工具(Tools)使智能体能够调用外部能力、执行操作并与应用或用户协作。AG-UI 通过标准事件描述工具调用的全过程,并支持前后端协同的工具执行模式。
工具的作用
在 AG-UI 中,工具可用于:
- 获取外部信息或查询系统数据
- 在后端执行操作(如搜索、计算、数据库读写、API 调用)
- 请求前端执行特定动作(如 UI 操作、本地能力调用)
- 引入人工判断(如确认、选择、填写信息)
工具定义与来源
AG-UI 生态中常见两类工具来源:
- 后端定义工具:由智能体后端或框架配置管理,通常在服务端执行。
- 客户端提供工具:由应用在运行输入中提供(例如通过
RunAgentInput.tools传递,具体字段视实现而定),供智能体在需要时调用前端能力或用户交互流程。
客户端工具特别适合:需要浏览器权限、依赖当前 UI 状态、或必须由用户在界面中完成的动作。
工具调用事件生命周期
工具调用通常遵循流式模式,与文本消息类似:
TOOL_CALL_START:声明一次工具调用开始toolCallId:唯一标识本次调用toolCallName:工具名称parentMessageId(可选):关联的父消息
TOOL_CALL_ARGS:流式传输参数片段toolCallId:关联同一次调用delta:参数数据片段(常为 JSON 片段),客户端按顺序拼接得到完整参数
TOOL_CALL_END:表示参数/调用规格传输完成TOOL_CALL_RESULT:返回工具执行结果- 关联
toolCallId与消息上下文 content携带结果内容,role通常为tool(以实现为准)
- 关联
部分实现还提供 TOOL_CALL_CHUNK 便捷事件,可由适配层自动展开为 Start/Args/End 序列。
前端工具调用与回传
对于前端执行的工具,典型流程为:
- 智能体发出工具调用事件(指定工具名与参数)。
- 客户端识别该工具为前端可处理工具,执行对应逻辑(可能包含 UI 展示或用户确认)。
- 客户端将执行结果作为工具结果回传给智能体/运行时,驱动后续推理继续进行。
这一机制使智能体能够安全地利用前端能力,同时保持协议层面的统一表达。
后端工具渲染与可观测性
AG-UI 支持将后端工具的执行过程与输出作为一等事件呈现:
- 在 UI 中展示“正在调用某工具”“参数/进度”“返回结果”
- 对长耗时工具配合流式输出展示中间日志或部分结果(视能力与实现而定)
- 将工具副作用与关键产物纳入会话时间线,便于审计与调试
实践建议
- 稳定的工具命名与 schema:为参数与结果定义清晰结构,减少解析歧义。
- 按
toolCallId聚合状态:在客户端维护调用状态机(pending / args streaming / executing / completed / failed)。 - 区分展示与执行:后端工具结果用于展示与后续推理;前端工具需明确执行权限与用户确认策略。
- 错误处理:工具失败时提供可理解的错误信息,并决定是否允许重试或回退。
- 与中断协同:高风险工具操作可结合人机协同中断引入审批步骤。