免费开始 →

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-Usecase
usecaseId:调用所服务的系统(授权)
X-Azoth-Decision-Ref
decisionRef:业务决策,一个不透明标识
X-Azoth-Subject-Zone
subjectZone:相关人员所在地——FR、US-CA、EU……
X-Azoth-End-User
endUser:公开系统的访客,一个不透明标识,切勿使用电子邮件地址
X-Azoth-Challenge-Passed
challengePassed:访客已通过的验证的 nonce
X-Azoth-Locale
拒绝说明的语言:en、fr、es、zh 或 ar
X-Azoth-On-Behalf-Of
调用所代表的人员——其 SCIM ID 或邮件地址——须使用允许指明人员的服务密钥;需自行设置(人员归属)

回执

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);

客户端选项

apiKey
必填:工作区 API 密钥
baseUrl
默认为 https://www.azothos.ai;自托管时为您自己的主机
workspaceId
client.io.* 和模拟功能必填
enableTracing · tracer
输出 OpenTelemetry span
timeoutMs
每次尝试的超时时间,默认 30 000
maxRetries
遇到 429 或 5xx 时的总尝试次数,默认 3;429 会遵循 Retry-After

REST API(v1)

大多数 /api/v1 路由需要 API 密钥:Authorization: Bearer <key> 或 X-Azoth-API-Key: <key>。带范围的密钥只能访问其范围所对应的路由。控制台自身的读取——/api/v1/me 和 GreenOps 读取——改用已登录的会话,绝不接受密钥。每个路由的认证方式、字段和应答都在 API 参考 中,也以 OpenAPI 文件形式发布。

POST /api/v1/chat/completions
受治理的网关,兼容 OpenAI
POST /api/v1/chat
受治理的网关,可显式指定 provider,支持备用方案和流式传输
POST /api/v1/infer/resume
在挂起的调用获批后运行它
GET /api/v1/journal
已封存的决策
GET /api/v1/journal/export?format=dossier
审计档案(ZIP)
POST /api/v1/decisions/export
按决策引用导出决策档案
POST /api/v1/exceptions
针对拒绝申请豁免
POST /api/v1/insights/{tool}
助手的只读工具,需要 insights:read 范围
POST /api/v1/mcp
受治理的 MCP 网关,使用绑定到智能体的密钥
GET /api/v1/usage · /api/v1/report · /api/v1/budgets
用量、支出报告、预算
POST /api/ingest
上报在网关之外进行的调用
GET /api/proof/keys/{workspaceId}
工作区的公钥(JWKS),无需密钥
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_failed
请求体验证失败:field 指明字段,error 说明原因。
401
API 密钥缺失、无效或已撤销。
402 budget_exceeded
预算在调用模型之前拒绝了该调用。
202 human_review_required
等待人工处理;使用其 approval_request_id 恢复。
403
被规则拒绝:policy_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_required
公开系统要求访客通过验证。
429
速率限制、exhaustion_slow 或 exhaustion_blocked:响应体中有 retryAfterMs,响应头中有 Retry-After。
503 governance_error
治理无法运行,部署以故障即关闭方式处理:请重试。

治理拒绝会被封存并附带回执。成本耗尽拒绝则只计数,并按级别变化封存。每个 code 都在错误代码中有说明,回答中的 doc_url 即指向那里。