完全指南:从工具定义到调用机制与安全边界)
文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载导读在 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 作为工具。工具的核心价值补足模型短板原文档明确指出工具带来了三方面关键收益能力扩展让一个规模较小的核心模型也能完成自身难以完成、或完成起来又慢又差的任务Tools let a small core model handle tasks that would be hard or slow on its own时效性帮助 Agent 保持答案的最新current弥补训练数据的时间截止问题准确性与真实性让回答 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 DefinitionAgent 如何认识一个工具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.一个完整的工具定义通常包含三要素要素作用典型格式名称name唯一标识供模型选择字符串如web_search用途/描述description说明工具能力与适用场景帮助模型判断何时相关自然语言描述参数parameters声明工具接受哪些输入及约束JSON SchemaJSON 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 描述了这个步骤的完整流程Agent 审视当前目标与刚制定的计划looks at its current goal and the plan it just made选出最合适的工具例如 web 搜索、数据库查询或计算器picks the best tool填入所需输入并发出调用fills in the needed inputs and sends the call外部系统完成重活并返回结果the external system does the heavy work and returns a resultAgent 存储该结果以便思考下一步行动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 models 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, toolstools) # 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 文档描述了它的工作方式Agent 把用户请求转成搜索关键词turns a user request into search words发送给搜索引擎并阅读结果列表跟进最相关的链接、抓取页面文本、挑出回答任务的部分。它的适用场景非常明确处理训练数据中没有的话题、更新过时知识、交叉核对细节。原文档同时强调了其局限必须警惕广告、偏见或错误页面通过交叉核对来源来保证准确。这提醒我们在设计搜索工具时应在工具描述中提示用于获取实时信息、核实事实并让 Agent 养成多源核实的习惯。数据库查询工具Database Queries 文档则描述了面向结构化数据的工具Agent 用查询语言最常用 SQL向数据库发送请求数据库引擎在表中查找并只返回符合条件的行与列。其价值在于回答需要实时数字、用户记录或存储事实的问题写入新条目或修改旧数据保持数据最新由于查询实时执行且规则明确follow clear rulesAgent 可以可靠地处理大规模结构化信息。如何选择与何时使用原文档的结论是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 能触及和能做的事来阻止错误、数据泄漏或滥用。文档给出的工程实践包括最小权限只授予完成任务所需的最小权利集grant the smallest set of rights全程监控观察 Agent 的活动watch activity越界拦截阻止计划之外的任何访问block anything outside the plan动态授权如果 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。赞分享文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载相关推荐突破AI交互边界Langchain-Chatchat Agent机制与工具调用全指南突破AI交互边界Langchain Chatchat Agent机制与工具调用全指南 Langchain Chatchat是基于Langchain与ChatG人工智能大模型RAGAI Agent本地部署后端Flue Tools 完全指南为 Agent 定义、挂载与保护工具调用Flue Tools 完全指南为 Agent 定义、挂载与保护工具调用 这篇技术指南以 Fluesandbox agent framework的 Tool人工智能大模型AI AgentAgent 框架工具调用Agent 沙箱MCP ClientsX6 边工具Edge Tool完全指南从内置工具到自定义工具X6 边工具Edge Tool完全指南从内置工具到自定义工具 本篇指南以 X6 图编辑引擎的边工具Edge Tool为核心讲解如何通过工具增强边的可前端图形学上一篇QtScrcpy终极指南免费开源的安卓设备跨平台投屏与控制解决方案下一篇PyRestTest命令行参数全解析定制你的测试执行流程创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考