AI Agent 工具（Tools）完全指南：从工具定义到调用机制与安全边界

• 文档
• 教程
• 知识库

导读

在 AI Agent 的体系里，"工具"（Tools）是让智能体突破纯文本推理局限、真正落地执行任务的核心组件。本篇指南以 developer-roadmap 仓库的 ai-agents 路线图 为基础，系统讲解什么是 Agent 工具、工具如何在工作循环中被调用、如何用结构化定义描述工具、主流模型厂商的原生函数调用实现，以及工具沙箱与权限控制等安全实践。读完本文，你将掌握 Agent 工具的类型划分、定义格式、调用流程与选型要点，能够独立设计并接入自己的第一个 Agent 工具。

什么是 AI Agent 的工具（Tools）

在 What are Tools? 中，工具被定义为AI Agent 可以调用来完成任务的额外技能或资源（extra skills or resources that an AI agent can call on to finish a job）。

理解这一概念，需要先回到 Agent 本身：一个 AI agent 是能够感知环境、思考并采取行动以达成目标的程序。它通过摄像头、麦克风或软件输入收集数据，用规则或学习到的模式判断数据含义，并选择最合适的行动来接近目标（参见 What are AI Agents?）。而工具就是 Agent 用来"行动"的抓手——它是连接 Agent 内部推理与外部世界的一座桥。

从类型上看，工具几乎可以是任何东西：

• Web 搜索 API：获取训练数据之外的实时信息；
• 计算器：执行精确的数值运算；
• 数据库：查询、增删改结构化数据；
• 语言翻译引擎：跨语言处理；
• 更广义地，还可以是文件系统访问、代码执行环境、邮件/短信发送服务、第三方业务 API 等。

这条路线图中还包含 what-are-tools 之外的同类主题文档 的姊妹篇，例如 MCP Servers 展示的 MCP 服务器就可以向客户端暴露文件系统、数据库或第三方 API 作为工具。

工具的核心价值：补足模型短板

原文档明确指出，工具带来了三方面关键收益：

1. 能力扩展：让一个规模较小的核心模型也能完成自身难以完成、或完成起来又慢又差的任务（"Tools let a small core model handle tasks that would be hard or slow on its own"）；
2. 时效性：帮助 Agent 保持答案的"最新"（current），弥补训练数据的时间截止问题；
3. 准确性与真实性：让回答 grounded in real data（基于真实数据），减少幻觉。

工具工作的基本循环

原文档描述了工具被调用的基本过程：

The agent sends a request to the tool, gets the result, and then uses that result to move forward.

即：Agent 向工具发送请求 → 工具返回结果 → Agent 基于结果继续推进任务。这构成了 Agent 工作循环（Agent Loop）中的关键一环。在 Agent Loop 文档中可以看到更完整的循环：Agent 先收集新数据（来自工具、传感器或记忆），更新内部状态并决策，然后执行动作（如调用 API、写入文件、发送消息），最后检查结果并存储新信息，循环往复。工具调用正是其中"执行动作"阶段的主要载体。

工具定义（Tool Definition）：Agent 如何"认识"一个工具

Agent 之所以知道存在哪些工具、何时该用、参数怎么填，靠的是工具定义（Tool Definition）。仓库中的 Tool Definition 文档给出了精确定义：

A tool definition describes a function an agent can call, including its name, purpose, and the parameters it accepts, usually specified in a structured format like JSON schema.

一个完整的工具定义通常包含三要素：

JSON Schema 描述参数

参数部分通常采用 JSON Schema 结构化描述，例如一个计算器工具的定义可以写作：

{ "type": "function", "function": { "name": "calculator", "description": "对两个数字执行四则运算", "parameters": { "type": "object", "properties": { "a": { "type": "number", "description": "第一个操作数" }, "b": { "type": "number", "description": "第二个操作数" }, "op": { "type": "string", "enum": ["add", "subtract", "multiply", "divide"], "description": "要执行的运算" } }, "required": ["a", "b", "op"] } } }

语言模型（LLM）会阅读这份定义来决定工具何时相关（when the tool is relevant）以及如何填入参数（how to fill in its arguments）。原文档特别强调了一个工程要点：

Clear, well documented tool definitions directly affect how reliably an agent chooses and uses the right tool.

也就是说，工具定义是否清晰、文档是否完善，直接决定了 Agent 选择与使用工具的可靠性。实践中应做到：description 写得足够具体、包含何时该用/何时不该用的提示；参数名语义明确；必填字段用required显式声明；枚举值收窄取值范围以降低模型出错概率。

工具调用的执行阶段：Acting / Tool Invocation

有了定义之后，工具真正被"跑起来"的阶段在路线图中被称为Acting（又称工具调用，Tool Invocation）。仓库文档 Acting / Tool Invocation 描述了这个步骤的完整流程：

1. Agent 审视当前目标与刚制定的计划（looks at its current goal and the plan it just made）；
2. 选出最合适的工具，例如 web 搜索、数据库查询或计算器（picks the best tool）；
3. 填入所需输入并发出调用（fills in the needed inputs and sends the call）；
4. 外部系统完成"重活"并返回结果（the external system does the heavy work and returns a result）；
5. Agent 存储该结果，以便思考下一步行动（stores that result so it can think about the next move）。

需要注意的边界是：模型本身并不执行工具。模型只负责"决策"——决定调用哪个工具、填什么参数、输出一份结构化的调用请求；真正执行工具的是 Agent 所在的应用程序（宿主代码）。执行结果再作为新的上下文回传给模型，供其继续推理。这与 LLM Native Function Calling 文档的描述完全一致：模型输出对预定义函数的结构化调用（函数名+参数），由应用执行实际函数并把结果返回给模型继续对话。

工具与记忆、推理的协作：观察—决策—行动

一个工具调用并不是孤立发生的，它始终处于 Agent 更大的循环中。结合 Agent Loop 与 What is Agent Memory? 两篇文档，可以看到工具与记忆的协作关系：

• Agent 在调用工具前，会参考短期记忆（当前对话上下文）与长期记忆（跨会话存储的用户偏好、已学事实）来决定调用策略；
• 工具返回的结果会被写入记忆，供后续回合使用；
• 循环以"observe–decide–act"（观察–决策–行动）的方式快速重复，让 Agent 能随环境变化持续调整。

可以说，工具负责"与世界交互"，记忆负责"记住交互结果"，推理负责"决定交互方式"，三者共同构成 Agent 的完整行为闭环。

原生函数调用：主流模型如何输出工具调用

什么是 LLM 原生函数调用

工具调用之所以能稳定工作，离不开模型层面的"原生函数调用"（Function Calling）能力。仓库文档 LLM Native Function Calling 指出：

LLM native function calling is a capability built directly into a model's API that lets it output a structured call to a predefined function... instead of freeform text.

关键点是结构化输出：模型直接输出"函数名 + 参数"的结构化调用（通常是 JSON），而不是在自由文本里夹带调用意图。这免去了从纯文本输出中解析工具调用的麻烦，标准化了模型请求动作的方式。

两种代表性实现

路线图中收录了两种主流厂商的实现，可作为学习范本：

OpenAI Functions Calling（文档）：允许模型从 API 请求中定义的一组函数里做选择，并返回包含函数名与参数的 JSON 结构化调用；调用方执行函数后把结果回传，供模型生成下一个响应。它是最早、最广泛采用的原生工具调用实现之一。

Anthropic Tool Use（文档）：Claude 的原生函数调用实现，模型可以在响应中以结构化参数调用已定义工具；调用方执行工具并返回结果，Claude 据此继续推理或产出最终答案。它还支持并行工具调用（parallel tool calls）以及强制指定某个工具（forcing a specific tool to be used）等模式。

两种实现的核心模式一致：定义工具 → 模型输出结构化调用 → 应用执行 → 结果回传 → 模型继续。学习时可对照这两份文档理解各自 API 的差异（如并行调用、工具选择约束等）。

最小实现示意

以通用流程为例，一个典型的工具调用实现包含以下环节：

# 伪代码：示意工具调用的宿主侧流程 tools = [calculator_schema] # 工具定义（JSON Schema 列表） response = llm.chat(messages, tools=tools) # 1. 携带工具定义发起对话 if response.tool_calls: # 2. 模型返回结构化工具调用 for call in response.tool_calls: result = execute(call.name, call.arguments) # 3. 宿主执行工具 messages.append(tool_result_message(call.id, result)) # 4. 结果回传 final = llm.chat(messages) # 5. 模型基于结果继续推理

注意：以上为教学示意，实际实现请以你所用模型厂商 API 的官方规范为准（本仓库仅收录了概念性描述文档，不包含可运行的示例代码）。

典型工具实战：Web 搜索与数据库查询

为了理解"选择合适的工具"这一关键能力，路线图中收录了两类最典型的工具，值得展开：

Web 搜索工具

Web Search 文档描述了它的工作方式：

1. Agent 把用户请求转成搜索关键词（turns a user request into search words）；
2. 发送给搜索引擎并阅读结果列表；
3. 跟进最相关的链接、抓取页面文本、挑出回答任务的部分。

它的适用场景非常明确：处理训练数据中没有的话题、更新过时知识、交叉核对细节。原文档同时强调了其局限：必须警惕广告、偏见或错误页面，通过交叉核对来源来保证准确。这提醒我们在设计搜索工具时，应在工具描述中提示"用于获取实时信息、核实事实"，并让 Agent 养成多源核实的习惯。

数据库查询工具

Database Queries 文档则描述了面向结构化数据的工具：Agent 用查询语言（最常用 SQL）向数据库发送请求，数据库引擎在表中查找并只返回符合条件的行与列。其价值在于：

• 回答需要实时数字、用户记录或存储事实的问题；
• 写入新条目或修改旧数据，保持数据最新；
• 由于查询实时执行且规则明确（follow clear rules），Agent 可以可靠地处理大规模结构化信息。

如何选择与何时使用

原文档的结论是：Choosing the right tool and knowing when to use it are key parts of building a smart agent（选择合适的工具、知道何时使用它，是构建智能 Agent 的关键部分）。

实践中可遵循的决策原则：

• 按数据类型选：实时/非结构化信息 → Web 搜索；结构化、可查询的数据 → 数据库；精确数值 → 计算器；
• 按副作用区分：只读操作优先选择无副作用的工具，写操作要经过权限与确认；
• 让定义替你表达"何时用"：在工具 description 中写明适用边界，模型会依据定义做选择；
• 监控选择质量：如果 Agent 频繁选错工具，优先检查工具定义是否清晰，而不是责怪模型。

工具生态：MCP 与可复用工具

在实际工程中，工具往往不是为单个 Agent 手写的，而是通过统一协议复用。路线图中的 MCP Servers 文档说明：

An MCP server exposes a set of tools, data, or capabilities to any compatible client using the Model Context Protocol... Because servers follow a shared protocol, they can be reused across different AI applications without custom integration work.

这意味着：一个提供文件系统、数据库或第三方 API 访问的 MCP 服务器，可以被任何兼容客户端复用，无需为每个应用做定制集成。这与"工具定义标准化"是同一思路的延伸——工具不仅要在模型层面结构化，还要在协议层面标准化，才能形成生态。如果你需要把大量工具接入多个 Agent 应用，MCP 是目前值得优先考察的载体。

工具安全：沙箱与权限控制

工具赋予 Agent 行动能力的同时也带来了风险，因此路线图专门收录了 Tool Sandboxing / Permissioning 一文，其核心思想是"围栏"：

• 沙箱（Sandboxing）：让 Agent 待在安全区内，只能执行被批准的动作，不能触碰更广的系统；
• 权限控制（Permissioning）：制定明确规则，规定 Agent 可以使用哪些文件、网络或命令。

两者的共同目标，是通过限制 Agent 能触及和能做的事，来阻止错误、数据泄漏或滥用。文档给出的工程实践包括：

1. 最小权限：只授予完成任务所需的最小权利集（grant the smallest set of rights）；
2. 全程监控：观察 Agent 的活动（watch activity）；
3. 越界拦截：阻止计划之外的任何访问（block anything outside the plan）；
4. 动态授权：如果 Agent 需要新的访问权限，必须提出请求并获得新的许可（ask and get a fresh permit）。

这套"围栏"哲学直接对应到具体实现：文件系统工具应限制在特定目录、网络工具应只允许白名单域名、命令执行应放进容器或 VM。它既保护用户数据、降低危害，也建立对 Agent 工作的信任。

路线图定位与延伸阅读

本篇内容对应 developer-roadmap 仓库中 ai-agents 路线图 的 "What are Tools" 节点。该节点处于路线图的工具（Tools）能力簇中，与之紧密相连、建议按序阅读的相关文档包括：

• Tool Definition：工具的结构化定义与 JSON Schema 写法；
• Acting / Tool Invocation：工具调用的完整执行阶段；
• LLM Native Function Calling 与 OpenAI Functions Calling、Anthropic Tool Use：主流模型的原生工具调用机制；
• Agent Loop 与 What is Agent Memory?：工具调用所处的更大循环与记忆协作；
• Web Search、Database Queries：两类典型工具的实战细节；
• MCP Servers 与 Tool Sandboxing / Permissioning：工具生态与安全边界。

小结

工具是 AI Agent 的"手脚"，让模型从"只会说"进化到"能做事"。围绕本路线图的 What are Tools 节点，我们梳理出五条主线：工具的本质与价值（补足模型能力、保持时效、grounded 于真实数据）、工具的定义方式（JSON Schema 结构化描述，质量直接决定选型可靠性）、调用的执行流程（决策—执行—回传—再推理）、主流实现（OpenAI 与 Anthropic 的原生函数调用），以及工程化配套（MCP 生态复用与沙箱权限控制）。理解并实践好这五条主线，你就能设计出"会选工具、会用工具、用得安全"的智能 Agent。

• 文档
• 教程
• 知识库