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

连接 AI 助手

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

本实战将帮助你理解

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

准备条件和样例

开始前需要：

• 一个已经在 网页版对话 中确认模型返回有效回复的模型凭证和模型。凭证出现在选择列表中、模型名称已经显示，只表示相应配置已经加载；尚未验证实际回复时，先运行创建第一个智能体并完成基础验证。
• 创建智能体模板、智能体实例、WebSocket 渠道账号和相应 Token 的权限。
• Node.js 22 或更高版本，用于运行带原生 fetch 和 WebSocket 的样例调用方。
• 服务提供方给出的 HTTP 接口的 HTTPS 基址和完整 WSS 地址，以及能访问这两个地址的受控运行环境。不要从控制台地址推导主机名。

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

• user-toolkit.json：用户工具定义。
• tickets.json：虚构工单数据。
• ticket-assistant-client.mjs：业务调用方。
• test-cases.json：固定验收用例。
• README.md：运行方法、版本兼容性和客户端限制。

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

下面可以直接查看或下载这份清单，核对样例文件和校验值。

manifest.json·JSON·1 KiB下载原始文件

{
  "name": "agentworks-ticket-assistant",
  "version": "2.0.0",
  "description": "Synthetic user-tool contract, ticket data, Bridge HTTP/WebSocket client, and acceptance cases for the AgentWorks business-tool recipe.",
  "bundle": {
    "path": "ticket-assistant-v2.zip",
    "sha256": "f6e868052c0913367381de58e12f21b1586f07e21b47f24372dd052a7d223f54"
  },
  "files": [
    {
      "path": "user-toolkit.json",
      "sha256": "50f6aec040e22aa43609da06f9bccec8f67d03f39cb8fa684fc4c250f88edf0a"
    },
    {
      "path": "tickets.json",
      "sha256": "946eaa299d13a2ddf978a9ee626fc4eba4d9d24f107cdd73cfa66a9ba5e23682"
    },
    {
      "path": "test-cases.json",
      "sha256": "a99b82abd99decac803dff0bc0d6c29363cd48195a8647cccbe3040948de13fb"
    },
    {
      "path": "ticket-assistant-client.mjs",
      "sha256": "d93d4a85ebeadc3ef2029f462ccb22ce6e3687cadac9b5526d12cb6c55db3275"
    },
    {
      "path": "README.md",
      "sha256": "abf11a70f7575fba74823a32e71e84f82550b710f2ed378eab014b0418b19d20"
    }
  ]
}

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

注意

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

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

理解谁执行工具

图表预览

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

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

创建工单助手

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

   创建智能体模板

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

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

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

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

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

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

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

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

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

   注意

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

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

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

9. 创建名为 recipe-ticket-assistant-test-v2 的智能体实例，按网页版对话验证步骤确认实例能够返回有效回复，再继续配置业务接入。

创建接入账号和 Token

1. 打开 渠道账号，按创建 WebSocket 渠道账号创建 recipe-ticket-assistant-channel-v2。

   打开渠道账号

2. 选择 绑定 Agent 实例（默认），绑定 recipe-ticket-assistant-test-v2。

3. 为本实战创建独立 wst_ Token，立即保存一次性显示的明文；不要写入样例文件或版本控制。

4. 核对服务提供方给出的 HTTP 基址和 WebSocket 地址属于同一部署。账号负责路由到目标实例，不在消息请求中另传实例 ID。

已有同一实例的 WebSocket 账号时，在该账号下创建独立 Token，不重复创建账号。参见为客户端创建 Token。

运行工具闭环

在解压后的样例目录中运行。把两个地址占位符替换为服务提供方给出的地址：HTTP 基址填写 /api/bridge/v1/ 之前的部署地址与可选部署前缀，脚本会追加方法路径；WebSocket 使用完整 WSS 地址。测试用户标识仅用于本实战：

export AGENTWORKS_BRIDGE_BASE_URL="{bridge_http_base_url}"
export AGENTWORKS_BRIDGE_WS_URL="{bridge_websocket_url}"
export AGENTWORKS_USER_ID="recipe-test-user"
printf 'WebSocket Token: '
read -s AGENTWORKS_TOKEN
printf '\n'
export AGENTWORKS_TOKEN
node ticket-assistant-client.mjs INC-1024

粘贴 wst_ Token 并按 Enter。客户端先建立事件连接，经 HTTP 提交消息，再订阅返回的 context_key。收到 get_ticket_status 中断后，它检查工具和参数，读取 tickets.json，通过 RespondInterrupt 返回 RESPOND，并等待主智能体终态。

确认：

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

完成结果：你的业务调用方实际执行了工单查询，智能体使用返回的数据完成回答。仅出现消息已接收或一段正确文字，不足以证明用户工具闭环成功。

样例为每次运行创建独立会话，等待上限为 120 秒。它不会自动批准工具，也不会在断线或游标重建时自动重试业务操作；遇到这些情况会停止并报告失败。超时或客户端退出不代表远端运行已取消。

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

可选：验证不存在的工单

运行：

node ticket-assistant-client.mjs INC-9999

调用方返回 ERROR，并以 ticket INC-9999 was not found 报告查询失败；如果智能体返回了失败说明，样例会先输出该说明。无论智能体如何结束，都不应编造工单状态。

完成后运行 unset AGENTWORKS_TOKEN。test-cases.json 中的“缺少工单编号”可在支持自定义输入的业务客户端中验证；本页固定客户端只接受 INC-0000 格式的编号。未知工具由允许列表拒绝，不需要修改契约来完成首次实战。

如果验证没有通过

• 连接或鉴权失败：检查部署地址、账号绑定、账号状态和 Token；不要用旧 Agent API Token 或模型 API Key。
• 提交成功但没有回复：确认 subd.d.ok 为 true，事件的 sid 和 mid 与当前请求匹配。
• 未收到工具就失败，或模型没有选择工具：先检查模型凭证和实际回复，再核对实例是否使用当前用户工具定义。
• 调用一直等待工具结果：核对 HTTP RespondInterrupt 的 context_key、msg_id、interrupt_id，并检查 success_response。不要把 sid 填入 chat_id。
• 收到人工审批请求：本样例不会自动批准。核对模板权限，使用可信客户端审查待处理操作，或为独立测试实例配置符合团队策略的最小权限。
• 断线、超时或恢复失败：记录会话标识、请求标识和时间，核对远端及业务结果；不要直接重发有副作用的真实业务请求。
• 工具结果已回传但答案不正确：检查 response_data 与 outputSchema，以及实际返回的状态和负责团队。

排障记录中不要保存 Token、模型 API Key 或不必要的业务数据。修复后重新运行 INC-1024。详见管理会话、运行和中断。

调整为自己的系统

首次调用成功后，再替换工具契约和处理程序：

• 查询真实工单 API：替换 executeTicketLookup，保留工具允许列表、参数校验、业务用户授权和超时。
• 创建、更新或删除数据：增加业务幂等、审计和必要的人工确认，不只依赖提示词。
• 面向浏览器提供界面：把 wst_ 和 API 客户端留在后端，由后端验证登录用户并维护会话映射。
• 通过飞书或 QQ 直接使用：改用平台工具包或 MCP；渠道不会代运行用户工具代码。
• 工具已有远程 MCP Server：使用 MCP 连接，不再由本地调用方执行该工具。
• 不同实例需要不同契约：使用 创建实例时可配置，并分别验证实例契约与实际客户端实现。

准备上线和清理

上线前补充业务身份和权限、持久会话映射、事件游标和重连恢复、串行请求队列、幂等、审计、Token 轮换和失败告警。本页最小客户端不是生产级会话恢复实现。参见用户工具包、协议恢复规则和将智能体投入生产。

清理时：

1. 停止本地客户端，核对任务和工具操作是否仍在运行。
2. 停用并删除本实战专用 Token；不要影响同一账号其他业务客户端。
3. 专用渠道账号不再使用时，停用并删除它；共享账号只清理本次创建的 Token。
4. 删除测试智能体实例和模板。
5. 清理本地临时文件和环境变量，确认未留下凭证。

停用 Token 不等于所有既有连接立即断开；需要停止整个账号时，先确认对其他客户端的影响。