文档中心

Appearance

控制台

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

本实战构建一个通过 Invoke API 使用的工单助手。智能体选择 get_ticket_status 并生成工单编号，样例调用方接收用户工具中断、查询本地虚构工单数据，再把结果返回给同一会话。完成后，智能体会根据调用方实际返回的状态和负责团队回答用户。

本实战将帮助你理解 ​

  • 用户工具包如何向模型说明可用工具，而实际业务代码为什么仍由 Invoke 调用方运行。
  • 调用方如何使用同一个 session_id 和中断 ID 返回工具结果，让智能体继续完成回答。
  • 为什么调用方必须先检查工具名称、参数和用户权限，不能直接执行模型提出的操作。

准备条件和样例 ​

开始前需要：

  • 一个已经在 Playground 中确认模型返回有效回复的模型凭证和模型。凭证出现在选择列表中、模型名称已经显示或页面显示 已连接，只表示相应配置已经加载；尚未验证实际回复时，先运行创建第一个智能体并完成基础验证。
  • 创建智能体模板、智能体实例和 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；不要修改或复用来源不明的同名资源。

注意

先使用虚构工单完成工具闭环

样例只读取虚构数据，不会连接真实工单系统。不要把生产 Token、用户数据或真实工单内容写入样例文件。改接真实业务系统前，必须在调用方补充身份、权限、超时和审计控制。

理解谁执行工具 ​

图表预览

用户工具包只把 get_ticket_status 的名称、用途和输入输出结构提供给智能体。ticket-assistant-client.mjs 才会检查工具名称和参数、读取 tickets.json，并返回结果。添加沙箱不会让沙箱自动执行这个用户工具。参见用户工具包中的工具在哪里运行？。

下面先由 AgentWorks 配置者创建智能体和 Token；到“运行工具闭环”时，再由业务调用方运行样例并处理中断。

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

创建工单助手 ​

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

    创建智能体模板

    也可以在 AgentWorks 管理控制台中打开 智能体模板，再选择 创建智能体模板。

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

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

    language-text
    你是工单查询助手。
用户提供具体工单编号并询问状态时，必须调用 get_ticket_status，不要猜测。
用户没有提供工单编号时，先询问编号，不要调用工具。
工具返回错误时，明确说明没有取得工单状态，不要编造替代结果。

  4. 在 插件配置 中单击 添加插件，在 类型 中选择 用户工具包。

  5. 把 user-toolkit.json 的完整内容粘贴到 默认值，单击 格式化。

    工具描述要求模型在查询具体工单时调用 get_ticket_status，输入 schema 只接受 INC-0000 形式的编号。格式化只检查 JSON 语法；工具是否被正确选择，还需要通过后面的真实调用确认。

  6. 不选中 创建实例时可配置，让本实战的测试实例使用同一份固定工具契约。

  7. 关闭默认开启的 启用文件系统，不添加其他插件或工具权限。本实战只验证由调用方执行的 get_ticket_status。

    注意

    批准工具也不会执行工单查询

    模型选择用户工具后，调用方必须执行工具，并使用 RESPOND 或 ERROR 返回结果。即使在工具权限中把工具设为需要人工确认，批准也只允许调用继续，不能替调用方执行工单查询。参见API 返回 pending_interrupt 后，应选择哪个响应动作？。

  8. 选择 创建智能体模板，并在 插件 中确认用户工具包已经关联。

  9. 创建名为 recipe-ticket-assistant-test-v1 的智能体实例，打开实例的 Playground，确认页面显示 已连接。

开启 API 调用并创建 Token ​

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

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

  2. 开启 API 调用状态。

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

  4. 打开 凭证管理。

    打开凭证管理

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

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

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

  6. 选择 创建 Token，立即把返回的 Token 明文放入当前终端会话使用的安全位置。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。样例调用方会接收 get_ticket_status 中断，检查工具名称和 INC-1024 参数，从 tickets.json 读取虚构工单，再使用同一个 session_id 和中断 ID 返回 RESPOND。

确认：

  1. 日志先显示 received get_ticket_status for INC-1024，再显示 returning status 处理中。
  2. 日志显示会话完成。
  3. 最终回答说明 INC-1024 正在处理，并提到网络支持组；措辞可以变化，但状态和负责团队必须来自工具结果。

完成结果：Invoke 调用方完成一次用户工具中断闭环，智能体使用 tickets.json 中实际返回的状态和负责团队回答用户。

如果不继续执行下一节的可选练习，请运行 unset AGENTWORKS_TOKEN，清除当前终端会话中的 Token。

可选：验证不存在的工单 ​

下面的练习是可选项，用于验证调用方在业务数据不存在时不会把工具执行当作成功。它不阻塞前面的首次成功。

运行：

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

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

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

样例包中的 test-cases.json 还列出了“缺少工单编号”用例，适合在需要扩大回归范围时使用。未知工具拒绝由样例调用方的允许列表实现，不需要故意修改工具契约来完成首次实战。

如果验证没有通过 ​

  • 在出现 received get_ticket_status 前返回 Invoke mission failed：模型尚未发起用户工具中断。先使用最小智能体重新验证模型凭证和模型服务，不要修改 user-toolkit.json 或本地查询函数。
  • 模型没有选择 get_ticket_status：确认智能体模板已关联用户工具包，智能体实例已采用最新配置，并核对工具名称、描述和输入 schema。
  • 调用停在 pending_interrupt：确认调用方使用同一个 session_id 和正确的中断 ID 返回了 RESPOND 或 ERROR。参见响应中断。
  • 工具结果已经返回，但最终回答不正确：确认 response_data 与 outputSchema 一致，并检查调用方实际返回的状态和负责团队。
  • Invoke 返回 HTTP 200，但样例仍报告失败：检查响应中的业务状态和错误信封；HTTP 状态码本身不能证明调用成功。参见API 返回 HTTP 200 就表示业务成功吗？。

排障记录中不要保存 API Key 或 Agent API Token。修复后先重新运行 INC-1024 固定用例，再决定是否执行可选失败练习。

调整为自己的系统 ​

首次调用成功后，再根据业务工具的执行位置、风险和接入方式替换工具契约与调用方实现。

  • 查询真实工单 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 应在删除智能体实例前完成，避免遗留仍可使用的调用凭证。