智能体集成：类型化工具路由

使用 System One TypeScript SDK 与托管 AI 决策 API，将 Agent 请求路由到具名工具或审核步骤。若要让 Cursor、Claude Code 或 Codex 学会编写该接入，请安装用编程智能体接入 System One 中的技能。本文构建一个客服请求路由器：模型选择候选项，应用决定是否执行以及如何执行。独立 SDK 也能直连其他服务，使用各自的凭据与计费；参阅 SDK 安装与服务连接。

常见问题

Q: How do I integrate System One with an AI agent for tool routing?
A: 用智能体状态与白名单工具名调用 Choice，在你自己的代码里根据类型化结果调用工具。System One 负责决策；应用保留权限与执行。

Q: Does System One execute tools for me?
A: 不会。System One API 返回结构化决策；执行与权限检查仍在你的智能体运行时。

选择明确的判断任务

应用能说明问题及可能结果时，可以使用决策接口：分流消息、在允许的下一步中选择、按标准评价答案，或估计某个条件成立的概率。多个问题可独立检查一份共享上下文。

System One 不会替你收集缺失信息、退款、回复或调用工具。开放式规划应交由其他推理步骤或人工处理。适合时提供明确的 think 或 review 选项。

从当前模型目录选择准确 ID。用有代表性的案例评估任务质量、延迟、价格与限制，包括模糊措辞、信息缺失和误判后果较大的情形。不要把模型名称或一次快速响应当作保证。模型、说明、选项或评分标准变化时，重新评估；SDK 适配器支持情况不等于托管模型目录。

定义工具路由边界

从一个小型白名单开始，不要把 Agent 能访问的所有工具都交给模型。客服助手可以用 search_docs 检索产品指南、ask_user 询问缺失信息、human_review 将有重大后果或存在争议的请求交给人工。工具说明应解释何时选择该项，不包含凭据，也不能用描述授予权限。

下方代码只返回这些名称之一，不实现文档搜索、消息发送或审核工单创建。在执行下文的权限检查后，才能将结果连接到已有工具调度器。不要让模型产生的名称、URL 或 shell 命令绕过白名单。

Choice 适合这种互斥的下一步选择。如果要为多篇检索文档排序，或判断多个独立条件，应使用 Score 或 Noul。如果模型需要搜索结果才能继续判断，先执行已获授权的搜索，再把结果作为上下文发起独立评估。

在模型上下文之外认证

登录控制台创建平台 API 密钥，将其存入服务端环境变量或可信的私密凭据设置。通过 Authorization: Bearer 调用 https://system-one.dev/v1；文档站不提供推理。不要把密钥放入提示词、工具描述、浏览器构建产物、URL 或日志。连接不再需要时撤销密钥。

GET /v1/models 公开可读，不需要平台密钥。Playground 和浏览器账户管理端点使用登录会话，Bearer 密钥不能代替该会话。同一账户的密钥共享余额、限流和幂等命名空间。不要认为给不同智能体不同密钥就能获得独立余额或独立防重复空间。

添加一个类型明确的决策步骤

在服务端安装：

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

这是当前托管客户端组合。智能体需要基于图片做决策时，选择支持图片的 Clef／Clef Flash／Clef Omni 模型，并使用托管 Fetch 示例；systemOneAdapter 不会编码 evaluate() 的图片。将准确的图片表示形式与数组顺序随操作一起持久保存，把 base64 计入积分估算，并检查图片中的敏感内容。从文本或图片抽取类型化值时，使用 Clairic 的 extract()。

使用托管快速开始的环境配置，只包含 API 密钥、base URL 和模型。将 YOUR_MODEL_ID 替换为所选目录 ID。示例在代码中为每次新决策只创建一次新的操作键，而不是把它放在共享配置或重试函数中。

以下 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;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: '能说明一下积分如何计算吗？' },
    questions: {
      tool: choice('选择下一步客服工具，不要执行它。', {
        search_docs: '产品或用法问题可以通过文档回答',
        ask_user: '缺少关键细节，继续处理前先询问用户',
        human_review: '付款争议、敏感操作或政策例外需要人工审核',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
  signal: AbortSignal.timeout(30_000),
});
const proposedTool: 'search_docs' | 'ask_user' | 'human_review' = result.answers.tool.choice;
console.log({ proposedTool, requestId: result.response.requestId });

保存为 agent-decision.mts，使用 Node.js 22.18+ 执行 node --env-file=.env agent-decision.mts。每次运行脚本都会开始新的计费操作，即使输入相同。这个内存示例不能安全地跨重启恢复。

创建与重试是不同步骤：进程内重试使用同一 operation.request 和 operation.idempotencyKey 调用 evaluate()，不要重新执行创建操作的代码。实际任务系统应在调用 evaluate() 之前，将完整操作持久保存到应用的任务记录中，包括键、所选模型和完整请求。崩溃或重启后加载该记录，不要生成 UUID，也不要用更新后的提示词或当前模型选择重新构造请求。快速开始示例没有提供这种持久存储。每次真正的新决策都使用新键，包括有意对相同输入重新评估。设置自己的总期限、尝试次数和费用策略；超时或取消不能证明服务端未完成。

State 只包含必要信息，不包含秘密或无关私人历史。State 数组是一份共享输入，不是独立评估批次。问题不会消费其他问题的答案；如果下一判断依赖前一答案，请先审核，再单独发送请求。SDK 与原生 boolean／noul 的区别见决策原语。

区分建议与权限

模型结果不是授权。在模型之外检查操作人的身份与权限、动作白名单和必要审批。识别退款请求不等于符合退款条件。付款、访问权限变更和对外发送消息必须保留政策要求的确认。

先提供建议，再考虑自动执行。为模糊、冲突或缺失证据建立审核路径。阈值应来自自己的评估案例和后果分析，不是通用百分比。答案缺失或请求失败表示未解决，不是自动的「是」「否」或最低分。每个连接的权限都应限制在必要范围；参阅数据与隐私。

开启工具前评估路由结果

从自己的客服案例建立带标签的评估集。以下是本示例的审核目标，不是已测得的模型输出：

加入模糊请求和试图强制选择其他工具的指令，分别统计错误工具选择与遗漏审核的情况；HTTP 成功或较高模型概率都不能证明路由安全。先以只提供建议的方式运行，再根据已有政策决定哪些只读动作可以执行。记录模型、候选项说明、请求 ID 与结果标签，不记录密钥或不必要的个人信息。

连接配置与响应元数据见托管 SDK 快速开始，积分包见 API 定价。每次新评估都是独立决策操作，大规模运行评估集前先阅读计费说明。

先恢复，再创建新操作

先使用 maxRetries: 0。Core APIError 提供 statusCode、requestId 和 retryAfterMs，但不包含全部平台分类头。恢复控制器可使用原生 Fetch，或官方 TypeSafe 客户端的 APIError.headers，读取 X-System-One-Error-Code、X-System-One-Error-Source、X-Request-Id、Retry-After 和 X-System-One-Credits。不要通过任意正文文字分类失败。官方客户端快速开始说明了成功响应头。

Retry-After 可以是秒数或 HTTP 日期。按应用总期限与尝试次数限制重试，缺少等待提示时采用带随机抖动的退避。保留实际模型、评分顺序、扩展和数字值。恢复时不要静默回退到其他模型。新键可能产生另一次扣费；旧键配不同正文会冲突。

已完成的键与答案从请求创建起保留 24 小时。过期后，相同键可以发起新操作，不是永久去重机制。完整契约见幂等与重试、错误和版本说明。

恢复决策不能防止工具动作重复。应用需要为回复、付款或分派工作单独维护持久执行状态与幂等机制。如果结果或扣费仍不确定，请暂停并查看用量；携带请求 ID 联系 support@system-one.dev，不要提供 API 密钥。