1. 项目概述当Agent学会“动手”最近和几个做AI应用的朋友聊天发现一个挺有意思的现象大家聊起Agent智能体时兴奋点往往集中在它的“大脑”上——用了哪个大模型、思维链Chain-of-Thought有多长、推理能力有多强。但聊到具体落地比如让Agent去订一张机票、自动整理一份周报、或者控制智能家居设备时气氛就有点微妙了。很多人会两手一摊说“这得等模型能力再强一点或者等某个框架把工具调用封装得更好。”这其实陷入了一个思维误区。我们总在期待一个“全能”的Agent却忽略了让Agent真正“活”起来、长出“手脚”去执行任务的关键往往不在模型内部而在模型与外部世界交互的“协议层”。这就像造一个机器人我们花了大量精力优化它的中央处理器CPU和算法却对如何给它安装机械臂、设计握持指令的接口语焉不详。今天我们就以最主流的OpenAI API为切入点抛开那些“黑箱”式的框架封装直接深入到API协议层面看看一个Agent是如何被“教会”使用工具的。你会发现所谓的“智能体行动”其核心机制远比想象中要清晰和结构化。理解了这个你不仅能更好地使用现成的Agent框架甚至能自己设计更贴合业务需求的工具调用逻辑。无论你是想深入Agent开发还是仅仅想用好ChatGPT的“自定义指令”或“GPTs”功能这篇文章都会帮你揭开那层神秘的面纱。2. 核心机制拆解OpenAI API中的“工具”与“函数调用”要理解Agent如何行动我们必须先搞清楚大模型本身是如何被“告知”它可以做什么以及它如何表达“我想做什么”。在OpenAI的API体系中这主要围绕两个核心概念展开tools工具和function calling函数调用。很多人会把它们混为一谈但其实它们扮演着不同的角色。2.1 角色定义系统、用户、助手与工具在OpenAI的聊天补全API中对话由一系列消息messages构成每条消息都有一个role角色。除了我们熟悉的system系统、user用户和assistant助手之外当涉及工具调用时会引入第四个角色tool。system: 设定助手的背景、行为和目标。例如“你是一个乐于助人的旅行助手专注于使用工具为用户查询信息。”user: 代表人类用户提出问题或发出指令。例如“帮我查一下下周五从北京飞往上海的航班。”assistant: 模型的回复。这里的关键是助理的回复可能包含两种内容1) 直接的文本回答2) 一个请求调用特定工具的“意图”声明。tool: 代表工具执行后的返回结果。当模型请求调用一个工具后开发者需要实际执行该工具函数然后将执行结果以tool角色的消息形式附加到对话历史中再送回给模型让它基于结果继续回复。这个tool角色的引入是模型能与外部世界进行“多轮”交互的基石。它把一次性的问答变成了一个“模型思考-请求行动-环境反馈-模型再思考”的循环。2.2 工具Tools的定义给模型一份“能力清单”工具本质上是一个声明。它告诉模型“嘿你现在拥有这些可用的外部能力。” 在API请求中我们通过tools参数来传递这个清单。每个工具都是一个JSON对象核心是type和function字段。目前type主要是function未来可能会有其他类型。function字段内则详细描述了这个函数。{ type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气情况。, parameters: { type: object, properties: { location: { type: string, description: 城市名称例如北京、San Francisco }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位摄氏度或华氏度。 } }, required: [location] } } }关键点解析name: 函数的唯一标识符。模型在决定调用时就靠这个名字来指定。description:这是最重要的部分模型完全依靠这段自然语言描述来理解这个工具是干什么的。描述必须清晰、准确最好包含使用场景和示例。模糊的描述会导致模型错误调用或根本不调用。parameters: 严格遵循JSON Schema格式定义。它定义了函数需要的参数、每个参数的类型、描述以及是否必需。enum列表能有效约束模型的输出范围。实操心得描述的艺术写工具描述时要站在模型的视角。不要写“查询天气数据”而要写“当用户询问天气、穿衣建议、或出行计划时使用此工具获取准确的温度、湿度和天气状况。” 前者是开发者视角后者是任务视角能极大提高模型调用的准确率。2.3 函数调用Function Calling的流程模型如何“举手”当我们把包含tools定义的请求发送给模型后模型并不会直接去执行工具。它做的第一件事是“思考”根据当前对话上下文和可用的工具列表判断是否需要调用工具以及调用哪一个。如果模型认为需要调用工具它会在回复中返回一个特殊结构而非常规的文本。这个结构包含在choices[0].message中关键字段是tool_calls。一个典型的模型“举手”请求调用的响应如下{ id: chatcmpl-xxx, object: chat.completion, created: 1700000000, model: gpt-4, choices: [{ index: 0, message: { role: assistant, content: null, tool_calls: [{ id: call_abc123, type: function, function: { name: get_current_weather, arguments: {\location\: \上海\, \unit\: \celsius\} } }] }, finish_reason: tool_calls }], usage: {...} }关键字段解读content: null: 当模型决定调用工具时其文本回复内容通常为空。它的“想法”已经通过tool_calls表达了。tool_calls: 一个数组理论上模型可以同时请求调用多个工具并行工具调用。每个元素代表一次调用请求。id: 本次调用的唯一ID非常重要在后续返回工具结果时需要用这个ID来匹配。function.name: 模型想调用的工具名称必须与之前tools参数中定义的某个name完全一致。function.arguments: 一个JSON格式的字符串。模型会根据工具定义中parameters的JSON Schema生成符合规范的参数。这里是{location: 上海, unit: celsius}。finish_reason: “tool_calls”: 停止原因明确表示模型停止生成是因为它发起了工具调用。这个过程就是模型“长出想法”的关键一步它将模糊的用户意图“上海天气怎么样”转化成了一个结构化的、可执行的行动指令调用get_current_weather函数参数为location上海。2.4 执行与反馈完成行动闭环模型发出了调用请求但它自己并不会执行。执行工具是开发者代码的责任。我们需要解析tool_calls中的name和arguments。在我们的后端代码中找到对应的函数比如一个真正调用天气API的函数。执行该函数并获得结果。然后我们必须将结果反馈给模型让模型进行“下一轮思考”。这是通过在下一次API请求的messages列表中追加一条role为tool的消息实现的。{ role: tool, content: {\temperature\: 22, \condition\: \晴朗\, \humidity\: \65%\}, tool_call_id: call_abc123 }关键字段解读role: “tool”: 明确这是一条工具执行结果的消息。tool_call_id:必须与模型请求中的idcall_abc123对应这是将结果与特定请求关联起来的唯一纽带。如果一次请求中有多个tool_calls你需要为每一个都返回对应的tool消息。content: 工具执行结果的字符串。可以是JSON字符串也可以是纯文本。内容应尽可能简洁、相关便于模型理解。当这条消息和之前的对话历史一起作为新的请求发送给模型时模型就能基于工具返回的真实数据上海22度晴朗组织出最终的回复给用户“上海目前天气晴朗气温22摄氏度湿度65%是个出门的好天气。”至此一个完整的“感知-思考-行动-反馈”的Agent行动循环就完成了。这个循环可以不断重复让Agent完成复杂的多步骤任务。3. 从协议到实践构建一个可工作的Agent循环理解了基本协议我们来看如何用代码将其串联起来构建一个真正能“动手”的Agent。这里我们以Python为例使用OpenAI的官方SDK实现一个简单的“天气时间查询助手”。3.1 环境准备与工具定义首先确保你已安装OpenAI Python包并设置好API密钥。pip install openai接下来在代码中定义我们Agent可以使用的工具。我们将定义两个工具查询天气和查询当前时间。import json from datetime import datetime import pytz # 需要安装pip install pytz # 模拟的工具函数实现 def get_current_weather(location: str, unit: str celsius) - str: 模拟获取天气数据。在实际应用中这里会调用如OpenWeatherMap的API。 # 模拟数据 weather_data { 北京: {temperature: 18, condition: 多云, humidity: 50%}, 上海: {temperature: 22, condition: 晴朗, humidity: 65%}, 旧金山: {temperature: 15, condition: 有雾, humidity: 80%} } data weather_data.get(location, {temperature: 20, condition: 未知, humidity: N/A}) temp data[temperature] if unit fahrenheit: temp temp * 9/5 32 return json.dumps({ location: location, temperature: temp, unit: unit, condition: data[condition], humidity: data[humidity] }, ensure_asciiFalse) def get_current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。 try: tz pytz.timezone(timezone) current_time datetime.now(tz).strftime(%Y-%m-%d %H:%M:%S %Z%z) return json.dumps({timezone: timezone, current_time: current_time}, ensure_asciiFalse) except pytz.exceptions.UnknownTimeZoneError: return json.dumps({error: f未知时区: {timezone}}, ensure_asciiFalse) # 工具定义列表用于发送给API tools_definition [ { type: function, function: { name: get_current_weather, description: 当用户询问天气、气候、温度、穿衣建议或出行计划时使用此工具。提供城市名称和可选单位摄氏度/华氏度。, parameters: { type: object, properties: { location: { type: string, description: 城市或地区的名称例如北京、Tokyo、New York。 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认为摄氏度celsius。, default: celsius } }, required: [location] } } }, { type: function, function: { name: get_current_time, description: 当用户询问时间、日期、时区或需要时间信息进行规划时使用此工具。可以指定时区。, parameters: { type: object, properties: { timezone: { type: string, description: IANA时区名称例如Asia/Shanghai, America/New_York, UTC。默认为Asia/Shanghai。, default: Asia/Shanghai } }, required: [] # 时区参数非必需有默认值 } } } ]注意事项默认值default的使用在JSON Schema中为参数设置default值非常有用。如上例中的unit和timezone。这能引导模型在用户未明确指定时使用合理的默认值而不是因为缺少参数而拒绝调用或胡乱猜测。这提升了交互的流畅性。3.2 核心循环逻辑实现Agent的核心是一个循环与模型对话处理工具调用返回结果直到模型给出最终回答。from openai import OpenAI import os # 初始化客户端建议从环境变量读取API Key client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) def run_agent_conversation(user_query: str, max_turns: int 5): 运行一个带有工具调用能力的Agent对话。 Args: user_query: 用户的初始问题。 max_turns: 最大对话轮次防止无限循环。 # 初始化对话历史 messages [ {role: system, content: 你是一个有用的助手可以查询天气和时间。请根据用户需求使用可用工具获取准确信息后回答。如果信息不足可以主动询问用户。}, {role: user, content: user_query} ] print(f用户: {user_query}) for turn in range(max_turns): # 1. 调用Chat Completion API传入当前对话历史和工具定义 response client.chat.completions.create( modelgpt-4, # 或 gpt-3.5-turbo messagesmessages, toolstools_definition, tool_choiceauto, # 让模型自行决定是否调用工具 ) assistant_message response.choices[0].message messages.append(assistant_message) # 将助手的回复可能是工具调用请求加入历史 # 2. 检查模型是否请求调用工具 if assistant_message.tool_calls: print(f\n[Agent 第{turn1}轮思考] 决定使用工具...) # 处理每一个工具调用请求支持并行 for tool_call in assistant_message.tool_calls: function_name tool_call.function.name function_args json.loads(tool_call.function.arguments) print(f 调用工具: {function_name}, 参数: {function_args}) # 3. 执行对应的工具函数 if function_name get_current_weather: function_response get_current_weather(**function_args) elif function_name get_current_time: function_response get_current_time(**function_args) else: function_response json.dumps({error: f未知工具: {function_name}}) # 4. 将工具执行结果作为一条新消息追加到历史 messages.append({ role: tool, tool_call_id: tool_call.id, # 关键匹配调用ID content: function_response, }) print(f 工具返回: {function_response[:100]}...) # 打印部分结果 # 本轮有工具调用需要继续循环让模型基于结果生成回复 continue # 5. 模型没有调用工具生成了最终文本回复 final_response assistant_message.content if final_response: print(f\n助手: {final_response}) break # 对话结束 else: # 理论上不会走到这里除非模型既没调用工具也没生成内容 print(\n助手: (无内容)) break else: # 如果循环达到最大轮次仍未结束 print(f\n对话已达到最大轮次({max_turns})可能陷入循环。) return messages # 运行示例 if __name__ __main__: history run_agent_conversation(我明天要去上海出差那边现在天气怎么样另外纽约现在是几点)代码逻辑详解初始化与首次调用我们以系统指令和用户问题开启对话并将工具定义tools_definition传给API。tool_choiceauto表示由模型自主决定是否及何时调用工具。解析模型响应检查响应中的assistant_message.tool_calls。如果非空说明模型请求调用工具。执行工具遍历每个tool_call根据name找到本地函数用arguments解析出的参数字典**function_args执行它。反馈结果将执行结果构造成tool角色的消息关键是一定要带上对应的tool_call_id然后追加到messages列表末尾。继续循环由于历史中新增了工具结果循环继续将新的messages列表包含工具结果再次发送给模型。生成最终回复当模型收到工具结果后它基于这些真实数据生成文本回复此时tool_calls为空content有值循环结束。这个for循环就模拟了Agent最核心的“思考-行动”循环。通过调整max_turns你可以控制Agent完成任务的最大步骤数。3.3 高级控制与参数解析在实际开发中你可能会遇到更复杂的情况需要对工具调用进行更精细的控制。tool_choice参数详解这个参数决定了模型在工具使用上的自由度。“auto”(默认): 模型自行决定是否调用工具以及调用哪个工具。这是最常用的模式。“none”: 模型将不会调用任何工具即使你定义了tools。这可以用于强制模型进行纯文本对话。{“type”: “function”, “function”: {“name”: “get_current_weather”}}:强制模型调用指定工具。当你明确知道下一步必须执行某个操作时例如在预定义的工作流中这非常有用。模型会尝试生成符合该工具参数结构的arguments。处理复杂的参数验证模型生成的arguments是一个JSON字符串你需要用json.loads()解析。但模型有时可能会生成格式略有瑕疵的JSON如尾随逗号或者参数值不完全符合预期。import json def safe_json_loads(json_str: str): 安全地解析JSON处理一些常见格式问题。 try: return json.loads(json_str) except json.JSONDecodeError as e: # 简单处理尝试修复尾随逗号仅适用于简单情况生产环境需更严谨 if e.msg Expecting property name enclosed in double quotes: # 这里可以添加更复杂的修复逻辑或记录日志 print(f警告JSON解析错误原始字符串: {json_str}) # 返回一个错误指示或在工具函数中处理 return {_error: fInvalid JSON: {e.msg}}并行工具调用Parallel Tool Calls处理从上面的代码可以看到tool_calls是一个数组。模型可以一次性请求调用多个工具。我们的循环逻辑已经通过for tool_call in assistant_message.tool_calls:进行了处理。这意味着当用户问“上海和北京的天气分别怎么样”时模型有可能在一个响应里同时请求调用两次get_current_weather工具分别传入不同的location参数。这能显著提升复杂任务的效率。实操心得管理对话历史长度在多轮复杂交互中messages数组会不断增长用户消息、助手消息、工具消息可能导致超过模型上下文窗口。你需要一个“历史管理”策略选择性保留只保留最近N轮对话或总结之前的对话内容。工具消息压缩工具返回的content可能很长如一大段网页摘要。可以尝试提取关键信息再喂给模型。使用长上下文模型对于超长对话优先选用如gpt-4-turbo或gpt-4o等支持128K上下文的模型。4. 避坑指南与效能优化协议和基础循环看似简单但在实际构建稳定、高效的Agent时会遇到不少坑。下面分享一些从实战中总结的经验。4.1 常见错误与排查问题现象可能原因解决方案模型完全不调用工具1. 工具描述 (description) 不清晰或与用户问题不匹配。2. 系统指令 (system) 过于宽泛未鼓励使用工具。3. 模型认为已知信息足以回答知识截止日期前。1. 重写工具描述使用更任务导向的语言包含典型用例。2. 在系统指令中明确要求“请优先使用提供的工具来获取最新或准确信息。”3. 对于需要实时数据的问题在系统指令中强调“你无法知道实时信息必须使用工具”。模型调用了错误的工具工具之间的描述区分度不够。让每个工具的description和name具有高度特异性。例如search_web和search_internal_doc的描述要明确区分应用场景。arguments解析失败1. 模型生成的JSON格式有轻微错误如缺少引号。2. 参数类型不匹配如期望数字却传了字符串。1. 使用json.loads()时增加容错处理如ast.literal_eval或尝试修复。2. 在工具函数内部进行参数类型转换和验证并返回友好错误信息。工具调用陷入死循环模型反复调用同一个工具或调用后无法得出最终结论。1. 检查工具返回的content是否清晰。模糊或错误的结果会导致模型困惑。2. 在系统指令中设定规则如“同一工具在同一会话中最多调用X次”。3. 实现最大轮次 (max_turns) 限制。API返回400错误提示“type” must be in [“enabled”, “disabled”, “auto”]tool_choice参数的值格式错误。tool_choice应是一个字符串 (“auto”,“none”) 或一个特定的字典对象 ({“type”: “function”, “function”: {“name”: “xxx”}})检查是否传错了字段名或值。API返回400错误提示上下文长度超限对话历史messages太长超过了模型的最大上下文长度如gpt-3.5-turbo的16K。1. 实施对话历史摘要或截断策略。2. 切换到支持更长上下文的模型如gpt-4-turbo-128k。3. 压缩工具返回的content只保留核心信息。4.2 提升工具调用准确性的技巧描述即契约把工具的description和parameters中的description字段当作给模型看的“产品说明书”来写。要具体、无歧义。好的描述示例“当用户需要将文本从一种语言翻译成另一种语言时使用此工具。必须指定源语言和目标语言。” 坏的描述“进行翻译。”提供示例Few-shot在system指令或早期的user消息中提供一两个正确使用工具的示例对话。这能极大地引导模型行为。强制与引导对于关键步骤可以使用tool_choice强制模型调用特定工具。对于一般情况在system指令中使用引导性语言如“你拥有以下工具[列出工具名]。在回答用户问题时请首先考虑是否需要使用这些工具来获取必要信息。”结构化输出确保工具函数返回的content是结构化的如JSON并且包含模型生成友好回复所需的所有关键字段。避免返回冗长的原始API响应。4.3 超越基础构建复杂Agent系统单个工具调用循环是基石。要构建能处理复杂任务的Agent你需要在此基础上设计更高级的模式。工具路由Router当工具很多时可以设计一个“元工具”或使用一个专门的LLM调用先分析用户意图决定调用哪个工具或哪一系列工具然后再进入执行循环。状态管理State ManagementAgent需要记忆自己的目标、已完成步骤和中间结果。这可以通过在system指令中维护一个“任务清单”或使用外部存储数据库、内存来实现。流程控制Workflow对于固定流程的任务如数据提取-清洗-分析-报告可以硬编码调用序列仅在需要决策的点让LLM参与。这比完全依赖LLM自发规划更可控。验证与回退Validation Fallback在工具执行后对结果进行验证。如果结果无效如天气API返回错误可以将错误信息反馈给模型让它决定是重试、询问用户还是采用备用方案。5. 协议之外的思考Agent架构的演进OpenAI的tools和function calling协议提供了一种标准、优雅的方式为LLM赋能。但它只是Agent生态中的一种实现模式。理解其本质后你可以更好地评估和使用其他框架。LangChain / LlamaIndex这些高阶框架在底层也使用了类似的协议与OpenAI模型交互。但它们提供了更丰富的抽象如“智能体Agent”、“工具Tool”、“执行器Executor”等概念以及内置的搜索引擎、计算器等大量现成工具。它们的价值在于提效和生态但底层原理是相通的。ReActReasoning Acting模式这是学术界提出的一种经典Agent推理框架要求模型以“Thought: ... Action: ... Observation: ...”的格式进行交互。OpenAI的协议可以看作是ReAct模式的一种简化且更工程化的实现将“Action”具体化为tool_calls将“Observation”具体化为tool消息。自主智能体Autonomous Agents如AutoGPT、BabyAGI等。它们通常内置了目标分解、长期记忆、任务队列等复杂模块工具调用只是其执行单元的一部分。它们可能使用OpenAI的协议也可能使用其他模型的类似接口。我个人在实际构建Agent系统的体会是从裸协议开始理解至关重要。这让你不被框架的黑箱所束缚能精准定位问题是工具描述问题还是循环逻辑问题也能在框架无法满足定制化需求时有能力自己动手实现核心逻辑。当你清晰地看到模型输出tool_calls的那一刻你就真正握住了让AI长出“手脚”的开关。 1. 项目概述当Agent学会“动手”最近和几个做AI应用的朋友聊天发现一个挺有意思的现象大家聊起Agent智能体时兴奋点往往集中在它的“大脑”上——用了哪个大模型、思维链Chain-of-Thought有多长、推理能力有多强。但聊到具体落地比如让Agent去订一张机票、自动整理一份周报、或者控制智能家居设备时气氛就有点微妙了。很多人会两手一摊说“这得等模型能力再强一点或者等某个框架把工具调用封装得更好。”这其实陷入了一个思维误区。我们总在期待一个“全能”的Agent却忽略了让Agent真正“活”起来、长出“手脚”去执行任务的关键往往不在模型内部而在模型与外部世界交互的“协议层”。这就像造一个机器人我们花了大量精力优化它的中央处理器CPU和算法却对如何给它安装机械臂、设计握持指令的接口语焉不详。今天我们就以最主流的OpenAI API为切入点抛开那些“黑箱”式的框架封装直接深入到API协议层面看看一个Agent是如何被“教会”使用工具的。你会发现所谓的“智能体行动”其核心机制远比想象中要清晰和结构化。理解了这个你不仅能更好地使用现成的Agent框架甚至能自己设计更贴合业务需求的工具调用逻辑。无论你是想深入Agent开发还是仅仅想用好ChatGPT的“自定义指令”或“GPTs”功能这篇文章都会帮你揭开那层神秘的面纱。2. 核心机制拆解OpenAI API中的“工具”与“函数调用”要理解Agent如何行动我们必须先搞清楚大模型本身是如何被“告知”它可以做什么以及它如何表达“我想做什么”。在OpenAI的API体系中这主要围绕两个核心概念展开tools工具和function calling函数调用。很多人会把它们混为一谈但其实它们扮演着不同的角色。2.1 角色定义系统、用户、助手与工具在OpenAI的聊天补全API中对话由一系列消息messages构成每条消息都有一个role角色。除了我们熟悉的system系统、user用户和assistant助手之外当涉及工具调用时会引入第四个角色tool。system: 设定助手的背景、行为和目标。例如“你是一个乐于助人的旅行助手专注于使用工具为用户查询信息。”user: 代表人类用户提出问题或发出指令。例如“帮我查一下下周五从北京飞往上海的航班。”assistant: 模型的回复。这里的关键是助理的回复可能包含两种内容1) 直接的文本回答2) 一个请求调用特定工具的“意图”声明。tool: 代表工具执行后的返回结果。当模型请求调用一个工具后开发者需要实际执行该工具函数然后将执行结果以tool角色的消息形式附加到对话历史中再送回给模型让它基于结果继续回复。这个tool角色的引入是模型能与外部世界进行“多轮”交互的基石。它把一次性的问答变成了一个“模型思考-请求行动-环境反馈-模型再思考”的循环。2.2 工具Tools的定义给模型一份“能力清单”工具本质上是一个声明。它告诉模型“嘿你现在拥有这些可用的外部能力。” 在API请求中我们通过tools参数来传递这个清单。每个工具都是一个JSON对象核心是type和function字段。目前type主要是function未来可能会有其他类型。function字段内则详细描述了这个函数。{ type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气情况。, parameters: { type: object, properties: { location: { type: string, description: 城市名称例如北京、San Francisco }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位摄氏度或华氏度。 } }, required: [location] } } }关键点解析name: 函数的唯一标识符。模型在决定调用时就靠这个名字来指定。description:这是最重要的部分模型完全依靠这段自然语言描述来理解这个工具是干什么的。描述必须清晰、准确最好包含使用场景和示例。模糊的描述会导致模型错误调用或根本不调用。parameters: 严格遵循JSON Schema格式定义。它定义了函数需要的参数、每个参数的类型、描述以及是否必需。enum列表能有效约束模型的输出范围。实操心得描述的艺术写工具描述时要站在模型的视角。不要写“查询天气数据”而要写“当用户询问天气、穿衣建议、或出行计划时使用此工具获取准确的温度、湿度和天气状况。” 前者是开发者视角后者是任务视角能极大提高模型调用的准确率。2.3 函数调用Function Calling的流程模型如何“举手”当我们把包含tools定义的请求发送给模型后模型并不会直接去执行工具。它做的第一件事是“思考”根据当前对话上下文和可用的工具列表判断是否需要调用工具以及调用哪一个。如果模型认为需要调用工具它会在回复中返回一个特殊结构而非常规的文本。这个结构包含在choices[0].message中关键字段是tool_calls。一个典型的模型“举手”请求调用的响应如下{ id: chatcmpl-xxx, object: chat.completion, created: 1700000000, model: gpt-4, choices: [{ index: 0, message: { role: assistant, content: null, tool_calls: [{ id: call_abc123, type: function, function: { name: get_current_weather, arguments: {\location\: \上海\, \unit\: \celsius\} } }] }, finish_reason: tool_calls }], usage: {...} }关键字段解读content: null: 当模型决定调用工具时其文本回复内容通常为空。它的“想法”已经通过tool_calls表达了。tool_calls: 一个数组理论上模型可以同时请求调用多个工具并行工具调用。每个元素代表一次调用请求。id: 本次调用的唯一ID非常重要在后续返回工具结果时需要用这个ID来匹配。function.name: 模型想调用的工具名称必须与之前tools参数中定义的某个name完全一致。function.arguments: 一个JSON格式的字符串。模型会根据工具定义中parameters的JSON Schema生成符合规范的参数。这里是{location: 上海, unit: celsius}。finish_reason: “tool_calls”: 停止原因明确表示模型停止生成是因为它发起了工具调用。这个过程就是模型“长出想法”的关键一步它将模糊的用户意图“上海天气怎么样”转化成了一个结构化的、可执行的行动指令调用get_current_weather函数参数为location上海。2.4 执行与反馈完成行动闭环模型发出了调用请求但它自己并不会执行。执行工具是开发者代码的责任。我们需要解析tool_calls中的name和arguments。在我们的后端代码中找到对应的函数比如一个真正调用天气API的函数。执行该函数并获得结果。然后我们必须将结果反馈给模型让模型进行“下一轮思考”。这是通过在下一次API请求的messages列表中追加一条role为tool的消息实现的。{ role: tool, content: {\temperature\: 22, \condition\: \晴朗\, \humidity\: \65%\}, tool_call_id: call_abc123 }关键字段解读role: “tool”: 明确这是一条工具执行结果的消息。tool_call_id:必须与模型请求中的idcall_abc123对应这是将结果与特定请求关联起来的唯一纽带。如果一次请求中有多个tool_calls你需要为每一个都返回对应的tool消息。content: 工具执行结果的字符串。可以是JSON字符串也可以是纯文本。内容应尽可能简洁、相关便于模型理解。当这条消息和之前的对话历史一起作为新的请求发送给模型时模型就能基于工具返回的真实数据上海22度晴朗组织出最终的回复给用户“上海目前天气晴朗气温22摄氏度湿度65%是个出门的好天气。”至此一个完整的“感知-思考-行动-反馈”的Agent行动循环就完成了。这个循环可以不断重复让Agent完成复杂的多步骤任务。3. 从协议到实践构建一个可工作的Agent循环理解了基本协议我们来看如何用代码将其串联起来构建一个真正能“动手”的Agent。这里我们以Python为例使用OpenAI的官方SDK实现一个简单的“天气时间查询助手”。3.1 环境准备与工具定义首先确保你已安装OpenAI Python包并设置好API密钥。pip install openai接下来在代码中定义我们Agent可以使用的工具。我们将定义两个工具查询天气和查询当前时间。import json from datetime import datetime import pytz # 需要安装pip install pytz # 模拟的工具函数实现 def get_current_weather(location: str, unit: str celsius) - str: 模拟获取天气数据。在实际应用中这里会调用如OpenWeatherMap的API。 # 模拟数据 weather_data { 北京: {temperature: 18, condition: 多云, humidity: 50%}, 上海: {temperature: 22, condition: 晴朗, humidity: 65%}, 旧金山: {temperature: 15, condition: 有雾, humidity: 80%} } data weather_data.get(location, {temperature: 20, condition: 未知, humidity: N/A}) temp data[temperature] if unit fahrenheit: temp temp * 9/5 32 return json.dumps({ location: location, temperature: temp, unit: unit, condition: data[condition], humidity: data[humidity] }, ensure_asciiFalse) def get_current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。 try: tz pytz.timezone(timezone) current_time datetime.now(tz).strftime(%Y-%m-%d %H:%M:%S %Z%z) return json.dumps({timezone: timezone, current_time: current_time}, ensure_asciiFalse) except pytz.exceptions.UnknownTimeZoneError: return json.dumps({error: f未知时区: {timezone}}, ensure_asciiFalse) # 工具定义列表用于发送给API tools_definition [ { type: function, function: { name: get_current_weather, description: 当用户询问天气、气候、温度、穿衣建议或出行计划时使用此工具。提供城市名称和可选单位摄氏度/华氏度。, parameters: { type: object, properties: { location: { type: string, description: 城市或地区的名称例如北京、Tokyo、New York。 }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认为摄氏度celsius。, default: celsius } }, required: [location] } } }, { type: function, function: { name: get_current_time, description: 当用户询问时间、日期、时区或需要时间信息进行规划时使用此工具。可以指定时区。, parameters: { type: object, properties: { timezone: { type: string, description: IANA时区名称例如Asia/Shanghai, America/New_York, UTC。默认为Asia/Shanghai。, default: Asia/Shanghai } }, required: [] # 时区参数非必需有默认值 } } } ]注意事项默认值default的使用在JSON Schema中为参数设置default值非常有用。如上例中的unit和timezone。这能引导模型在用户未明确指定时使用合理的默认值而不是因为缺少参数而拒绝调用或胡乱猜测。这提升了交互的流畅性。3.2 核心循环逻辑实现Agent的核心是一个循环与模型对话处理工具调用返回结果直到模型给出最终回答。from openai import OpenAI import os # 初始化客户端建议从环境变量读取API Key client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) def run_agent_conversation(user_query: str, max_turns: int 5): 运行一个带有工具调用能力的Agent对话。 Args: user_query: 用户的初始问题。 max_turns: 最大对话轮次防止无限循环。 # 初始化对话历史 messages [ {role: system, content: 你是一个有用的助手可以查询天气和时间。请根据用户需求使用可用工具获取准确信息后回答。如果信息不足可以主动询问用户。}, {role: user, content: user_query} ] print(f用户: {user_query}) for turn in range(max_turns): # 1. 调用Chat Completion API传入当前对话历史和工具定义 response client.chat.completions.create( modelgpt-4, # 或 gpt-3.5-turbo messagesmessages, toolstools_definition, tool_choiceauto, # 让模型自行决定是否调用工具 ) assistant_message response.choices[0].message messages.append(assistant_message) # 将助手的回复可能是工具调用请求加入历史 # 2. 检查模型是否请求调用工具 if assistant_message.tool_calls: print(f\n[Agent 第{turn1}轮思考] 决定使用工具...) # 处理每一个工具调用请求支持并行 for tool_call in assistant_message.tool_calls: function_name tool_call.function.name function_args json.loads(tool_call.function.arguments) print(f 调用工具: {function_name}, 参数: {function_args}) # 3. 执行对应的工具函数 if function_name get_current_weather: function_response get_current_weather(**function_args) elif function_name get_current_time: function_response get_current_time(**function_args) else: function_response json.dumps({error: f未知工具: {function_name}}) # 4. 将工具执行结果作为一条新消息追加到历史 messages.append({ role: tool, tool_call_id: tool_call.id, # 关键匹配调用ID content: function_response, }) print(f 工具返回: {function_response[:100]}...) # 打印部分结果 # 本轮有工具调用需要继续循环让模型基于结果生成回复 continue # 5. 模型没有调用工具生成了最终文本回复 final_response assistant_message.content if final_response: print(f\n助手: {final_response}) break # 对话结束 else: # 理论上不会走到这里除非模型既没调用工具也没生成内容 print(\n助手: (无内容)) break else: # 如果循环达到最大轮次仍未结束 print(f\n对话已达到最大轮次({max_turns})可能陷入循环。) return messages # 运行示例 if __name__ __main__: history run_agent_conversation(我明天要去上海出差那边现在天气怎么样另外纽约现在是几点)代码逻辑详解初始化与首次调用我们以系统指令和用户问题开启对话并将工具定义tools_definition传给API。tool_choiceauto表示由模型自主决定是否及何时调用工具。解析模型响应检查响应中的assistant_message.tool_calls。如果非空说明模型请求调用工具。执行工具遍历每个tool_call根据name找到本地函数用arguments解析出的参数字典**function_args执行它。反馈结果将执行结果构造成tool角色的消息关键是一定要带上对应的tool_call_id然后追加到messages列表末尾。继续循环由于历史中新增了工具结果循环继续将新的messages列表包含工具结果再次发送给模型。生成最终回复当模型收到工具结果后它基于这些真实数据生成文本回复此时tool_calls为空content有值循环结束。这个for循环就模拟了Agent最核心的“思考-行动”循环。通过调整max_turns你可以控制Agent完成任务的最大步骤数。3.3 高级控制与参数解析在实际开发中你可能会遇到更复杂的情况需要对工具调用进行更精细的控制。tool_choice参数详解这个参数决定了模型在工具使用上的自由度。“auto”(默认): 模型自行决定是否调用工具以及调用哪个工具。这是最常用的模式。“none”: 模型将不会调用任何工具即使你定义了tools。这可以用于强制模型进行纯文本对话。{“type”: “function”, “function”: {“name”: “get_current_weather”}}:强制模型调用指定工具。当你明确知道下一步必须执行某个操作时例如在预定义的工作流中这非常有用。模型会尝试生成符合该工具参数结构的arguments。处理复杂的参数验证模型生成的arguments是一个JSON字符串你需要用json.loads()解析。但模型有时可能会生成格式略有瑕疵的JSON如尾随逗号或者参数值不完全符合预期。import json def safe_json_loads(json_str: str): 安全地解析JSON处理一些常见格式问题。 try: return json.loads(json_str) except json.JSONDecodeError as e: # 简单处理尝试修复尾随逗号仅适用于简单情况生产环境需更严谨 if e.msg Expecting property name enclosed in double quotes: # 这里可以添加更复杂的修复逻辑或记录日志 print(f警告JSON解析错误原始字符串: {json_str}) # 返回一个错误指示或在工具函数中处理 return {_error: fInvalid JSON: {e.msg}}并行工具调用Parallel Tool Calls处理从上面的代码可以看到tool_calls是一个数组。模型可以一次性请求调用多个工具。我们的循环逻辑已经通过for tool_call in assistant_message.tool_calls:进行了处理。这意味着当用户问“上海和北京的天气分别怎么样”时模型有可能在一个响应里同时请求调用两次get_current_weather工具分别传入不同的location参数。这能显著提升复杂任务的效率。实操心得管理对话历史长度在多轮复杂交互中messages数组会不断增长用户消息、助手消息、工具消息可能导致超过模型上下文窗口。你需要一个“历史管理”策略选择性保留只保留最近N轮对话或总结之前的对话内容。工具消息压缩工具返回的content可能很长如一大段网页摘要。可以尝试提取关键信息再喂给模型。使用长上下文模型对于超长对话优先选用如gpt-4-turbo或gpt-4o等支持128K上下文的模型。4. 避坑指南与效能优化协议和基础循环看似简单但在实际构建稳定、高效的Agent时会遇到不少坑。下面分享一些从实战中总结的经验。4.1 常见错误与排查问题现象可能原因解决方案模型完全不调用工具1. 工具描述 (description) 不清晰或与用户问题不匹配。2. 系统指令 (system) 过于宽泛未鼓励使用工具。3. 模型认为已知信息足以回答知识截止日期前。1. 重写工具描述使用更任务导向的语言包含典型用例。2. 在系统指令中明确要求“请优先使用提供的工具来获取最新或准确信息。”3. 对于需要实时数据的问题在系统指令中强调“你无法知道实时信息必须使用工具”。模型调用了错误的工具工具之间的描述区分度不够。让每个工具的description和name具有高度特异性。例如search_web和search_internal_doc的描述要明确区分应用场景。arguments解析失败1. 模型生成的JSON格式有轻微错误如缺少引号。2. 参数类型不匹配如期望数字却传了字符串。1. 使用json.loads()时增加容错处理如ast.literal_eval或尝试修复。2. 在工具函数内部进行参数类型转换和验证并返回友好错误信息。工具调用陷入死循环模型反复调用同一个工具或调用后无法得出最终结论。1. 检查工具返回的content是否清晰。模糊或错误的结果会导致模型困惑。2. 在系统指令中设定规则如“同一工具在同一会话中最多调用X次”。3. 实现最大轮次 (max_turns) 限制。API返回400错误提示“type” must be in [“enabled”, “disabled”, “auto”]tool_choice参数的值格式错误。tool_choice应是一个字符串 (“auto”,“none”) 或一个特定的字典对象 ({“type”: “function”, “function”: {“name”: “xxx”}})检查是否传错了字段名或值。API返回400错误提示上下文长度超限对话历史messages太长超过了模型的最大上下文长度如gpt-3.5-turbo的16K。1. 实施对话历史摘要或截断策略。2. 切换到支持更长上下文的模型如gpt-4-turbo-128k。3. 压缩工具返回的content只保留核心信息。4.2 提升工具调用准确性的技巧描述即契约把工具的description和parameters中的description字段当作给模型看的“产品说明书”来写。要具体、无歧义。好的描述示例“当用户需要将文本从一种语言翻译成另一种语言时使用此工具。必须指定源语言和目标语言。” 坏的描述“进行翻译。”提供示例Few-shot在system指令或早期的user消息中提供一两个正确使用工具的示例对话。这能极大地引导模型行为。强制与引导对于关键步骤可以使用tool_choice强制模型调用特定工具。对于一般情况在system指令中使用引导性语言如“你拥有以下工具[列出工具名]。在回答用户问题时请首先考虑是否需要使用这些工具来获取必要信息。”结构化输出确保工具函数返回的content是结构化的如JSON并且包含模型生成友好回复所需的所有关键字段。避免返回冗长的原始API响应。4.3 超越基础构建复杂Agent系统单个工具调用循环是基石。要构建能处理复杂任务的Agent你需要在此基础上设计更高级的模式。工具路由Router当工具很多时可以设计一个“元工具”或使用一个专门的LLM调用先分析用户意图决定调用哪个工具或哪一系列工具然后再进入执行循环。状态管理State ManagementAgent需要记忆自己的目标、已完成步骤和中间结果。这可以通过在system指令中维护一个“任务清单”或使用外部存储数据库、内存来实现。流程控制Workflow对于固定流程的任务如数据提取-清洗-分析-报告可以硬编码调用序列仅在需要决策的点让LLM参与。这比完全依赖LLM自发规划更可控。验证与回退Validation Fallback在工具执行后对结果进行验证。如果结果无效如天气API返回错误可以将错误信息反馈给模型让它决定是重试、询问用户还是采用备用方案。5. 协议之外的思考Agent架构的演进OpenAI的tools和function calling协议提供了一种标准、优雅的方式为LLM赋能。但它只是Agent生态中的一种实现模式。理解其本质后你可以更好地评估和使用其他框架。LangChain / LlamaIndex这些高阶框架在底层也使用了类似的协议与OpenAI模型交互。但它们提供了更丰富的抽象如“智能体Agent”、“工具Tool”、“执行器Executor”等概念以及内置的搜索引擎、计算器等大量现成工具。它们的价值在于提效和生态但底层原理是相通的。ReActReasoning Acting模式这是学术界提出的一种经典Agent推理框架要求模型以“Thought: ... Action: ... Observation: ...”的格式进行交互。OpenAI的协议可以看作是ReAct模式的一种简化且更工程化的实现将“Action”具体化为tool_calls将“Observation”具体化为tool消息。自主智能体Autonomous Agents如AutoGPT、BabyAGI等。它们通常内置了目标分解、长期记忆、任务队列等复杂模块工具调用只是其执行单元的一部分。它们可能使用OpenAI的协议也可能使用其他模型的类似接口。我个人在实际构建Agent系统的体会是从裸协议开始理解至关重要。这让你不被框架的黑箱所束缚能精准定位问题是工具描述问题还是循环逻辑问题也能在框架无法满足定制化需求时有能力自己动手实现核心逻辑。当你清晰地看到模型输出tool_calls的那一刻你就真正握住了让AI长出“手脚”的开关。 
