# @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 或邮件地址——须使用允许指明人员的服务密钥；需自行设置（[人员归属](https://www.azothos.ai/zh/docs/admin#attribution)）

## 回执

`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 参考](https://www.azothos.ai/zh/docs/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` 都在[错误代码](https://www.azothos.ai/zh/docs/errors)中有说明，回答中的 `doc_url` 即指向那里。
