文档中心

Appearance

✨费用中心控制台

构建可调用业务系统的工单助手 ​

本实战构建一个通过 Invoke API 使用的工单助手。智能体负责判断何时查询工单并生成参数；调用方接收用户工具中断，执行本地的虚构工单查询，再把结果返回给同一会话。完成后，智能体能够回答真实工具结果，同时拒绝未知工具和不存在的工单。

准备条件和样例 ​

开始前需要：

  • 一个可用的模型凭证和模型。
  • 创建智能体模板、智能体实例和 Agent API Token，以及开启 API 调用的权限。
  • Node.js 18 或更高版本，用于运行样例调用方。
  • 可以访问一体化智能体运行与协同平台（AgentWorks）Invoke API 的网络环境。

下载并解压工单助手样例包。压缩包包含：

  • user-toolkit.json：用户工具定义。
  • tickets.json：虚构工单数据。
  • ticket-assistant-client.mjs：Invoke 调用方。
  • test-cases.json：固定验收用例。

可以另外查看样例清单和校验值。

本文使用固定的 recipe-ticket-assistant-* 名称，便于识别和清理实战资源。如果环境中已经存在同名资源，请为智能体模板、实例和 Token 统一追加简短后缀，例如 -team-a；不要修改或复用来源不明的同名资源。

样例只读取虚构数据，不会连接真实工单系统。把它改为真实业务调用前，必须在调用方补充身份、权限、超时和审计控制。

验证模型调用 ​

创建工单助手之前，使用创建第一个智能体并完成基础验证中创建的最小智能体实例发送一条消息，并确认模型返回有效回复，以此作为凭证验证结果。模型凭证出现在选择列表中、模型名称已经显示或 Playground 显示 已连接，只表示相应配置已经加载。

如果最小智能体没有回复，或返回模型凭证、模型服务相关错误，请先由凭证负责人修复模型链路。用户工具中断发生在模型选择工具之后，因此模型调用尚未成功时，修改 user-toolkit.json、Invoke 调用方或 Token 都不能解决问题。

理解谁执行工具 ​

用户工具包只把 get_ticket_status 的名称、用途和输入输出结构提供给智能体。ticket-assistant-client.mjs 才是执行工具的一方。添加沙箱不会让沙箱自动执行这个用户工具。

按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。

创建工单助手 ​

  1. 打开创建智能体模板页面。

    创建智能体模板

    也可以打开 智能体模板，再选择 创建智能体模板。

  2. 将 模板名称 设为 recipe-ticket-assistant-v1，选择可用的 模型凭证和模型。

  3. 在 系统提示词 中使用以下内容：

language-text
你是工单查询助手。
用户提供具体工单编号并询问状态时，必须调用 get_ticket_status，不要猜测。
用户没有提供工单编号时，先询问编号，不要调用工具。
工具返回错误时，明确说明没有取得工单状态，不要编造替代结果。
  1. 在 插件配置 中单击 添加插件。
  2. 在 类型 中选择 用户工具包。
  3. 把 user-toolkit.json 的完整内容粘贴到 默认值，单击 格式化。
  4. 本实战不选中 创建实例时可配置，让测试实例使用同一份固定工具契约。
  5. 选择 创建智能体模板，并在 插件 中确认用户工具包已经关联。
  6. 创建名为 recipe-ticket-assistant-test-v1 的智能体实例，打开实例的 Playground，确认页面显示 已连接。

工具描述明确要求“具体工单状态必须调用”和“只读取”，输入 schema 只接受 INC-0000 形式的编号。模型是否真的选择工具仍需通过运行测试确认。

检查点 1：智能体实例已经创建，Playground 显示 已连接，来源智能体模板的插件页签显示用户工具包。

开启 API 调用并创建 Token ​

智能体实例 API 调用页面中的调用状态、Token 管理、HTTP 和 SSE 调用地址

  1. 打开测试智能体实例的 API 调用。

  2. 开启 API 调用状态。

  3. 在 概览 的 调用地址 中复制完整 Invoke URL。

  4. 打开 凭证管理。

    打开凭证管理

    也可以从控制台左侧导航进入 凭证管理。

  5. 进入 Agent API Token，选择 新建 Agent Token，在 Token 名称 中输入能识别本次实战的名称，通过 绑定 Agent 实例 选择 recipe-ticket-assistant-test-v1，并按团队策略设置 有效期。

  6. 选择 创建 Token，立即把返回的 Token 明文放入当前终端会话使用的安全位置。Token 明文只显示一次，不要把它写入样例文件、命令脚本或版本控制。

本实战从本地调用方访问 Invoke API，因此使用绑定到目标智能体实例的 Agent API Token。临时调试 Token 适合控制台中的短时调试；不要把它部署到持续运行的调用服务。Token 类型和生命周期参见管理 API 调用和 WebSocket Token。

检查点 2：API 调用已开启，并取得一个已绑定测试智能体实例且仍在有效期内的 Agent API Token。

运行工具闭环 ​

在下载样例的目录中设置临时环境变量：

language-bash
export AGENTWORKS_INVOKE_URL="{invoke_url}"
printf 'Agent API Token: '
read -s AGENTWORKS_TOKEN
printf '\n'
export AGENTWORKS_TOKEN
node ticket-assistant-client.mjs INC-1024

粘贴 Agent API Token 并按 Enter。样例调用方会：

  1. 请求 /api/agents/Invoke，要求查询 INC-1024。
  2. 接收 get_ticket_status 的 pending_interrupt。
  3. 拒绝不在允许列表中的工具，并校验工单编号格式。
  4. 从 tickets.json 读取虚构工单。
  5. 使用同一个 session_id 和中断 ID 返回 RESPOND。
  6. 输出智能体的最终回答。

运行日志应依次显示收到 get_ticket_status、返回 处理中，以及会话完成。最终回答应说明 INC-1024 正在处理，并提到网络支持组；措辞可以变化，但状态和负责团队必须来自工具结果。

检查点 3：调用完成，调用方经历一次用户工具中断，最终回答使用 tickets.json 中的状态和负责团队。

执行失败练习 ​

不存在的工单 ​

运行：

language-bash
node ticket-assistant-client.mjs INC-9999

调用方会向中断返回 ERROR，然后以 ticket INC-9999 was not found 结束。如果智能体实例同时返回了失败说明，样例会先输出该说明。无论 Invoke 以 completed 还是 error 结束，都不应出现一个编造的工单状态。

完成所有调用测试后，运行 unset AGENTWORKS_TOKEN 清除当前终端会话中的 Token。

缺少工单编号 ​

在控制台 调试 页签或自己的调用方中发送 帮我查询工单状态。智能体应先询问工单编号，不应发出 get_ticket_status 中断。

未知工具 ​

样例调用方只允许 get_ticket_status。把同一模式用于真实系统时，调用方必须在执行任何业务操作前检查工具名称、参数 schema 和当前用户权限。不能因为工具名称来自模型就直接执行。

模型调用在工具前失败 ​

如果样例在输出 received get_ticket_status 之前以 Invoke mission failed 结束，先查看同一行中的错误摘要。模型凭证被拒绝、模型不可用或模型服务不可访问时，智能体还没有发起用户工具中断，此时不应修改 user-toolkit.json 或本地查询函数。

在 凭证管理 中确认智能体模板使用的模型凭证仍然有效，并在智能体模板编辑页确认模型仍可选择。由凭证负责人更新失效凭证后，先重新运行 INC-1024 固定用例，再继续失败练习。排障记录中不要保存 API Key 或 Agent API Token。

调整为自己的系统 ​

根据业务工具的执行位置、风险和接入方式，替换样例中的工具契约与调用方实现。

  • 查询真实工单 API：使用经过鉴权和超时控制的 API 调用替换 executeTicketLookup，保持工具契约和允许列表检查。
  • 创建、更新或删除业务数据：在业务系统增加权限校验、幂等键、审计和人工确认，不要只依赖提示词限制。
  • 使用 WebSocket 接入：保留工具契约，改为接收 message_stream_reply.interrupt 并发送 interrupt_response。
  • 通过飞书或 QQ 直接使用：改用平台工具包或 MCP；这些渠道不会运行用户工具代码。
  • 工具已经由远程 MCP Server 提供：使用 MCP 连接，让 AgentWorks 调用 MCP 工具，不再由 Invoke 调用方处理中断。
  • 不同智能体实例需要不同工具契约：选中创建实例时可配置，并对每个实例配置执行同一组契约测试。

准备上线和清理 ​

上线前至少补充：调用用户身份传递、业务权限检查、参数校验、超时和重试边界、幂等控制、工具和 API 审计、Token 轮换、失败告警，以及固定成功和失败用例。参见定义用户工具包、管理 API 会话、调用任务和中断和将智能体投入生产。

清理本实战时：

  1. 在 API 调用状态 中关闭测试智能体实例的 API 调用。
  2. 在 Agent API Token 中选择 停用，然后选择 删除，移除本实战创建的 Token。
  3. 删除测试智能体实例。
  4. 删除测试智能体模板。
  5. 删除本地样例目录中的临时文件，并确认环境中没有保留 Token。

关闭 API 调用和撤销 Token 应在删除智能体实例前完成，避免遗留仍可使用的调用凭证。