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

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具调用

工具（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）。
- **区分展示与执行**：后端工具结果用于展示与后续推理；前端工具需明确执行权限与用户确认策略。
- **错误处理**：工具失败时提供可理解的错误信息，并决定是否允许重试或回退。
- **与中断协同**：高风险工具操作可结合[人机协同中断](https://ag-ui.ndjp.net/concepts/interrupts/)引入审批步骤。

Source: https://ag-ui.ndjp.net/concepts/tools/index.mdx
