写这篇东西之前我先说个背景。最近大模型圈子里的风向已经从“谁的对话体验更聪明”转到了“谁能让模型真正动手干活”。聊得再漂亮调不动接口、查不了数据、发不了通知那充其量就是个高级聊天框。Agent-Reach 这个项目说白了就是我在这个方向上的一次完整实践让智能体具备真正可用的“触达能力”从只会在对话框里输出文字变成能够稳定调用外部工具、执行实际操作、再基于结果继续推理的闭环系统。这个项目适合谁看如果你正在做 AI Agent 相关开发或者准备把大模型接进自己的业务系统却被工具调用不稳定、参数解析出错、多轮任务编排稀烂这些问题卡住那这篇文章应该能帮你少走不少弯路。我会从架构设计、工具描述规范、执行链路搭建写到踩坑实录尽量把能沉淀下来的经验都摊开讲。1. 项目概述为什么我把 Agent 的“触达能力”当作核心来做Agent-Reach 这个名字里有两个词Agent 好理解关键是 Reach。我当初给它起这个名字是想强调一个观点评估一个智能体的价值不能只看它能理解多少要看它能“触达”多远。理解只是输入侧的事情而触达是输出侧的能力——能不能真正影响外部世界能不能拿到真实数据再反馈给模型这才是智能体从演示走向有用的分水岭。1.1 Agent-Reach 想解决什么问题过去一段时间我陆续做过几个大模型落地的小项目发现一个很普遍的现象模型本身的能力已经够用了逻辑推理、文本生成、甚至代码补全都有不错的表现但一旦要让模型去调用真实的业务接口麻烦就来了。典型的三类问题模型输出的工具调用参数经常不合法要么少了必填字段要么枚举值乱填要么日期格式千奇百怪。工具执行完返回的结果往往是结构化数据直接塞回给模型模型经常“看不懂”导致下一轮推理完全跑偏。当用户一句话里包含多个连续任务时模型经常只完成第一步就停了缺少任务编排和状态记忆的能力。Agent-Reach 这个项目就是围绕这三个问题展开的。我不打算做一个依赖某个特定大模型厂商的封闭方案而是设计了一套与模型无关的工具调用中间层——任何支持函数调用Function Calling能力的模型都可以接入这套体系获得稳定的工具触达能力。1.2 为什么选“工具调用”作为第一步有人可能会问现在提 Agent 都是往多智能体协作、自主规划这些复杂方向走你这么保守只做工具调用是不是格局小了我的想法正好相反。工具调用是所有高阶能力的底座。多智能体协作本质上就是多个 Agent 互相把对方当作“工具”来调用自主规划拆开来也是“感知-决策-执行-反馈”的循环而其中每次执行都离不开工具调用。底座的稳定性如果不解决上面叠再多的层都是空中楼阁。举个例子你让 Agent 先查一下订单库存再算一下总价然后生成一张报表发给管理员。这个链路拆开看无非是三次工具调用加两次普通对话。但如果每次调用的成功率只有八成三次连续调用的成功率就掉到五成了。再叠加不同的工具类型整体可靠性根本没法看。Agent-Reach 的第一步就是把单次工具调用的成功率往上顶同时在架构上支持任务编排让多次调用可以串联起来。2. 架构设计给 Agent 装一套“会握手”的外设系统Agent 要触达外部世界不能靠意念必须有一套明确的“协议”。这套协议包括三部分模型怎么表达调用意图、系统怎么找到并执行对应的函数、执行结果怎么再反馈给模型。我们常说的 Function Calling本质就是这层协议的具体实现。2.1 整体链路从意图到执行我把 Agent-Reach 的处理链路分成五个环节每个环节都有清晰的责任边界意图解析用户输入进来之后模型根据系统提示词和工具描述判断当前是否需要调用工具如果需要则输出一个结构化的函数调用请求。参数校验系统拿到模型输出的函数名和参数后不直接执行先做一轮严格校验。确保函数名在注册表里存在、参数类型正确、必填项齐全、取值范围合法。工具执行校验通过后在受控环境中执行对应的工具函数记录执行日志、耗时、返回结果。结果标准化不管工具返回什么格式统一转换成模型友好的文本描述并附加状态信息如成功/失败/超时。反馈推理把标准化的结果拼接到对话上下文中重新交给模型让模型决定是结束任务还是继续调用下一个工具。这个链路看起来简单但我实际调试中花时间最多的地方全在容易被忽视的细节上。比如第 2 步的参数校验很多人觉得模型输出的 JSON 结构只要解析成功就可以了但真正跑起来你会发现模型经常把温度写成字符串 “25度”、把日期写成 “明天”、把枚举值大小写搞错。校验层如果不做容错和清洗光靠模型自觉翻车率会高到怀疑人生。2.2 工具描述一半的成败藏在函数签名里这是我最想强调的一点工具调用的成败很大程度上在你写工具描述的时候就已经决定了。模型不是人它不会“猜”你的函数是什么意思它只依赖你在工具描述里给出的信息。描述写得好模型自然调得准描述写得差后面加再多校验和兜底逻辑都是亡羊补牢。我总结了几条工具描述的经验函数名要动词开头表意直接。比如query_user_orders就比get_data_01强一万倍模型在语义理解上对这个名字的敏感度超乎想象。参数说明必须写明格式、单位、取值范围。比如日期参数你直接写date: 查询日期模型很可能给你输出 “2025-8-1” 或者 “昨天”但如果你写清楚date: 查询日期格式必须为 YYYY-MM-DD例如 2025-08-01准确率会有质的提升。对于有枚举限制的参数务必把可选项和对应含义都列出来。比如查询时间范围告诉模型range 只能取 1d、7d、30d不然它可能给你整出 “recent” 这种根本不存在的值。函数描述不要太长但要覆盖关键约束。有些同学喜欢把工具描述写成小作文其实反而干扰模型的注意力。控制在两三句话以内把参数规则说清楚就够了。2.3 执行沙箱与权限边界Agent 能触达外部世界同时也意味着它拥有了一定的“破坏力”。我见过很多早期 Agent 项目死在权限失控上——工具函数里直接写死了数据库连接Agent 一被提示词注入就可能执行危险的删除操作。Agent-Reach 在设计上从第一天起就引入了执行沙箱的概念每个工具函数运行在独立的执行环境中不共享全局变量。工具能访问的资源必须在注册时显式声明。比如某个工具需要读文件只能读指定目录下的文件需要访问网络只能访问白名单内的域名。所有工具执行都会记录审计日志包括调用者身份如果有、时间、入参、出参、耗时。这套设计在初版看起来有点“重”但后来的实践证明了它的价值。尤其是当你把 Agent 接入到生产环境任何一次工具调用都可能对应真实的业务操作权限边界就是安全和失控之间的防火墙。3. 实操过程从零搭一个能查天气、算金额的 Agent 工具链理论讲了这么多还是得落在代码上。我带大家走一遍 Agent-Reach 最小可用版本的完整实现。这个版本我刻意保持轻量不依赖任何重型框架方便你理解底层机制如果你后续要上生产再往里面加持久化、并发控制、可观测性这些加强件。3.1 最基础的工具注册流程我的做法是维护一个全局的工具注册表每个工具由名称、描述、参数 Schema、执行函数四部分组成。注册工具使用装饰器语法写起来很干净# registry.py class ToolRegistry: def __init__(self): self._tools {} def register(self, name, description, parameters_schema): 注册工具的装饰器工厂 def decorator(func): self._tools[name] { name: name, description: description, parameters: parameters_schema, func: func, enabled: True, } return func return decorator def get(self, name): return self._tools.get(name) def list_tools(self): return [ {name: t[name], description: t[description], parameters: t[parameters]} for t in self._tools.values() if t[enabled] ] registry ToolRegistry()然后定义两个基础工具一个查天气一个做计算# tools.py import json import random from registry import registry registry.register( nameget_weather, description查询指定城市和日期的天气情况。日期格式必须为 YYYY-MM-DD。, parameters_schema{ type: object, properties: { city: {type: string, description: 城市名称如 北京、上海}, date: {type: string, description: 查询日期格式 YYYY-MM-DD例如 2025-08-01}, }, required: [city, date], }, ) def get_weather(city: str, date: str) - dict: # 这里接入真实天气服务演示阶段返回模拟数据 mock_weather {北京: 晴 25-32°C, 上海: 多云 26-33°C} return { city: city, date: date, weather: mock_weather.get(city, 未知), source: mock, } registry.register( namecalculate, description计算数学表达式例如 (12.5 * 3 8) / 2。只支持四则运算和括号。, parameters_schema{ type: object, properties: { expression: {type: string, description: 数学表达式字符串}, }, required: [expression], }, ) def calculate(expression: str) - dict: # 安全起见这里用 eval 前必须做表达式清洗生产环境建议用 ast 或专门计算库 cleaned expression.replace( , ) allowed set(0123456789-*/().%) if not set(cleaned).issubset(allowed): raise ValueError(表达式包含非法字符) result eval(cleaned, {__builtins__: {}}, {}) return {expression: cleaned, result: result}这个阶段的注册表只是把工具信息收集起来了真正的核心在于下一步把工具描述喂给模型让模型学会在合适的时机发起调用。3.2 让 Agent 学会“带参数”调用模型本身不具备调用工具的能力——至少当前主流对话模型不会主动去调用。需要我们在请求里附带工具定义模型才会在回复中输出结构化的函数调用意图。以 OpenAI 兼容接口为例请求的结构大致是这样的import json from registry import registry def build_messages_with_tool_result(user_query, tool_resultsNone): messages [ {role: system, content: 你是一个能调用工具完成任务的助手。如果需要查询实时数据或进行计算请调用相应工具。}, {role: user, content: user_query}, ] if tool_results: for tr in tool_results: messages.append({role: tool, tool_call_id: tr[tool_call_id], content: json.dumps(tr[content], ensure_asciiFalse)}) return messages def call_model(messages, tools): # 这里用简化的方式示意实际需要根据你选择的模型 SDK 调整 # 核心是传入 messages 和 tools 两个关键参数 response your_model_sdk.chat.completions.create( modelyour-model-name, messagesmessages, toolstools, # 工具列表来源于 registry.list_tools() tool_choiceauto, ) return response.choices[0].messagetools参数需要符合模型的接口规范通常是把注册表里的描述转换成模型要求的格式。这里的关键在于模型返回的内容里会多出tool_calls字段里面包含了它想调用的函数名和参数 JSON。我们拿到这个信息后去注册表里查找函数并执行def execute_tool_call(tool_call): # tool_call 结构参考{id: call_xxx, function: {name: get_weather, arguments: {\city\: \北京\, \date\: \2025-08-01\}}} func_name tool_call[function][name] arguments json.loads(tool_call[function][arguments]) tool registry.get(func_name) if not tool: raise ValueError(f工具 {func_name} 不存在) # 执行前校验参数 validated_args validate_arguments(arguments, tool[parameters]) result tool[func](**validated_args) return { tool_call_id: tool_call[id], content: result, }这一步是整个链路的桥梁。模型输出的arguments是一个 JSON 字符串解析之后我们要做校验防止模型填了非法参数。校验逻辑可以写得简单点先保证类型正确def validate_arguments(args, schema): properties schema.get(properties, {}) validated {} for name, prop in properties.items(): if name not in args: # 不在 required 中的参数可以跳过 continue value args[name] expected_type prop.get(type) if expected_type string and not isinstance(value, str): validated[name] str(value) elif expected_type number and isinstance(value, str): try: validated[name] float(value) except ValueError: validated[name] 0.0 elif expected_type integer and isinstance(value, str): try: validated[name] int(value) except ValueError: validated[name] 0 else: validated[name] value return validated3.3 多轮对话中的工具编排单次工具调用只是最小闭环实际使用中用户往往会提出更复杂的诉求。比如“北京明天天气怎么样如果最高温度超过 30 度帮我算一下从上海飞北京的机票总价含税按 12% 算。”这句话里包含两个工具调用先查天气再根据温度条件决定是否计算机票。模型需要通过两轮甚至多轮推理才能完成。这就是 Agent 循环的用武之地。Agent-Reach 的主循环逻辑并不复杂核心是一个 while 循环def agent_loop(user_query, max_iterations5): messages build_messages_with_tool_result(user_query) for _ in range(max_iterations): response_msg call_model(messages, toolsregistry.list_tools()) if response_msg.tool_calls: # 把模型的工具调用响应先追加到消息历史中 messages.append(response_msg) current_results [] for tool_call in response_msg.tool_calls: result execute_tool_call(tool_call) current_results.append(result) print(f[Agent-Reach] 调用工具 {tool_call[function][name]} - {result[content]}) # 再把工具结果追加到消息历史中模型会基于结果继续推理 tool_result_message {role: tool, tool_call_id: result[tool_call_id], content: json.dumps(result[content], ensure_asciiFalse)} messages.append(tool_result_message) else: # 没有工具调用说明模型已经可以直接回答返回最终回复 return response_msg.content return 已达到最大迭代次数任务未完成这个循环有几点细节值得注意最大迭代次数必须设置否则模型可能陷入无限调用工具的循环损耗 token 也损耗时间。每一轮工具调用的结果都需要放进对话上下文模型才能基于最新数据做下一步推理。如果在同一次响应里返回多个 tool_calls并行调用要逐个执行并收集结果再一次性反馈给模型。用这个循环跑几轮你会看到一个完整的 Agent 闭环模型先调天气工具拿到温度再根据条件决定是否调计算工具最后综合所有信息输出最终的答案。这就是 Agent 从“只会说”到“能干活”的底层机制。4. 常见问题与排查心得实操过程中踩过的坑比我想象的多有的是模型侧的脾性使然有的是架构设计时欠考虑。我把最典型的几类问题整理了一份速查表附带我的排查思路希望能帮你少走一些弯路。4.1 模型总是“幻觉参数”怎么办这个问题的典型表现是模型明明拿到了工具描述里面写清楚了参数格式它还是会在调用时输出一个不存在的参数名或者把日期格式写错。我试过的几种解法按效果排列在参数描述里增加“示例值”。模型对小样本非常敏感一个放在描述里的示例值效果远超你写十句规则。比如日期参数描述写成格式 YYYY-MM-DD例如 2025-08-01调用成功率立刻上升。在系统提示词里增加“工具调用规范”。比如明确要求“调用工具前必须检查参数格式符合描述要求如果用户提供的信息不足请先向用户确认”。这一招能明显减少模型强行猜测参数的情况。在参数校验层做模糊归一。比如把“今天”“明天”这类相对日期转换成具体日期把“二十五度”转换成数字 25。虽然这不是根治方案但能兜住不少边缘情况。4.2 工具返回结果反喂给模型时的格式陷阱执行完工具之后我们拿到的是 Python 字典但模型需要的是字符串。很多人图省事直接str(result)一把梭结果模型读到的是一堆单引号包裹的 Python dict 文本经常解析出错。我的做法是统一用json.dumps(result, ensure_asciiFalse)序列化并且给每种工具定义了一个“对模型友好的摘要器”把最关键的字段提取出来组成一段描述性文字。比如订单查询工具原始返回可能是{ order_id: A12345, status: paid, total_amount: 399.00, items: [{name: 键盘, price: 199.00}, {name: 鼠标, price: 200.00}], created_at: 2025-07-20 14:30:00 }直接丢给模型它也能看但不够高效。我更推荐先转换成这样订单 A12345 状态为已支付创建于 2025-07-20 14:30:00共 2 件商品总金额 399.00 元。商品明细键盘 199.00 元鼠标 200.00 元。模型拿到这种结果后几乎不需要额外推理就能直接回答用户整个链路的稳定性和响应速度都提升了不少。4.3 工具执行失败后模型重复调用工具调用不总是成功的遇到网络超时、数据为空、计算异常时模型如果只看到“失败”两个字很容易反复调用同一个工具白白消耗 token 和时间。解决的办法是把错误信息也标准化成结构化内容反馈给模型并且附带建议的下一步行动。比如工具执行失败查询订单接口超时超过 5000ms。建议稍后重试或提示用户稍后再试。如果失败原因可能是参数不合法还可以让系统主动修正参数后重试一次。但要注意设置重试上限最多重试两三次避免进入死循环。4.4 一个经常被忽视的坑工具描述里的“过度承诺”写工具描述的时候我们很容易把功能写得特别全面总想着让模型充分了解工具能力。但实际效果恰恰相反描述过长过全模型反而更容易误用。我遇到过最典型的情况一个发短信工具描述里写了“可以用来发送验证码、营销短信、系统通知、告警消息”。结果模型在判断是否调用时经常把一些本来不应触发短信的场景也调用了。后来我把描述改成“发送短信通知发送前必须确认用户已授权接收通知”并明确限制了“不要将该工具用于发送营销广告”。误用率立刻降了下来。这背后的逻辑是模型并不具备人类的常识判断力它只能依据描述字面意思来匹配意图。描述里的每一个能力点都可能在某个语境下被它选中。所以工具描述要尽量克制只写核心功能明确边界约束。5. 有一点体会想留下来Agent-Reach 做到这个阶段给我最大的感受是所谓智能体并不存在什么神秘的“自主意识”它做到的每一步背后都是极致的工程约束和细节打磨。模型负责天马行空地理解意图而我们这些做系统的则负责在地面上画好跑道让它每一次触达都稳定、可控、可追溯。如果你也正在往 Agent 方向做我建议你先别急着上多智能体、规划算法这些花活踏踏实实把单次工具调用的成功率打到 95% 以上再把工具之间的编排串起来。很多看似复杂的问题往往就是基础链路不稳被放大的结果。把这层地基打牢后面盖什么楼都会顺手很多。
Agent-Reach实践：让大模型Agent稳定调用工具与外部系统
写这篇东西之前我先说个背景。最近大模型圈子里的风向已经从“谁的对话体验更聪明”转到了“谁能让模型真正动手干活”。聊得再漂亮调不动接口、查不了数据、发不了通知那充其量就是个高级聊天框。Agent-Reach 这个项目说白了就是我在这个方向上的一次完整实践让智能体具备真正可用的“触达能力”从只会在对话框里输出文字变成能够稳定调用外部工具、执行实际操作、再基于结果继续推理的闭环系统。这个项目适合谁看如果你正在做 AI Agent 相关开发或者准备把大模型接进自己的业务系统却被工具调用不稳定、参数解析出错、多轮任务编排稀烂这些问题卡住那这篇文章应该能帮你少走不少弯路。我会从架构设计、工具描述规范、执行链路搭建写到踩坑实录尽量把能沉淀下来的经验都摊开讲。1. 项目概述为什么我把 Agent 的“触达能力”当作核心来做Agent-Reach 这个名字里有两个词Agent 好理解关键是 Reach。我当初给它起这个名字是想强调一个观点评估一个智能体的价值不能只看它能理解多少要看它能“触达”多远。理解只是输入侧的事情而触达是输出侧的能力——能不能真正影响外部世界能不能拿到真实数据再反馈给模型这才是智能体从演示走向有用的分水岭。1.1 Agent-Reach 想解决什么问题过去一段时间我陆续做过几个大模型落地的小项目发现一个很普遍的现象模型本身的能力已经够用了逻辑推理、文本生成、甚至代码补全都有不错的表现但一旦要让模型去调用真实的业务接口麻烦就来了。典型的三类问题模型输出的工具调用参数经常不合法要么少了必填字段要么枚举值乱填要么日期格式千奇百怪。工具执行完返回的结果往往是结构化数据直接塞回给模型模型经常“看不懂”导致下一轮推理完全跑偏。当用户一句话里包含多个连续任务时模型经常只完成第一步就停了缺少任务编排和状态记忆的能力。Agent-Reach 这个项目就是围绕这三个问题展开的。我不打算做一个依赖某个特定大模型厂商的封闭方案而是设计了一套与模型无关的工具调用中间层——任何支持函数调用Function Calling能力的模型都可以接入这套体系获得稳定的工具触达能力。1.2 为什么选“工具调用”作为第一步有人可能会问现在提 Agent 都是往多智能体协作、自主规划这些复杂方向走你这么保守只做工具调用是不是格局小了我的想法正好相反。工具调用是所有高阶能力的底座。多智能体协作本质上就是多个 Agent 互相把对方当作“工具”来调用自主规划拆开来也是“感知-决策-执行-反馈”的循环而其中每次执行都离不开工具调用。底座的稳定性如果不解决上面叠再多的层都是空中楼阁。举个例子你让 Agent 先查一下订单库存再算一下总价然后生成一张报表发给管理员。这个链路拆开看无非是三次工具调用加两次普通对话。但如果每次调用的成功率只有八成三次连续调用的成功率就掉到五成了。再叠加不同的工具类型整体可靠性根本没法看。Agent-Reach 的第一步就是把单次工具调用的成功率往上顶同时在架构上支持任务编排让多次调用可以串联起来。2. 架构设计给 Agent 装一套“会握手”的外设系统Agent 要触达外部世界不能靠意念必须有一套明确的“协议”。这套协议包括三部分模型怎么表达调用意图、系统怎么找到并执行对应的函数、执行结果怎么再反馈给模型。我们常说的 Function Calling本质就是这层协议的具体实现。2.1 整体链路从意图到执行我把 Agent-Reach 的处理链路分成五个环节每个环节都有清晰的责任边界意图解析用户输入进来之后模型根据系统提示词和工具描述判断当前是否需要调用工具如果需要则输出一个结构化的函数调用请求。参数校验系统拿到模型输出的函数名和参数后不直接执行先做一轮严格校验。确保函数名在注册表里存在、参数类型正确、必填项齐全、取值范围合法。工具执行校验通过后在受控环境中执行对应的工具函数记录执行日志、耗时、返回结果。结果标准化不管工具返回什么格式统一转换成模型友好的文本描述并附加状态信息如成功/失败/超时。反馈推理把标准化的结果拼接到对话上下文中重新交给模型让模型决定是结束任务还是继续调用下一个工具。这个链路看起来简单但我实际调试中花时间最多的地方全在容易被忽视的细节上。比如第 2 步的参数校验很多人觉得模型输出的 JSON 结构只要解析成功就可以了但真正跑起来你会发现模型经常把温度写成字符串 “25度”、把日期写成 “明天”、把枚举值大小写搞错。校验层如果不做容错和清洗光靠模型自觉翻车率会高到怀疑人生。2.2 工具描述一半的成败藏在函数签名里这是我最想强调的一点工具调用的成败很大程度上在你写工具描述的时候就已经决定了。模型不是人它不会“猜”你的函数是什么意思它只依赖你在工具描述里给出的信息。描述写得好模型自然调得准描述写得差后面加再多校验和兜底逻辑都是亡羊补牢。我总结了几条工具描述的经验函数名要动词开头表意直接。比如query_user_orders就比get_data_01强一万倍模型在语义理解上对这个名字的敏感度超乎想象。参数说明必须写明格式、单位、取值范围。比如日期参数你直接写date: 查询日期模型很可能给你输出 “2025-8-1” 或者 “昨天”但如果你写清楚date: 查询日期格式必须为 YYYY-MM-DD例如 2025-08-01准确率会有质的提升。对于有枚举限制的参数务必把可选项和对应含义都列出来。比如查询时间范围告诉模型range 只能取 1d、7d、30d不然它可能给你整出 “recent” 这种根本不存在的值。函数描述不要太长但要覆盖关键约束。有些同学喜欢把工具描述写成小作文其实反而干扰模型的注意力。控制在两三句话以内把参数规则说清楚就够了。2.3 执行沙箱与权限边界Agent 能触达外部世界同时也意味着它拥有了一定的“破坏力”。我见过很多早期 Agent 项目死在权限失控上——工具函数里直接写死了数据库连接Agent 一被提示词注入就可能执行危险的删除操作。Agent-Reach 在设计上从第一天起就引入了执行沙箱的概念每个工具函数运行在独立的执行环境中不共享全局变量。工具能访问的资源必须在注册时显式声明。比如某个工具需要读文件只能读指定目录下的文件需要访问网络只能访问白名单内的域名。所有工具执行都会记录审计日志包括调用者身份如果有、时间、入参、出参、耗时。这套设计在初版看起来有点“重”但后来的实践证明了它的价值。尤其是当你把 Agent 接入到生产环境任何一次工具调用都可能对应真实的业务操作权限边界就是安全和失控之间的防火墙。3. 实操过程从零搭一个能查天气、算金额的 Agent 工具链理论讲了这么多还是得落在代码上。我带大家走一遍 Agent-Reach 最小可用版本的完整实现。这个版本我刻意保持轻量不依赖任何重型框架方便你理解底层机制如果你后续要上生产再往里面加持久化、并发控制、可观测性这些加强件。3.1 最基础的工具注册流程我的做法是维护一个全局的工具注册表每个工具由名称、描述、参数 Schema、执行函数四部分组成。注册工具使用装饰器语法写起来很干净# registry.py class ToolRegistry: def __init__(self): self._tools {} def register(self, name, description, parameters_schema): 注册工具的装饰器工厂 def decorator(func): self._tools[name] { name: name, description: description, parameters: parameters_schema, func: func, enabled: True, } return func return decorator def get(self, name): return self._tools.get(name) def list_tools(self): return [ {name: t[name], description: t[description], parameters: t[parameters]} for t in self._tools.values() if t[enabled] ] registry ToolRegistry()然后定义两个基础工具一个查天气一个做计算# tools.py import json import random from registry import registry registry.register( nameget_weather, description查询指定城市和日期的天气情况。日期格式必须为 YYYY-MM-DD。, parameters_schema{ type: object, properties: { city: {type: string, description: 城市名称如 北京、上海}, date: {type: string, description: 查询日期格式 YYYY-MM-DD例如 2025-08-01}, }, required: [city, date], }, ) def get_weather(city: str, date: str) - dict: # 这里接入真实天气服务演示阶段返回模拟数据 mock_weather {北京: 晴 25-32°C, 上海: 多云 26-33°C} return { city: city, date: date, weather: mock_weather.get(city, 未知), source: mock, } registry.register( namecalculate, description计算数学表达式例如 (12.5 * 3 8) / 2。只支持四则运算和括号。, parameters_schema{ type: object, properties: { expression: {type: string, description: 数学表达式字符串}, }, required: [expression], }, ) def calculate(expression: str) - dict: # 安全起见这里用 eval 前必须做表达式清洗生产环境建议用 ast 或专门计算库 cleaned expression.replace( , ) allowed set(0123456789-*/().%) if not set(cleaned).issubset(allowed): raise ValueError(表达式包含非法字符) result eval(cleaned, {__builtins__: {}}, {}) return {expression: cleaned, result: result}这个阶段的注册表只是把工具信息收集起来了真正的核心在于下一步把工具描述喂给模型让模型学会在合适的时机发起调用。3.2 让 Agent 学会“带参数”调用模型本身不具备调用工具的能力——至少当前主流对话模型不会主动去调用。需要我们在请求里附带工具定义模型才会在回复中输出结构化的函数调用意图。以 OpenAI 兼容接口为例请求的结构大致是这样的import json from registry import registry def build_messages_with_tool_result(user_query, tool_resultsNone): messages [ {role: system, content: 你是一个能调用工具完成任务的助手。如果需要查询实时数据或进行计算请调用相应工具。}, {role: user, content: user_query}, ] if tool_results: for tr in tool_results: messages.append({role: tool, tool_call_id: tr[tool_call_id], content: json.dumps(tr[content], ensure_asciiFalse)}) return messages def call_model(messages, tools): # 这里用简化的方式示意实际需要根据你选择的模型 SDK 调整 # 核心是传入 messages 和 tools 两个关键参数 response your_model_sdk.chat.completions.create( modelyour-model-name, messagesmessages, toolstools, # 工具列表来源于 registry.list_tools() tool_choiceauto, ) return response.choices[0].messagetools参数需要符合模型的接口规范通常是把注册表里的描述转换成模型要求的格式。这里的关键在于模型返回的内容里会多出tool_calls字段里面包含了它想调用的函数名和参数 JSON。我们拿到这个信息后去注册表里查找函数并执行def execute_tool_call(tool_call): # tool_call 结构参考{id: call_xxx, function: {name: get_weather, arguments: {\city\: \北京\, \date\: \2025-08-01\}}} func_name tool_call[function][name] arguments json.loads(tool_call[function][arguments]) tool registry.get(func_name) if not tool: raise ValueError(f工具 {func_name} 不存在) # 执行前校验参数 validated_args validate_arguments(arguments, tool[parameters]) result tool[func](**validated_args) return { tool_call_id: tool_call[id], content: result, }这一步是整个链路的桥梁。模型输出的arguments是一个 JSON 字符串解析之后我们要做校验防止模型填了非法参数。校验逻辑可以写得简单点先保证类型正确def validate_arguments(args, schema): properties schema.get(properties, {}) validated {} for name, prop in properties.items(): if name not in args: # 不在 required 中的参数可以跳过 continue value args[name] expected_type prop.get(type) if expected_type string and not isinstance(value, str): validated[name] str(value) elif expected_type number and isinstance(value, str): try: validated[name] float(value) except ValueError: validated[name] 0.0 elif expected_type integer and isinstance(value, str): try: validated[name] int(value) except ValueError: validated[name] 0 else: validated[name] value return validated3.3 多轮对话中的工具编排单次工具调用只是最小闭环实际使用中用户往往会提出更复杂的诉求。比如“北京明天天气怎么样如果最高温度超过 30 度帮我算一下从上海飞北京的机票总价含税按 12% 算。”这句话里包含两个工具调用先查天气再根据温度条件决定是否计算机票。模型需要通过两轮甚至多轮推理才能完成。这就是 Agent 循环的用武之地。Agent-Reach 的主循环逻辑并不复杂核心是一个 while 循环def agent_loop(user_query, max_iterations5): messages build_messages_with_tool_result(user_query) for _ in range(max_iterations): response_msg call_model(messages, toolsregistry.list_tools()) if response_msg.tool_calls: # 把模型的工具调用响应先追加到消息历史中 messages.append(response_msg) current_results [] for tool_call in response_msg.tool_calls: result execute_tool_call(tool_call) current_results.append(result) print(f[Agent-Reach] 调用工具 {tool_call[function][name]} - {result[content]}) # 再把工具结果追加到消息历史中模型会基于结果继续推理 tool_result_message {role: tool, tool_call_id: result[tool_call_id], content: json.dumps(result[content], ensure_asciiFalse)} messages.append(tool_result_message) else: # 没有工具调用说明模型已经可以直接回答返回最终回复 return response_msg.content return 已达到最大迭代次数任务未完成这个循环有几点细节值得注意最大迭代次数必须设置否则模型可能陷入无限调用工具的循环损耗 token 也损耗时间。每一轮工具调用的结果都需要放进对话上下文模型才能基于最新数据做下一步推理。如果在同一次响应里返回多个 tool_calls并行调用要逐个执行并收集结果再一次性反馈给模型。用这个循环跑几轮你会看到一个完整的 Agent 闭环模型先调天气工具拿到温度再根据条件决定是否调计算工具最后综合所有信息输出最终的答案。这就是 Agent 从“只会说”到“能干活”的底层机制。4. 常见问题与排查心得实操过程中踩过的坑比我想象的多有的是模型侧的脾性使然有的是架构设计时欠考虑。我把最典型的几类问题整理了一份速查表附带我的排查思路希望能帮你少走一些弯路。4.1 模型总是“幻觉参数”怎么办这个问题的典型表现是模型明明拿到了工具描述里面写清楚了参数格式它还是会在调用时输出一个不存在的参数名或者把日期格式写错。我试过的几种解法按效果排列在参数描述里增加“示例值”。模型对小样本非常敏感一个放在描述里的示例值效果远超你写十句规则。比如日期参数描述写成格式 YYYY-MM-DD例如 2025-08-01调用成功率立刻上升。在系统提示词里增加“工具调用规范”。比如明确要求“调用工具前必须检查参数格式符合描述要求如果用户提供的信息不足请先向用户确认”。这一招能明显减少模型强行猜测参数的情况。在参数校验层做模糊归一。比如把“今天”“明天”这类相对日期转换成具体日期把“二十五度”转换成数字 25。虽然这不是根治方案但能兜住不少边缘情况。4.2 工具返回结果反喂给模型时的格式陷阱执行完工具之后我们拿到的是 Python 字典但模型需要的是字符串。很多人图省事直接str(result)一把梭结果模型读到的是一堆单引号包裹的 Python dict 文本经常解析出错。我的做法是统一用json.dumps(result, ensure_asciiFalse)序列化并且给每种工具定义了一个“对模型友好的摘要器”把最关键的字段提取出来组成一段描述性文字。比如订单查询工具原始返回可能是{ order_id: A12345, status: paid, total_amount: 399.00, items: [{name: 键盘, price: 199.00}, {name: 鼠标, price: 200.00}], created_at: 2025-07-20 14:30:00 }直接丢给模型它也能看但不够高效。我更推荐先转换成这样订单 A12345 状态为已支付创建于 2025-07-20 14:30:00共 2 件商品总金额 399.00 元。商品明细键盘 199.00 元鼠标 200.00 元。模型拿到这种结果后几乎不需要额外推理就能直接回答用户整个链路的稳定性和响应速度都提升了不少。4.3 工具执行失败后模型重复调用工具调用不总是成功的遇到网络超时、数据为空、计算异常时模型如果只看到“失败”两个字很容易反复调用同一个工具白白消耗 token 和时间。解决的办法是把错误信息也标准化成结构化内容反馈给模型并且附带建议的下一步行动。比如工具执行失败查询订单接口超时超过 5000ms。建议稍后重试或提示用户稍后再试。如果失败原因可能是参数不合法还可以让系统主动修正参数后重试一次。但要注意设置重试上限最多重试两三次避免进入死循环。4.4 一个经常被忽视的坑工具描述里的“过度承诺”写工具描述的时候我们很容易把功能写得特别全面总想着让模型充分了解工具能力。但实际效果恰恰相反描述过长过全模型反而更容易误用。我遇到过最典型的情况一个发短信工具描述里写了“可以用来发送验证码、营销短信、系统通知、告警消息”。结果模型在判断是否调用时经常把一些本来不应触发短信的场景也调用了。后来我把描述改成“发送短信通知发送前必须确认用户已授权接收通知”并明确限制了“不要将该工具用于发送营销广告”。误用率立刻降了下来。这背后的逻辑是模型并不具备人类的常识判断力它只能依据描述字面意思来匹配意图。描述里的每一个能力点都可能在某个语境下被它选中。所以工具描述要尽量克制只写核心功能明确边界约束。5. 有一点体会想留下来Agent-Reach 做到这个阶段给我最大的感受是所谓智能体并不存在什么神秘的“自主意识”它做到的每一步背后都是极致的工程约束和细节打磨。模型负责天马行空地理解意图而我们这些做系统的则负责在地面上画好跑道让它每一次触达都稳定、可控、可追溯。如果你也正在往 Agent 方向做我建议你先别急着上多智能体、规划算法这些花活踏踏实实把单次工具调用的成功率打到 95% 以上再把工具之间的编排串起来。很多看似复杂的问题往往就是基础链路不稳被放大的结果。把这层地基打牢后面盖什么楼都会顺手很多。
