最近我一直在鼓捣一个叫 Agent-Reach 的项目说实话这个名字一开始就是我随手敲出来的代号后来越做越觉得贴切——Reach够得着。现在圈子里做个 Agent demo 很容易让大模型接上对话窗口能写诗、能编故事、能给你规划旅行路线张口就来。可真到生产环境里让 Agent 去查一条订单状态、改一份合同文档、发一封通知邮件成功率立刻掉下来。这不是模型变笨了而是缺了让智能体真正“够得着”外部世界的那套运行时机制。Agent-Reach 想解决的就是这个从“能聊”到“能办”的断层问题。这篇文章我会从项目定位、核心架构、关键代码、踩坑实录和提效习惯五个角度展开把我做 Agent-Reach 过程中的真实思路和教训写出来。不管你是正要给 Agent 接工具还是已经被工具调用搞得焦头烂额应该都能从中找到一些可以照搬的做法。1. Agent-Reach 的定位从“能聊”到“能办”的最后一公里先说清楚这个项目不做的事Agent-Reach 不是一个模型不是一个对话 UI也不需要你重新训练任何东西。它是一层运行时的编排层夹在大模型和真实世界之间。1.1 Agent 项目的通病能说不能做我见过太多类似的场景用户对 Agent 说“帮我看看上周三那笔 1024 号订单到哪一步了”Agent 流畅地回答“好的我来查一下”然后…… 它就开始胡编了。要么编了一个订单状态要么直接告诉你“查询失败请稍后重试”但它压根没有查过任何真实系统。还有个更典型的例子让 Agent 根据一份会议纪要生成待办事项并写入公司内部的 Excel 表格。模型在对话里把待办事项列得清清楚楚非常漂亮但到了写入这一步就卡住了——因为模型没有直接操作 Excel 的“手”。你需要的是一套机制让模型先表达“我要调写入函数参数是这几行数据”再由这套机制去真正执行把执行结果拿回来给模型做下一步判断。这个“表达意图 → 外部执行 → 回填结果 → 继续推理”的闭环就是 Agent-Reach 的核心。你可以把它理解成一个翻译加调度层大模型说人话 Agent-Reach 负责把“人话”翻译成具体工具调用再把工具的机器结果翻译回模型能理解的上下文。1.2 我定义的“触达”用户、工具、数据三条链路“Agent-Reach”里的“触达”在我这里具体指三层意思触达方向要解决的问题典型场景触达用户理解真实需求而不只是听字面意思用户说“太冷了”要理解为“查询天气并给出穿衣建议”触达工具能真正调用 API、脚本、数据库而不是嘴上说“已完成”写入 Excel、发送 HTTP 请求、执行 Shell 命令触达数据拿到实时的、准确的、可被模型消化的外部数据查订单系统状态、读数据库记录、抓取网页内容三条链路缺一不可。只触达用户不触达工具就是个聊天机器人只触达工具不触达数据模型拿不到反馈执行就是盲跑。Agent-Reach 的设计目标是把这三条链路串成一个稳定闭环。1.3 为什么说这是运行时问题而不是模型问题很多人遇到 Agent “不干活”时第一反应是换更强的模型。但我在实际测试中发现GPT、Claude 这类模型写代码的能力、理解任务的能力都足够强问题往往出在系统没有给它们“动手”的通道也没有给它们清晰、结构化的工具说明书。换句话说再聪明的实习生你只给他一部电话让他办业务他也得知道该按什么键、说什么话。你让他“随便办一下”他当然只能给你编一个结果。Agent-Reach 做的就是给这个“实习生”一套完整的办事流程、工具手册和反馈机制让它的能力可以被真正兑现。2. 触达系统的核心设计工具注册、执行器和状态管理整个 Agent-Reach 可以拆成三个核心模块工具注册表、执行器和状态管理器。三个模块合在一起才构成了 Agent 从“想”到“做”的完整通路。2.1 工具注册表让大模型“读懂”每个工具能干什么模型并不知道你的系统里有哪些函数、每个函数接收什么参数。所以第一步必须把每个工具变成一份大模型能“读懂”的说明书。我在项目里用 JSON Schema 来描述每个工具并给每个工具绑定一个真实函数。TOOL_REGISTRY: dict[str, dict] {} def tool(name: str, description: str, parameters: dict): def decorator(func): TOOL_REGISTRY[name] { name: name, description: description, parameters: parameters, func: func, } return func return decorator关键在设计这份“说明书”的措辞。工具的description不能只写“查询天气”四个字而要写清三件事这个工具在什么场景下使用。比如“当用户想了解某城市的实时天气、温度、风力或询问出行穿搭建议时使用”。参数的精确含义和取值范围。这里的描述直接影响模型能不能生成正确参数。边界与禁用情况。比如“本工具不负责查询历史天气历史天气请调用 query_historical_weather”。参数部分更要用好 JSON Schema 的字段约束能力。以城市这个参数为例{ type: object, properties: { city: { type: string, description: 要查询天气的中文城市名例如北京、上海、广州。, enum: [北京, 上海, 广州, 深圳, 杭州, 成都] } }, required: [city] }有了enum这类约束模型和校验器都能拿到同一份标准参数幻觉的容错空间就被压缩了。这份“说明书”会直接传给大模型作为工具定义同时本地执行器也会拿着它对模型返回的参数做二次校验。2.2 执行器把模型的意图变成真实的函数调用注册好了工具下一个问题是大模型怎么“调用”。现在的模型供应商基本都支持原生工具调用Function Calling / Tool Use——也就是说模型会在回复里返回一个结构化的tool_calls数组里面包含工具名和参数 JSON而不是干巴巴地输出一段“我想调用 xxx”。我的执行器负责消费这个数组逐个执行再把结果装进一个新的消息体里返回给模型。这就是 Agent 的“手”。核心调度逻辑如下import json from jsonschema import validate, ValidationError def dispatch(tool_call: dict) - dict: name tool_call[name] arguments json.loads(tool_call.get(arguments, {})) if name not in TOOL_REGISTRY: return {error: f未知工具: {name}, ok: False} tool_schema TOOL_REGISTRY[name] try: # 1. 先校验参数不符合 schema 直接拒绝 validate(instancearguments, schematool_schema[parameters]) except ValidationError as e: return {error: f参数校验失败: {e.message}, ok: False} try: # 2. 校验通过再真正执行 result tool_schema[func](**arguments) return {result: result, ok: True} except Exception as e: # 3. 异常也结构化返回方便模型理解后自行修正 return {error: f工具执行异常: {type(e).__name__}: {e}, ok: False}这里的每一步都有讲究。参数校验放在真实执行之前是为了防止模型幻觉参数直接打到真实业务系统里。比如模型调你写的“删除文件”工具传了一个用户的路径校验层就能在入参阶段拦下错误。执行异常也必须结构化返回否则模型只会看到一段堆栈天花板的文本很难判断下一步该改参数还是换工具。2.3 状态管理不能做一步忘一步Agent 和普通函数调用最大的区别在于多步任务。用户说“先查天气再针对天气写一份北京周末出行建议最后存成 Markdown 文件”这个任务需要 3 次以上的工具调用中间还隔着模型的两次推理。如果没有状态管理模型很可能查完天气就开始“写小作文”把“存成文件”这最后一步彻底忘掉。我在 Agent-Reach 里维护一个会话对象包含三块历史消息列表、当前任务清单Task Stack和可选的短期记忆摘要。class Session: def __init__(self, user_id: str): self.user_id user_id self.messages: list[dict] [] self.task_stack: list[str] [] self.summary: str def push_task(self, plan: list[str]): self.task_stack plan def complete_task(self, task: str): if task in self.task_stack: self.task_stack.remove(task)每次调用模型前我都会把未完成的任务清单注入 system 消息def build_system_prompt(session: Session) - str: prompt 你是一个任务执行助手。每次调用工具后请检查任务清单并继续推进直到全部完成。\n if session.summary: prompt f对话摘要{session.summary}\n if session.task_stack: prompt 当前待办任务\n for i, task in enumerate(session.task_stack, 1): prompt f{i}. {task}\n prompt 如果任务全部完成请明确告诉用户。\n return prompt这个设计是我在无数次“Agent 做到一半忘了目标”之后总结出来的。你不要指望模型把所有历史消息都一字不差读完但每轮都看到一遍“待办任务清单”大部分情况它就能老老实实往下执行。3. 从零复现 Agent-Reach 的关键代码与选型很多读者肯定想知道这套东西到底怎么落地我下面按选型、核心代码、真实工具接入三步走来讲。3.1 技术栈选择为什么是 Python FastAPI 结构化输出Agent-Reach 目前的技术栈非常简单Python 3.11团队熟悉AI 生态最成熟没有理由不选。FastAPI用来暴露两个 HTTP 接口——会话创建接口和消息发送接口。选它纯粹因为性能足够、类型标注舒服、文档自动生成。OpenAI SDK 兼容层现在的模型供应商大多提供 OpenAI 兼容接口接一个统一的 SDK 层可以留出切换空间。JSON Schema 校验库jsonschema给工具入参做标准化校验。选这套组合不是因为它新而是因为“稳”。Agent-Reach 的瓶颈从来不是框架性能而是模型能不能稳定生成正确工具参数。Python 生态里调试工具和日志方案都成熟排查问题省一半时间。3.2 核心代码落地注册器、调度回路与结果回填除了上面已经展示的注册器和 dispatch最关键的是主调度回路。它负责循环处理模型返回要不要调用工具如果需要就执行、回填、再交给模型直到模型给出最终文本回答或达到最大步数。import json MAX_STEPS 8 def run_agent(user_request: str, session: Session): session.messages.append({role: user, content: user_request}) for step in range(MAX_STEPS): messages [{role: system, content: build_system_prompt(session)}] session.messages resp llm.chat.completions.create( modelMODEL_NAME, messagesmessages, tools[t[schema] for t in TOOL_REGISTRY.values()], tool_choiceauto, ) choice resp.choices[0] session.messages.append(choice.message) if not choice.message.tool_calls: # 没有工具调用说明 Agent 认为任务完成了 return choice.message.content for tool_call in choice.message.tool_calls: result dispatch(tool_call) session.messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) return 执行步数超限已停止。这里有两个容易忽略的细节。第一个每次都要重新把system消息拼在对话最前面因为里面带着最新的任务清单和摘要。第二个tools参数每次都会扫描一次注册表所以后加的tool装饰器方法不需要重启服务也能生效前提是 Python 模块已加载。3.3 接入两个真实工具看完整链路为了验证这套架构我接了两个毫无浪漫感但非常实用的工具查天气和写文件。天气工具直接调一个免费天气 API但是加了enum约束城市名文件工具接受filename和content两个参数负责把内容写入本地目录。tool( namewrite_markdown_file, description将内容保存到本地 Markdown 文件。当用户要求保存、导出或落盘一份文本时使用输出成功后返回文件路径。, parameters{ type: object, properties: { filename: { type: string, description: 文件名必须以 .md 结尾例如 travel_plan.md }, content: { type: string, description: 要写入文件的完整 Markdown 内容 } }, required: [filename, content] } ) def write_markdown_file(filename: str, content: str) - str: if not filename.endswith(.md): filename .md output_path Path(outputs) / filename output_path.parent.mkdir(parentsTrue, exist_okTrue) output_path.write_text(content, encodingutf-8) return f文件已保存到 {output_path}用户发一句“帮我查下上海天气然后写份周末两日游的建议存成 md 文件”理想链路是这样的模型解析意图识别出需要先调用query_weather(city上海)。dispatch 执行天气查询把返回的文本塞回模型。模型读到天气结果生成出行建议接着调用write_markdown_file(filenameshanghai_weekend.md, content...)。文件写入成功模型向用户输出“已保存到 outputs/shanghai_weekend.md”。这一条链路跑通Agent-Reach 的骨架就算立住了。剩下的功夫全在调“边界”——而边界问题恰恰是实操里最折磨人的部分。4. 触达失败实测三个典型事故的完整排查过程这部分是我认为全文最有价值的地方。我在开发 Agent-Reach 的过程中遇到了一箩筐模型“够不着”的坑。下面挑三个典型场景把我当时的排查链路完整写出来而不是只给结论。4.1 参数幻觉模型编造了一个不存在的城市现象用户问“广州天气怎么样”Agent 返回“未找到广州天气”。但参数校验明明通过了日志里显示 city 参数是“广州省”。排查链路第一步查看 dispatch 日志发现入参是“广州省”。这不是程序 bug是模型自己“脑补”了参数。第二步查看工具 schema发现enum里只写了“广州”而用户输入“广州市”或“广州省”时模型并没有百分之百按枚举值映射它会把输入原样带进参数。第三步我做了一组对照测试把description改成“如果用户输入‘广州市’或‘广州省’请统一转换为‘广州’”并用一行enum再加一个examples字段。重新跑 30 个同类型请求错误率从 35% 降到 6%。修复经验不要在工具描述里假设模型“会理解常识”。你在 schema 里每多写一个同义表述、每个示例值都是在给模型铺路。参数归一化这种脏活自己干别交给模型自觉。4.2 上下文遗忘Agent 做到一半忘了原始目标现象用户给了个五步任务Agent 完成前两步后开始长篇大论介绍相关背景知识既不调用后续工具也没有给用户一个结束语。排查链路第一步打印出当前 messages 的 token 数量发现历史已经膨胀到上万 token模型注意力被稀释。第二步观察这个模型在最后几轮回复中引用系统提示里的任务清单的次数——几乎没有。第三步检查会话对象发现任务清单是在第一轮由模型规划的但后来没有任何机制提醒它任务还没做完。修复经验我引入了system_prompt每轮刷新 Task Stack 强制注入的方案。效果很直观类似长任务的完成率从 40% 提到了 85%。但因为历史消息仍然会继续膨胀我又加了一层摘要逻辑每轮对话结束后把早期对话压缩成一句话摘要。这里的关键是“任务清单”永远放在摘要前面不让它被淹没。4.3 原始返回轰炸API 结果把模型“带跑偏”现象我接了一个内部订单查询 API返回的 JSON 非常大包含二十多个嵌套字段。Agent 调用这个工具后开始引用一个不存在的字段“order.status_detail”然后一本正经地告诉用户订单异常。事实上该字段是模型自己编的。排查链路第一步打开返回给模型的 tool message发现 2000 多字、层层嵌套的 JSON 直接塞进了上下文。第二步模型确实“读”了但读哪个字段、怎么解读完全失控。它自己脑补字段语义还脑补了结论。第三步我把工具改成了“字段裁剪 摘要优先”策略执行器内部拿到完整 JSON 后只把关键字段订单号、状态、金额、时间拼成简短文本返回完整数据存到临时空间附带一个引用 ID。需要细看时再让模型调用另一个get_order_detail_by_ref工具。修复经验工具返回不是越全越好而是越“适合模型消费”越好。模型不是数据库客户端它需要的是浓缩后的信息。这个原则适用于所有工具查数据库时 SELECT 只取需要的列查 API 时只把业务关键字段拼好。故障类型根因排查突破口修复方案参数幻觉schema 约束不足、描述缺乏别名提示dispatch 日志里的入参记录补全 enum、同义描述、参数示例上下文遗忘历史过长、任务目标没有显式注入打印 messages 的 token 量与任务清单出现次数引入任务栈 摘要裁剪结果带偏工具返回原始 JSON 过大、字段混乱查看 tool message 内容体量工具端字段裁剪、摘要优先5. 把触达成功率从六成拉到九成的五个习惯架构代码都到位之后剩下的全是细节。这五个习惯是我一路踩坑踩出来的直接照抄能省很多时间。5.1 先规划再动手强制 Agent 输出步骤我现在的 system prompt 里有一条硬性规定对于需要两步以上工具调用的任务模型必须先输出一个plan块列出具体步骤再开始调用工具。这一步看起来像“仪式感”实际上效果非常好。规划动作迫使模型把隐性推理显性化。原来它经常“边做边想”做着做着方向就偏了现在先想清楚“查天气→生成建议→写文件”后面每一步调用都跟计划对齐。而且计划里可以明确标注工具名和顺序相当于给 Agent 自己画了张地图。5.2 用“语义化”写工具描述而不是堆参数很多团队写工具描述时特别偷懒就写“查询订单”。我见过一次惨痛教训工具名query_order被模型反复调用但参数字段user_id它死活传不对。后来我把描述改成了完整场景句“当用户询问某个订单的物流进度、状态或金额时调用本工具。入参是用户登录系统的唯一标识通常可以在当前会话中获取。”改完之后同场景准确率直线上升。记住工具描述本质上是“提示工程的核心部分”它直接决定模型怎么理解工具适用条件。写作要像给人类同事写交接文档一样包含触发条件、输入来源、输出定义。5.3 失败返回也是一等公民我见过太多人只设计“成功路径”工具失败时随手return None。结果模型拿到 None 后开始瞎猜把失败变成幻觉的高发区。正确做法所有工具失败的返回必须是结构化、可诊断的。回到前面的dispatch设计失败时一定包含ok: False、error和错误类型。模型拿到这种消息后能正确判断是参数错误需要修正调用还是环境错误需要告知用户。我在几个工具上都验证过失败信息越清晰模型“自愈重试”的成功率越高。5.4 完整记录调用日志排查不靠猜Agent 系统的排查难度远高于普通接口因为“错误”往往不是抛异常而是“结果不对”。没有日志你根本没法判断是模型理解错了、参数传错了、工具执行错了还是用户描述有歧义。我在 Agent-Reach 里强制要求每一条工具调用都落库请求的唯一 ID串联起一轮对话中的所有调用。模型返回的原始 tool_call 参数不经过任何转换直接存。dispatch 校验结果和执行结果。每轮 messages 的 token 数量。有了这些数据排查 4.2 节那种“上下文遗忘”就不难翻一翻日志就能定位到哪一步开始模型不再提任务清单。5.5 保留人工兜底关键动作必须确认最后一条关乎安全感和稳定性。不是所有工具调用都应该自动化。比如发送邮件、删除文件、提交订单这类动作我建议在 dispatch 前插入一个requires_confirmation标记。当模型调用这类工具时系统不直接执行而是先返回给用户一个确认卡片“Agent 准备发送一封邮件给 xx内容为……点击确认后执行。”这在早期调试阶段尤其重要。因为 Agent 的不可控性本来就高你无法预判它哪一步会出奇奇怪怪的举动。有一层人肉阀门在关键链路上整个系统才敢从 demo 走向真实业务。做 Agent-Reach 做到现在我最大的体会是AI 应用的核心竞争力往往不在模型选得多强而在于你怎么把模型和基础设施之间的“最后一公里”修得够扎实。再聪明的 Agent也得有手有脚、有地图、有反馈回路才能真帮你办成事。如果你想自己搭一套类似的系统我建议第一版别贪多先接三个工具跑通这条链路再慢慢把工具描述、失败处理和状态管理打磨到位。这套思路本身比任何单一框架都值钱。
