定义用户工具包

用户工具包用于把业务系统能够执行的操作描述为模型工具。你在智能体模板中定义工具名称、用途和输入输出结构；模型选择工具后，接入一体化智能体运行与协同平台（AgentWorks）的业务系统接收中断、执行实际业务操作，再把结果返回给智能体实例。

用户工具包只定义工具契约，不提供工具运行环境。它不会在 AgentWorks 中托管业务代码、API 地址或凭证。

选择工具执行方式

根据实际执行工具的一方，选择平台工具包、MCP 或用户工具包。

执行工具的一方	使用方式	适用情况
AgentWorks	平台工具包	控制台已有可选工具包，平台负责执行
外部 MCP Server	MCP	已有可通过 Streamable HTTP 访问的 MCP 工具服务
业务系统	用户工具包	业务系统需要校验参数、执行业务 API，并把结果返回给智能体

只有当业务系统能够完成工具中断的接收和响应闭环时，才使用用户工具包。

需要一个可以直接运行的只读工具闭环时，参见构建可调用业务系统的工单助手。该实战包含工具契约、虚构业务数据、Invoke 调用方和固定成功与失败用例。

确认接入方式

只有能够接收并响应工具中断的接入方式，才适合使用用户工具包。

智能体的使用方式	是否适合用户工具包	业务系统需要完成的工作
Invoke API	适合	处理 pending_interrupt，执行工具，再提交 interrupt_response
WebSocket 接入	适合	接收 message_stream_reply.interrupt，执行工具，再发送 interrupt_response
飞书或 QQ	不适合	渠道不会运行用户自定义代码；改用平台工具包或 MCP
子代理委托	不适合	委托运行不能由主智能体代替业务系统响应用户工具中断；改用平台工具包、MCP 或沙箱

子代理发出的确认型审批与用户工具包中断不是同一条路径。确认型审批可以在主智能体的飞书会话中批准或拒绝；用户工具包需要业务系统执行工具，并返回 RESPOND 或 ERROR。在渠道中批准操作不会运行用户工具包中的业务代码。

在同一个智能体模板中同时添加用户工具包和沙箱，不会把两者连接起来。用户工具调用仍然等待业务系统返回结果；沙箱工具则通过独立的沙箱插件直接运行。

设计工具契约

每个工具包含：

• name：稳定且唯一的工具名称。
• description：说明何时应使用该工具，以及它不会做什么。
• inputSchema：模型必须提供的参数及约束。
• outputSchema：调用方返回结果的结构。

下面的工具用于查询工单状态：

[
  {
    "name": "get_ticket_status",
    "description": "根据工单编号查询状态。只读取工单，不创建或修改工单。",
    "inputSchema": {
      "type": "object",
      "properties": {
        "ticket_id": {
          "type": "string",
          "description": "工单编号，例如 INC-1024"
        }
      },
      "required": ["ticket_id"]
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "ticket_id": { "type": "string" },
        "status": { "type": "string" }
      },
      "required": ["ticket_id", "status"]
    }
  }
]

工具描述和 schema 会影响模型是否选择工具以及如何构造参数。对于写入、删除、付款或外发数据等操作，还应在业务应用中执行身份校验、权限检查和幂等控制。

工具调用中的名称来自 name，顶层参数名来自 inputSchema.properties。调用方应使用这两项校验允许执行的工具和参数。用户工具包产生的是需要调用方返回工具结果的中断；智能体模板中的审批处理规则不能代替调用方执行工具、鉴权或返回 RESPOND 和 ERROR。参见区分审批与工具结果。

将用户工具包添加到智能体模板

1. 创建或编辑智能体模板。

2. 打开 插件配置，单击 添加插件。

3. 在 类型 中选择 用户工具包。

4. 在 默认值 中输入工具数组。

5. 单击 格式化，确认 JSON 可以解析。

6. 决定是否选中 创建实例时可配置：

   • 选中：创建智能体实例时可以替换工具定义。
   • 不选中：智能体实例使用智能体模板中保存的工具定义。

7. 保存智能体模板，并在 插件 中确认关联。

8. 创建或更新测试智能体实例。

格式化 只检查 JSON 语法。保存前仍需核对工具名称、必填字段和输入输出 schema。

在调用方执行工具

用户工具包的完整调用过程如下：

Invoke API 通过 pending_interrupt 返回工具中断；WebSocket 通过 message_stream_reply.interrupt 推送同类信息。业务系统收到中断后：

1. 确认工具名称在应用允许列表中。
2. 按 inputSchema 校验参数，并检查当前用户是否有权执行该操作。
3. 调用业务服务。
4. 返回与 outputSchema 一致的结果：
   • Invoke API 使用同一个 session_id 和中断 ID。
   • WebSocket 使用原消息的 meta 和中断 ID。

Invoke API 示例：

{
  "session_id": "b02d0b5b-5083-4e25-ae98-b21538bf1515",
  "interrupt_response": {
    "interrupt_id": "interrupt-002",
    "action": "RESPOND",
    "response_data": "{\"ticket_id\":\"INC-1024\",\"status\":\"处理中\"}"
  },
  "stream": true
}

WebSocket 客户端的响应格式参见 WebSocket API 参考。

业务服务失败且无法返回有效工具结果时，使用 ERROR 结束该中断。会话、中断动作和调用任务恢复规则参见管理 API 会话、调用任务和中断。

验证用户工具包

1. 使用一个必须调用目标工具才能回答的测试输入。
2. 确认 Invoke API 返回目标工具的 pending_interrupt，或者 WebSocket 客户端收到目标工具的 interrupt。
3. 验证调用方拒绝未知工具、无效参数和无权限请求。
4. 返回与 outputSchema 一致的成功结果，确认智能体继续运行并使用该结果回答。
5. 模拟业务服务失败，确认调用方返回 ERROR，并且不会把业务操作当作成功。
6. 对有副作用的工具重复发送同一请求，验证业务服务的幂等保护。

排查用户工具包

• 模型没有选择工具：让名称和描述更具体，确认测试实例已更新，并使用必须依赖该工具的测试问题。
• 保存时提示 JSON 错误：检查最外层是否为数组，并确认每个元素都包含名称、描述和 schema。
• 调用停在 pending_interrupt 或 interrupt：确认业务系统已经执行工具，并使用正确的会话或消息上下文和中断 ID 返回 RESPOND 或 ERROR。
• 智能体无法理解结果：确认 response_data 的结构与 outputSchema 一致，并让描述说明各字段含义。
• 业务操作重复执行：在业务应用中使用业务请求 ID 或其他幂等键，不要依赖模型避免重复调用。