SDK 与 CLI
@azothos/sdk 与 v1 REST API
两种接入方式。使用任何兼容 OpenAI 的客户端通过受治理的网关发送调用——这是规则生效、决策被封存的路径——或使用 SDK 的封装器上报在其他地方进行的调用。
安装
npm install @azothos/sdk需要 Node.js 18 或更高版本,以及来自设置 › 访问权限的 API 密钥(az_live_… 或 az_test_…)。SDK 会在发出任何请求之前检查密钥格式。
通过网关
将 OpenAI 客户端指向 https://www.azothos.ai/api/v1——自托管时指向您自己的主机。azothGatewayHeaders 会构建 Azoth 请求头,并在遇到网关会拒绝的值时抛出错误:
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:调用所服务的系统(授权)X-Azoth-Decision-RefdecisionRef:业务决策,一个不透明标识X-Azoth-Subject-ZonesubjectZone:相关人员所在地——FR、US-CA、EU……X-Azoth-End-UserendUser:公开系统的访客,一个不透明标识,切勿使用电子邮件地址X-Azoth-Challenge-PassedchallengePassed:访客已通过的验证的 nonceX-Azoth-Localeen、fr、es、zh 或 arX-Azoth-On-Behalf-Of回执
receiptOf(response | body | headers) 读取回执,decodeReceipt(token) 读取其声明,verifyReceipt(token, jwks) 使用 WebCrypto 检查其签名。自 SDK 1.2.0 起,它还会拒绝在其密钥被声明泄露之时或之后签署的回执(依据密钥的 status 和 compromised_at):工作区的密钥及其状态公布在 /api/proof/keys/<workspaceId>。
拒绝与豁免
parseRefusal(err) 读取拒绝块,formatRefusal 给出可展示的文本,alternativeRequest(option) 给出合规选项所需的请求头和请求体变更,requestException(…) 向规则负责人申请有时限的豁免。收到 428 时,exhaustionChallengeOf(err) 返回需要通过的验证。
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',
});
}
}SDK 中的其他功能
createClientVault:以您的密钥加密保存保险库模式系统的内容,存放在您的存储中;Azoth 只封存哈希。groundingSources(passages):回答必须依据的段落,用于依据核查。runReferenceSet:运行保存在您保险库中的参考集并发送其回执,用于模型变更控制。
上报在网关之外进行的调用
wrapOpenAI、wrapAnthropic、wrapBedrock、wrapMistral 和 wrapGemini 封装您现有的客户端:每次调用都会在后台向 Azoth 上报(成本、延迟、token),并可选择输出 OpenTelemetry gen_ai.* span。这些调用只被观察,不受治理:任何规则都无法阻止它们。
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);客户端选项
apiKeybaseUrlhttps://www.azothos.ai;自托管时为您自己的主机workspaceIdclient.io.* 和模拟功能必填enableTracing · tracertimeoutMsmaxRetriesRetry-AfterREST API(v1)
大多数 /api/v1 路由需要 API 密钥:Authorization: Bearer <key> 或 X-Azoth-API-Key: <key>。带范围的密钥只能访问其范围所对应的路由。控制台自身的读取——/api/v1/me 和 GreenOps 读取——改用已登录的会话,绝不接受密钥。每个路由的认证方式、字段和应答都在 API 参考 中,也以 OpenAPI 文件形式发布。
POST /api/v1/chat/completionsPOST /api/v1/chatprovider,支持备用方案和流式传输POST /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:read 范围POST /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" }]
}可能收到的响应
400 validation_failedfield 指明字段,error 说明原因。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 或 exhaustion_blocked:响应体中有 retryAfterMs,响应头中有 Retry-After。503 governance_error治理拒绝会被封存并附带回执。成本耗尽拒绝则只计数,并按级别变化封存。每个 code 都在错误代码中有说明,回答中的 doc_url 即指向那里。