Primeros pasos
Inicio rápido
Envía tu primera llamada a través de la pasarela de Azoth, conserva su recibo y encuentra su decisión sellada — en unos cinco minutos, sin cambiar tus prompts.
Necesitas un espacio de trabajo de Azoth y una clave de proveedor guardada en Ajustes › Proveedores y modelos. Los ejemplos del SDK requieren Node.js 18 o posterior.
En Ajustes › Acceso, crea una clave API y cópiala en AZOTH_API_KEY: solo se muestra una vez. Los espacios de trabajo gratuitos reciben claves az_test_…; los planes de pago, az_live_….
La pasarela habla el formato de chat de OpenAI en /api/v1/chat/completions. -D - muestra las cabeceras de la respuesta, donde viaja el recibo.
curl -sS -D - https://www.azothos.ai/api/v1/chat/completions \
-H "Authorization: Bearer $AZOTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{ "role": "user", "content": "Say hello in one word." }]
}'
# HTTP/2 200
# x-azoth-receipt: eyJhbGciOiJFZERTQSIs…
# x-azoth-provider: openai
# x-azoth-model: gpt-4o-mini
# x-azoth-cost-usd: 0.00000330Cambia la URL base y la clave — nada más en tu código. azothGatewayHeaders de @azothos/sdk añade las cabeceras opcionales de Azoth y rechaza un valor que la pasarela rechazaría. .withResponse() también te da las cabeceras de la respuesta, donde viaja el recibo.
import OpenAI from 'openai';
import { azothGatewayHeaders } from '@azothos/sdk';
const openai = new OpenAI({
baseURL: 'https://www.azothos.ai/api/v1',
apiKey: process.env.AZOTH_API_KEY,
defaultHeaders: azothGatewayHeaders({ usecaseId: process.env.AZOTH_USECASE_ID }),
});
const { data, response } = await openai.chat.completions
.create({
model: 'gpt-4o-mini',
messages: [{ role: 'user', content: 'Say hello in one word.' }],
})
.withResponse();
console.log(data.choices[0].message.content);
console.log(response.headers.get('x-azoth-receipt'));El paquete openai funciona igual: cambia base_url y la clave. with_raw_response conserva las cabeceras de la respuesta, donde viaja el recibo.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://www.azothos.ai/api/v1",
api_key=os.environ["AZOTH_API_KEY"],
)
raw = client.chat.completions.with_raw_response.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(raw.parse().choices[0].message.content)
print(raw.headers.get("x-azoth-receipt"))Cada respuesta que no se transmite en streaming, servida o bloqueada, lleva un recibo firmado en X-Azoth-Receipt — y en azoth.receipt dentro de un cuerpo JSON servido. Identifica la decisión sin ningún contenido: guárdalo con tus registros. Una respuesta en streaming lleva X-Azoth-Trace-Id en su lugar: su decisión se sella cuando termina el streaming.
En Pruebas › Decisiones, la llamada aparece con su resultado, sus reglas y su derecho. Verificarlo yo mismo abre el verificador sin conexión: pega el recibo y elige el expediente.
Cómo funciona
Una llamada a través de la pasarela pasa por estos pasos, en este orden:
- Se comprueban la clave y el cuerpo. Un sistema expuesto al público recibe primero su nivel de protección contra el agotamiento de costes (sistemas públicos).
- La llamada se vincula a su mandato: la cabecera
X-Azoth-Usecase; si no, el agente, el conector o la clave a la que está vinculada; si no, el mandato por defecto del espacio de trabajo. - Se ejecutan las reglas: la parada de emergencia, el estado del mandato, los presupuestos, la soberanía, las reglas de política, el derecho aplicable, la aprobación humana.
- El modelo responde, en el proveedor que las reglas permiten. El enrutamiento y la caché son enriquecimientos, dentro de esas reglas.
- La decisión se sella en el diario encadenado por hash del espacio de trabajo — rechazos incluidos — y la respuesta sale con su recibo.
Perfiles de gobernanza
El rigor con que se trata una llamada sin mandato aprobado depende del modo de gobernanza: el más estricto entre el del despliegue (GOVERNANCE_PROFILE) y el que el espacio de trabajo eligió en Ajustes › Organización — un espacio de trabajo puede endurecerlo, nunca relajarlo (modo de gobernanza). observe (Observar), el valor por defecto, sella y sirve; govern (Gobernar) además alerta; enforce (Aplicar) rechaza. Un mandato detenido, y un sistema clasificado como práctica prohibida, se rechazan en cualquier modo.