SDK y CLI
@azothos/sdk y la API REST v1
Dos vías de entrada. Envía las llamadas a través de la pasarela gobernada con cualquier cliente compatible con OpenAI — la vía en la que se aplican las reglas y se sellan las decisiones — o notifica las llamadas hechas en otros lugares con los wrappers del SDK.
Instalación
npm install @azothos/sdkNode.js 18 o posterior, y una clave API de Ajustes › Acceso (az_live_… o az_test_…). El SDK comprueba la forma de la clave antes de cualquier petición.
A través de la pasarela
Apunta un cliente de OpenAI a https://www.azothos.ai/api/v1 — o a tu propio host, si es autoalojado. azothGatewayHeaders construye las cabeceras de Azoth y lanza un error ante un valor que la pasarela rechazaría:
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 }),
});
await openai.chat.completions.create(body, {
headers: azothGatewayHeaders({ decisionRef: creditFileId, subjectZone: 'FR' }),
});X-Azoth-UsecaseusecaseId: el sistema (mandato) al que sirve la llamadaX-Azoth-Decision-RefdecisionRef: la decisión de negocio, un id opacoX-Azoth-Subject-ZonesubjectZone: dónde están las personas afectadas — FR, US-CA, EU…X-Azoth-End-UserendUser: el visitante de un sistema público, un id opaco, nunca un correo electrónicoX-Azoth-Challenge-PassedchallengePassed: el nonce de una verificación que el visitante superóX-Azoth-Localeen, fr, es, zh o arX-Azoth-On-Behalf-OfRecibos
receiptOf(response | body | headers) lee un recibo, decodeReceipt(token) sus campos (claims) y verifyReceipt(token, jwks) comprueba su firma con WebCrypto. Desde el SDK 1.2.0 también rechaza un recibo firmado en el momento o después del compromiso declarado de su clave (el status y el compromised_at de la clave): las claves del espacio de trabajo y su estado se publican en /api/proof/keys/<workspaceId>.
Rechazos y dispensas
parseRefusal(err) lee el bloque de rechazo, formatRefusal da un texto para mostrar, alternativeRequest(option) las cabeceras y el cambio de cuerpo de una opción conforme, y requestException(…) pide al propietario de la regla una dispensa por tiempo limitado. Ante un 428, exhaustionChallengeOf(err) devuelve la verificación que hay que superar.
import { parseRefusal, formatRefusal, alternativeRequest, requestException } from '@azothos/sdk';
try {
await openai.chat.completions.create(body, { headers: { 'X-Azoth-Locale': 'fr' } });
} catch (err) {
const refusal = parseRefusal(err);
if (!refusal) throw err;
showToUser(formatRefusal(refusal));
const option = refusal.alternatives[0];
if (option) {
const { headers, body: change } = alternativeRequest(option);
await openai.chat.completions.create({ ...body, ...change }, { headers }); // governed again in full
} else if (refusal.exception.available) {
await requestException({
apiKey: process.env.AZOTH_API_KEY,
refusal,
justification: 'Quarter-end audit needs this model this week',
});
}
}También en el SDK
createClientVault: conserva el contenido de un sistema en modo bóveda cifrado con tu clave, en tu almacenamiento; Azoth solo sella los hashes.groundingSources(passages): los pasajes en los que debe basarse una respuesta, para la comprobación de anclaje.runReferenceSet: ejecuta un conjunto de referencia guardado en tu bóveda y envía su recibo, para el control de cambios de modelo.
Notificar llamadas hechas fuera de la pasarela
wrapOpenAI, wrapAnthropic, wrapBedrock, wrapMistral y wrapGemini envuelven tu cliente existente: cada llamada se notifica a Azoth — coste, latencia, tokens — en segundo plano, con spans OpenTelemetry gen_ai.* opcionales. Estas llamadas se observan, no se gobiernan: ninguna regla puede detenerlas.
wrapOpenAI
import OpenAI from 'openai';
import { AzothClient, wrapOpenAI } from '@azothos/sdk';
const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const openai = wrapOpenAI(new OpenAI(), azoth, {
provider: 'openai',
model: 'gpt-4o-mini',
agentId: 'support-bot', // the spend line it is attributed to
workflowId: 'ticket-triage',
});wrapAnthropic
import Anthropic from '@anthropic-ai/sdk';
import { AzothClient, wrapAnthropic } from '@azothos/sdk';
const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const anthropic = wrapAnthropic(new Anthropic(), azoth);Opciones del cliente
apiKeybaseUrlhttps://www.azothos.ai; tu propio host si es autoalojadoworkspaceIdclient.io.* y las simulacionesenableTracing · tracertimeoutMsmaxRetriesRetry-AfterAPI REST v1
La mayoría de las rutas /api/v1 requieren una clave API: Authorization: Bearer <key> o X-Azoth-API-Key: <key>. Una clave con ámbitos solo alcanza las rutas que corresponden a sus ámbitos. Las lecturas propias del panel — /api/v1/me y las lecturas de GreenOps — requieren en cambio una sesión iniciada, nunca una clave. Cada ruta, cómo se autentica, sus campos y sus respuestas están en la referencia de la API, publicada también como archivo OpenAPI.
POST /api/v1/chat/completionsPOST /api/v1/chatprovider explícito, alternativas de respaldo y streamingPOST /api/v1/infer/resumeGET /api/v1/journalGET /api/v1/journal/export?format=dossierPOST /api/v1/decisions/exportPOST /api/v1/exceptionsPOST /api/v1/insights/{tool}insights:readPOST /api/v1/mcpGET /api/v1/usage · /api/v1/report · /api/v1/budgetsPOST /api/ingestGET /api/proof/keys/{workspaceId}POST /api/v1/chat
Authorization: Bearer <key>
{
"provider": "anthropic", // openai | anthropic | mistral | gemini | azure_openai
"model": "claude-haiku-4-5", // | openrouter | ollama | deepseek | huggingface | internal
"messages": [{ "role": "user", "content": "Summarise this document." }],
"maxTokens": 1024,
"stream": false,
"fallbackProviders": [{ "provider": "mistral", "model": "mistral-small-latest" }]
}Respuestas que cabe esperar
400 validation_failedfield nombra el campo y error dice por qué.401402 budget_exceeded202 human_review_requiredapproval_request_id.403policy_blocked, usecase_unresolved, usecase_not_approved, usecase_prohibited, usecase_archived, mandate_suspended, mandate_expired, kill_switch_active, jurisdiction_blocked, sovereignty_blocked, egress_blocked…428 exhaustion_challenge_required429exhaustion_slow o exhaustion_blocked: retryAfterMs en el cuerpo, Retry-After en las cabeceras.503 governance_errorUn rechazo de gobernanza se sella y lleva su recibo. Los rechazos por agotamiento de costes, en cambio, se cuentan y se sellan en cada cambio de nivel. Cada code se explica en Códigos de error, adonde lleva el doc_url de una respuesta.