Agent 工具调用是让模型用结构化请求选择外部能力，再由 Agent 运行框架代为执行的机制。工具可以查询数据库、搜索资料、读取文件、运行程序或发起业务操作，从而使模型不只生成文本，还能感知和改变外部环境。
模型通常不会直接访问文件系统、网络或数据库。它输出工具名称和参数，Harness 校验并执行请求，再把结果作为工具消息返回给模型。
一次调用的四个阶段
- 定义工具：应用向模型提供名称、用途说明和参数 Schema；
- 选择工具：模型根据当前上下文决定是否调用、调用哪个工具以及传入什么参数；
- 执行工具：Harness 检查名称、参数和权限，在外部环境中运行真正的函数或服务；
- 返回结果：Harness 使用调用 ID 将成功结果或结构化错误交还给模型。
工具调用本身只是一次“请求—结果”交换；把多次交换组织到任务结束的控制流程，属于 Agent 工具调用循环。
工具定义
一个清晰的工具定义通常包含：
- 稳定且能表达动作的名称；
- 说明工具做什么、不做什么以及何时使用；
- 使用 JSON Schema 描述必填参数、类型、枚举和约束；
- 对返回值和错误建立稳定的结构；
- 标明只读、可逆写入或高风险操作等安全属性。
工具描述是模型选择工具时的重要依据。功能重叠、命名含糊或参数过多都会增加误用概率。
TypeScript 示例
下面的代码展示工具执行器的基本边界：
type ToolCall = {
id: string;
name: string;
arguments: unknown;
};
async function executeTool(call: ToolCall) {
const tool = toolRegistry.get(call.name);
if (!tool) throw new Error("Unknown tool");
const input = tool.schema.parse(call.arguments);
await authorize(tool, input);
return tool.run(input);
}
真实系统还需要处理超时、取消、并发、重试、幂等、日志脱敏以及大结果截断。
MCP 与工具调用
Model Context Protocol（MCP）可以让服务器以统一协议公开工具，使不同 Host 或 Agent 客户端发现并调用这些能力。MCP 解决的是工具如何描述、连接和传输；Agent 仍需负责何时使用工具、怎样组合结果、如何控制权限以及何时结束任务。
安全与可靠性
- 所有参数都在执行前进行 Schema 校验，不能把模型输出直接拼接为命令；
- 工具端再次执行身份、权限和资源范围检查；
- 高风险操作先展示影响范围并请求人工确认；
- 写操作使用幂等键或查重机制，避免重试造成重复副作用；
- 工具错误返回可判断的错误码，并限制相同失败的重试次数；
- 工具输出按不可信数据处理，防止其中的文本改变系统指令；
- 日志记录调用关系和耗时，但不保存 Token、Cookie 等凭据。