跳到主要内容

工具调用

理解 AG-UI 中工具的定义、调用生命周期、前端工具与结果回传。

工具(Tools)使智能体能够调用外部能力、执行操作并与应用或用户协作。AG-UI 通过标准事件描述工具调用的全过程,并支持前后端协同的工具执行模式。

工具的作用

在 AG-UI 中,工具可用于:

  • 获取外部信息或查询系统数据
  • 在后端执行操作(如搜索、计算、数据库读写、API 调用)
  • 请求前端执行特定动作(如 UI 操作、本地能力调用)
  • 引入人工判断(如确认、选择、填写信息)

工具定义与来源

AG-UI 生态中常见两类工具来源:

  • 后端定义工具:由智能体后端或框架配置管理,通常在服务端执行。
  • 客户端提供工具:由应用在运行输入中提供(例如通过 RunAgentInput.tools 传递,具体字段视实现而定),供智能体在需要时调用前端能力或用户交互流程。

客户端工具特别适合:需要浏览器权限、依赖当前 UI 状态、或必须由用户在界面中完成的动作。

工具调用事件生命周期

工具调用通常遵循流式模式,与文本消息类似:

  1. TOOL_CALL_START:声明一次工具调用开始
    • toolCallId:唯一标识本次调用
    • toolCallName:工具名称
    • parentMessageId(可选):关联的父消息
  2. TOOL_CALL_ARGS:流式传输参数片段
    • toolCallId:关联同一次调用
    • delta:参数数据片段(常为 JSON 片段),客户端按顺序拼接得到完整参数
  3. TOOL_CALL_END:表示参数/调用规格传输完成
  4. TOOL_CALL_RESULT:返回工具执行结果
    • 关联 toolCallId 与消息上下文
    • content 携带结果内容,role 通常为 tool(以实现为准)

部分实现还提供 TOOL_CALL_CHUNK 便捷事件,可由适配层自动展开为 Start/Args/End 序列。

前端工具调用与回传

对于前端执行的工具,典型流程为:

  1. 智能体发出工具调用事件(指定工具名与参数)。
  2. 客户端识别该工具为前端可处理工具,执行对应逻辑(可能包含 UI 展示或用户确认)。
  3. 客户端将执行结果作为工具结果回传给智能体/运行时,驱动后续推理继续进行。

这一机制使智能体能够安全地利用前端能力,同时保持协议层面的统一表达。

后端工具渲染与可观测性

AG-UI 支持将后端工具的执行过程与输出作为一等事件呈现:

  • 在 UI 中展示“正在调用某工具”“参数/进度”“返回结果”
  • 对长耗时工具配合流式输出展示中间日志或部分结果(视能力与实现而定)
  • 将工具副作用与关键产物纳入会话时间线,便于审计与调试

实践建议

  • 稳定的工具命名与 schema:为参数与结果定义清晰结构,减少解析歧义。
  • 按 toolCallId 聚合状态:在客户端维护调用状态机(pending / args streaming / executing / completed / failed)。
  • 区分展示与执行:后端工具结果用于展示与后续推理;前端工具需明确执行权限与用户确认策略。
  • 错误处理:工具失败时提供可理解的错误信息,并决定是否允许重试或回退。
  • 与中断协同:高风险工具操作可结合人机协同中断引入审批步骤。

Type to search…

↑↓ navigate↵ selectEsc close