使用用户工具包让智能体调用你自己的业务能力

用户工具包让智能体开发服务平台（AgentWorks）中的智能体调用你自己开发和运行的应用或服务所提供的操作。AgentWorks 保存并使用工具定义；实际代码仍在你自己的应用环境中运行，再把结果返回给智能体。本文把这些运行在 AgentWorks 之外、通过 Invoke API 或 WebSocket 调用智能体的应用、后端服务或客户端简称为“你的应用”；在 API 交互中，它们也是调用方。

让智能体调用在你自己的应用中运行的工具

用户工具包连接的是两部分：智能体模板中的工具定义，以及你的应用中已经实现的工具处理程序。工具定义帮助模型判断何时调用和提供哪些参数；工具处理程序使用当前用户、页面、设备或私网环境完成实际操作。

配置时，把工具定义添加到智能体模板

配置者在智能体模板中保存工具名称、用途和输入输出结构。创建或更新智能体实例时，这份定义随模板配置提供给实例；你的应用中的工具代码仍由应用团队编写、部署和运行。

图表预览

虚线只表示智能体模板和你的应用遵守同一份工具契约，不表示 AgentWorks 会把工具代码部署到你的应用。AgentWorks 不会根据工具名称自动寻找业务 API，也不会托管你的程序、API 地址、凭证或运行环境。

区分工具定义和工具实现

在智能体模板中定义	在你的应用中实现
工具名称和用途	工具名称对应的处理程序
模型可以提供的输入字段	当前用户、页面、设备和业务状态的可信来源
应用应返回的结果结构	身份校验、权限检查和实际业务操作
模型选择工具所需的说明	超时、重试、幂等、审计以及 RESPOND 或 ERROR 回传

运行时，由你的应用执行工具

你的应用向智能体发送用户请求。智能体选择用户工具后，AgentWorks 把工具名称和参数作为中断返回给同一个应用；你的应用校验请求、运行自己的处理程序，再使用 RESPOND 或 ERROR 返回结果。

图表预览

一次任务可以重复这个闭环。例如，客服智能体可以先取得当前来电信息，再查询服务政策，并根据结果决定是否让客服工作台暂停通话或创建后续工单。每次用户工具调用仍由客服工作台执行，AgentWorks 负责根据中间结果选择下一步。

注意

只需要一次模型响应时

如果应用只需生成摘要、分类结果，或把一个明确命令映射到固定函数，普通模型 API 或应用代码通常更直接。当用户只说明目标，系统需要根据中间结果连续选择能力、判断分支或继续尝试时，可以让 AgentWorks 组织这段过程。

普通模型 API 也能实现多步骤流程，但应用需要自行维护多轮模型调用、工具结果回传和下一步判断。详细比较参见你的应用应该调用 AgentWorks 智能体，还是直接调用模型 API？。

判断工具是否应该在你自己的应用中执行

当操作必须使用你的应用掌握的实时状态、当前用户身份、本地设备或私网连接时，优先使用用户工具包。若能力已经由 AgentWorks、远程 MCP Server 或另一个智能体实例提供，应直接使用对应方式。

智能体需要完成的操作	优先使用	原因
暂停客服工作台中的当前通话，或者修改 IDE 中尚未保存的文件	用户工具包	你的应用掌握当前通话、页面或本地工作区状态
操作扫码枪、标签打印机等本地设备，或者通过只允许出站连接的网关访问工厂系统	用户工具包	你的应用能够直接访问设备或私网，不需要额外开放 MCP Server
调用多个智能体都需要复用的远程工具服务	MCP	MCP Server 通过 Streamable HTTP 提供标准工具接口
在 AgentWorks 管理的隔离环境中运行命令、处理文件或执行代码	沙箱和 Skill	沙箱提供运行环境，Skill 提供任务方法和资源
使用 AgentWorks 已经提供的现成工具	平台工具包	AgentWorks 直接执行工具，无需在你的应用中实现处理程序
把专业任务交给另一个已有智能体实例	子代理	AgentWorks 跟踪委托任务并把结果交回主智能体

选择用户工具包前，确认以下条件都成立：

1. 你的应用通过 Invoke API 或 WebSocket 使用智能体。
2. 你的应用能够执行目标操作。
3. 执行所需的用户身份、业务状态或设备上下文适合继续由你的应用管理。
4. 你的应用能够接收工具中断，并用 RESPOND 或 ERROR 返回结果。

需要先用固定的只读示例验证工具中断闭环时，参见构建可调用业务系统的工单助手。该实战刻意只查询一个工单，用于验证工具契约、通过 Invoke API 调用智能体的应用以及固定成功与失败用例，不用于展示多步骤智能体的完整价值。

确认接入方式能够处理工具中断

只有能够接收并响应工具中断的接入方式，才能完成用户工具调用闭环。

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

子代理发出的确认型审批与用户工具包中断不是同一条路径。确认型审批可以在主智能体的飞书会话中批准或拒绝；用户工具包仍需要你的应用执行工具并返回 RESPOND 或 ERROR。在同一个智能体模板中同时添加用户工具包和沙箱，也不会让沙箱自动执行用户工具。

设计可由你的应用安全执行的工具

工具契约应让模型知道何时调用，也让你的应用能够严格校验收到的名称和参数。每个工具包含：

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

下面的示例只允许模型提供可选的暂停原因。当前通话 ID 不由模型提供，而是由客服工作台根据已认证的坐席会话取得：

[
  {
    "name": "hold_current_call",
    "description": "将客服坐席当前正在处理的通话置于保持状态。仅在用户明确要求暂停当前通话时使用。",
    "inputSchema": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "description": "暂停通话的原因"
        }
      },
      "additionalProperties": false
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": ["on_hold"]
        },
        "message": {
          "type": "string"
        }
      },
      "required": ["status", "message"],
      "additionalProperties": false
    }
  }
]

工具描述和 schema 会影响模型是否选择工具以及如何构造参数。设计时：

1. 只让模型提供完成操作所需的最少参数。
2. 由你的应用根据已认证会话确定当前用户、当前通话、当前文档或目标设备，不要直接采用模型生成的身份或环境 ID。
3. 对退款、付款、删除、外发数据等高风险操作，在你的应用中执行身份校验、权限检查、人工确认和幂等控制；必要时把预览和执行拆成两个工具。
4. 只返回智能体完成回答所需的结构化结果，不返回原始凭证或无关业务记录。

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

将工具定义添加到智能体模板

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

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

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

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

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

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

   • 不选中：所有智能体实例使用智能体模板中保存的同一份工具契约。你的应用为这些实例实现相同工具时，优先使用这一方式。
   • 选中：创建智能体实例时可以替换工具契约。只有不同实例确实由支持不同工具的应用调用时才使用，并确保实例中的定义与对应应用实现一致。

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

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

格式化 只检查 JSON 语法。保存前仍需核对工具名称、必填字段和输入输出 schema；它不会检查你的应用是否实现了这些工具。

在你的应用中执行工具并返回结果

你的应用收到工具中断后，只执行允许列表中已经实现的工具。完整处理过程包括：

1. 根据 Invoke API 会话或 WebSocket 消息上下文确定当前用户和业务会话。

2. 确认工具名称在允许列表中，并按 inputSchema 校验参数。

3. 检查当前用户是否有权执行操作；需要确认时，在业务应用中完成确认。

4. 调用对应的业务处理程序，并记录防止重复执行所需的业务请求 ID。

5. 返回与 outputSchema 一致的结果：

   • Invoke API 使用同一个 session_id 和中断 ID。
   • WebSocket 使用原消息的 meta 和中断 ID。

Invoke API 通过 pending_interrupt 返回工具中断。你的应用执行成功后，可以继续同一个会话：

{
  "session_id": "b02d0b5b-5083-4e25-ae98-b21538bf1515",
  "interrupt_response": {
    "interrupt_id": "interrupt-002",
    "action": "RESPOND",
    "response_data": "{\"status\":\"on_hold\",\"message\":\"当前通话已暂停\"}"
  },
  "stream": true
}

WebSocket 通过 message_stream_reply.interrupt 推送同类信息；响应格式参见 WebSocket API 参考。业务操作失败且无法返回有效工具结果时，使用 ERROR 结束该中断。会话、中断动作和调用任务恢复规则参见管理 API 会话、调用任务和中断。

注意

批准工具调用后仍要返回执行结果

如果用户工具调用还需要人工审批，APPROVE 只允许调用继续。你的应用仍需执行工具，并使用 RESPOND 返回结果或使用 ERROR 返回失败。

验证工具确实由你的应用执行

1. 使用一个必须调用目标工具才能完成的测试输入。
2. 确认 Invoke API 返回目标工具的 pending_interrupt，或者 WebSocket 客户端收到目标工具的 interrupt。
3. 确认你的应用使用同一会话或消息上下文识别当前用户，并且只执行一次预期处理程序。
4. 在业务系统的审计记录、测试数据或设备状态中，确认目标操作确实发生。
5. 返回与 outputSchema 一致的成功结果，确认智能体使用该结果回答并正常完成。
6. 验证你的应用拒绝未知工具、无效参数和无权限请求。
7. 模拟业务操作失败，确认你的应用返回 ERROR，并且不会把操作当作成功。
8. 对有副作用的工具重复发送同一业务请求，验证幂等保护不会重复执行操作。

管理身份、重复调用和外部执行环境

你的应用应在服务端保存 AgentWorks 会话或消息与当前用户、业务会话和执行目标的对应关系。不要让模型决定用户身份、权限、设备或外部环境；也不要因为模型已经选择工具而跳过业务系统原有的授权、确认和审计流程。

为每次操作设置明确的超时和失败处理。可能重试的写操作应使用业务请求 ID 或其他幂等键；返回给智能体的结果应避免包含密码、访问令牌和完成回答不需要的敏感数据。

按会话或调用任务管理外部执行环境

需要按会话、线程、调用任务或单次运行隔离工具执行时，由你的应用管理外部执行环境。AgentWorks 当前不会按这些范围创建沙箱，用户工具包本身也不提供运行环境。

• 按会话或线程隔离：你的应用在取得 session_id 或收到该会话的第一个工具中断后创建外部环境，保存业务会话、已授权用户和 session_id 的对应关系，后续处理中断时复用，并在业务会话结束或达到有效期后销毁。
• 按调用任务或单次运行隔离：你的应用为当前业务运行创建外部环境，在该运行的中断响应过程中复用，并在最终完成、失败或超时后销毁。

外部环境 ID 应由你的应用在完成身份和权限校验后选择并保存在服务端，不要直接采用模型生成的环境 ID。该方式只隔离你的应用执行的用户工具；AgentWorks 模型运行、平台工具包和沙箱工具仍使用各自原有的运行方式。需要使用 AgentWorks 沙箱执行时，参见选择沙箱隔离范围。

排查工具调用没有完成

• 模型没有选择工具：让名称和描述更具体，确认测试实例已更新，并使用必须依赖该工具的测试问题。
• 保存时提示 JSON 错误：检查最外层是否为数组，并确认每个元素都包含名称、描述和 schema。
• 你的应用没有收到中断：确认智能体通过 Invoke API 或 WebSocket 使用，并且测试实例已经采用包含用户工具包的当前模板配置。
• 调用停在 pending_interrupt 或 interrupt：确认你的应用已经执行工具，并使用正确的会话或消息上下文和中断 ID 返回 RESPOND 或 ERROR。
• 你的应用找不到工具处理程序：确认实例中的 name 与应用允许列表完全一致；如果允许创建实例时修改工具定义，还要核对该实例使用的契约。
• 智能体无法理解结果：确认 response_data 的结构与 outputSchema 一致，并让工具描述说明各字段含义。
• 业务操作重复执行：在业务应用中使用业务请求 ID 或其他幂等键，不要依赖模型避免重复调用。

你的应用应该调用 AgentWorks 智能体，还是直接调用模型 API？

先确认你的应用需要的是一次模型响应，还是一个能够连续选择和调用能力的智能体。普通模型 API 也可以生成文本、结构化数据或工具调用；区别在于谁负责组织后续步骤。

你的应用需要完成的工作	更直接的选择	你的应用需要负责什么
生成摘要、分类结果或结构化字段，一次响应即可完成	普通模型 API	准备输入并处理一次模型响应
一个明确命令固定对应一个业务函数	应用代码；需要理解自然语言时，可以配合普通模型 API 的工具调用	选择并执行固定函数
用户只说明目标，系统需要结合中间结果选择工具、判断分支或继续尝试	AgentWorks 智能体（通过 Invoke API 或 WebSocket 接入）	执行需要在你自己的应用中运行的用户工具；其余连续处理由 AgentWorks 组织

普通模型 API 也能实现最后一种流程，但应用需要自行维护模型请求、工具调用、结果回传、会话延续和下一步判断。选择 AgentWorks 的价值在于让平台管理“选择能力、接收结果、继续处理”的连续过程，并复用智能体模板中配置的知识、MCP、Skill 和其他能力；它不是让一个固定操作突然变得必须使用智能体。

例如，客服坐席可以向工作台中的智能体提出一个处理目标：

客户说本月账单可能重复扣费。请结合当前来电人的信息和服务政策查明原因；如果不能立即解决，暂停当前通话并创建包含通话摘要的后续工单，最后告诉我应该如何回复客户。

这个任务没有一条预先固定的执行路径。AgentWorks 可以结合当前来电信息和服务政策判断是否需要后续处理；真正读取当前通话、暂停通话和创建工单的仍是客服工作台。

图表预览

这里同时体现两层价值：客服工作台掌握当前通话和坐席身份，因此适合执行用户工具；AgentWorks 根据目标和中间结果选择处理路径，因此适合组织完整任务。参见让智能体调用在你自己的应用中运行的工具。