接入智能体
选择边界明确的决策任务、在服务端认证，并在保留动作与计费控制权的前提下恢复请求。
本文将 SDK 与 System One 托管 API 配合使用，为 Agent 添加一个决策步骤。SDK 直连其他服务的方式见 SDK 文档，这些连接使用所选服务的凭据与计费方式。
何时使用 System One
当应用能够定义问题及可能结果时，可以使用决策接口：分流消息、从允许的工作流步骤中选择下一步、按有序标准评分，或估计某个条件成立的概率。一份共享状态配合多个命名问题，可以让应用一起检查相关判断。
开放式规划、收集新信息或难以明确候选项时，可以转交独立推理模型或人工处理。适合的任务可以显式提供 review 或 think 选项。概率是模型估计，不是工具执行授权；动作白名单、权限与动作要求的确认仍由应用负责。
托管 API 当前提供 Jev 兼容决策。请用自己的任务评估准确性和延迟；本指南不承诺通用质量或响应时间。SDK 为其他模型提供的独立适配器，不是本站的托管模型目录。
在模型上下文之外认证
登录控制台创建平台 API 密钥，将其保存到服务端秘密配置或环境变量。通过 Authorization: Bearer 调用托管 https://system-one.dev/v1 API，文档站不提供推理。密钥不要进入提示词、工具描述、浏览器构建产物、URL 或日志。运营者的上游密钥不是调用者的平台密钥。
GET /v1/models 同样需要平台密钥。浏览器管理端点与 Playground 使用 Better Auth 会话，Bearer 密钥不能替代该会话。API 密钥归属于账户，共享账户余额、限流与幂等命名空间。
添加一个决策步骤
在服务端安装独立包：
npm install @system-one-ai/core@0.6.0 @system-one-ai/transport-fetch@0.6.0 @system-one-ai/adapter-system-one@0.6.0以下 TypeScript 示例只选择建议的下一步，不执行工具：
import { createSystemOne, choice } from '@system-one-ai/core';
import { createFetchTransport } from '@system-one-ai/transport-fetch';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
const apiKey = process.env.SYSTEM_ONE_API_KEY;
if (!apiKey) throw new Error('请在服务端设置 SYSTEM_ONE_API_KEY。');
const client = createSystemOne({
apiKey,
baseURL: 'https://system-one.dev/v1',
adapter: systemOneAdapter,
transport: createFetchTransport(),
model: 'jev-latest',
timeoutMs: 30_000,
maxRetries: 0,
});
const operation = {
idempotencyKey: crypto.randomUUID(),
request: {
state: { message: '能说明一下积分如何计算吗？' },
questions: {
next: choice('选择下一步处理方式。', {
answer: '可根据已有文档回答',
think: '需要更多推理或信息',
review: '需要人工审核',
}),
},
},
};
// 发送前持久保存操作；结果未知时复用同一操作恢复。
const result = await client.evaluate(operation.request, {
headers: { 'Idempotency-Key': operation.idempotencyKey },
});
console.log({ proposedStep: result.answers.next.choice });运行示例会产生计费请求。发送前，请在应用自己的持久任务状态中保存操作；重新创建 UUID 会成为新操作。客户端超时或取消，不能证明服务端没有完成。总期限与重试预算由应用自行决定。
状态只包含判断所需的信息，不放入 API 密钥或无关私人历史。状态数组是一份共享输入，不是独立评估批次。SDK 会把 booleanQuestion 映射为原生 noul，但 core 0.6 对 nullable 输入的限制比原生 HTTP 更严，详见决策原语。
先恢复，再决定是否新建操作
初始设置使用 maxRetries: 0。Core APIError 提供状态、请求 ID 和重试延迟，不暴露平台分类响应头。恢复控制器应使用原生 HTTP，读取 X-System-One-Error-Code、X-System-One-Error-Source、X-Request-Id、Retry-After 与 X-System-One-Credits，不要通过任意错误正文判断提供方失败类型。
| 观察到的结果 | 应用处理 |
|---|---|
| 断开连接、超时或结果未知 | 在保留窗口内使用保存的键与相同的实际请求恢复，不推定已退款。 |
409 request_in_progress | 遵守 Retry-After，再使用同一键和请求体。 |
| 成功重放 | 使用答案。X-Idempotency-Replayed: true 和零扣费头标记重放，没有执行新推理。 |
409 idempotency_failed | 前次尝试失败且已退款。明确决定重试时，使用新键。 |
409 idempotency_conflict | 恢复原请求，或仅为确实不同的操作使用新键。 |
429 rate_limit_exceeded | 等待账户限流恢复后重试同一操作。提供方的 provider_busy 有独立退款与重试语义。 |
503 request_reconciliation_pending、410 idempotency_expired 或未解决的内部失败 | 保存原标识，检查账户用量后再决定是否发起其他操作。扣费头缺失不等于零。 |
| 认证、输入或余额不足错误 | 先解决原因再尝试。上游 401 不能证明平台登录会话已过期。 |
Retry-After 可能是秒数或 HTTP 日期。按应用总期限与最大次数限制重试，缺少延迟提示时使用带随机抖动的退避。保留相同的实际请求模型、评分顺序、扩展与精确数字值。新键可能再次扣费；旧键配不同正文则产生冲突。
已完成操作的键与答案从请求创建起保留 24 小时。过期后，同一键可以发起新操作，不提供永久去重。应用执行工具时，需要自己的持久操作状态与幂等机制，因为决策 API 不执行或去重这些动作。参阅 API 重试、版本说明与数据处理。