1. 项目缘起为什么要做 Agent-Reach 这个代理触达框架做 AI Agent 开发的人可能都有一个共同的感受单个大模型能力再强落不到实际业务场景里面都是白搭。真正让 Agent 变得有用的是它能够触达外部的系统、工具和数据源完成一次真实的业务操作。我这里说的触达可不是简单调一个 API 就算完事而是需要经过任务拆解、参数校验、工具选择、结果回传、失败重试这一整套流程。Agent-Reach 这个名字核心就是让 Agent 够得着它该够得着的东西。整个项目解决的问题非常具体我在做企业内部的知识库问答机器人和多步骤数据分析助手时发现不管用 ReAct 模式还是 Plan-and-Execute 模式Agent 在调用外部工具比如搜索 Elasticsearch、查 MySQL、调内部审批接口的时候总会出现参数传错、工具选错、中途崩了不知道怎么办这些毛病。市面上的 LangChain 确实强大但对中小团队来说太重了依赖一堆、抽象绕来绕去出了问题排查成本太高。于是我用一个周末搞了个轻量级的代理触达框架后来逐步完善成 Agent-Reach 这个项目。这个框架适合谁我觉得三类人可以从中找到共鸣一是正在裸调大模型 API、发现 Token 消耗高得离谱的开发者Agent-Reach 的重试和校验机制能省不少无效 Token二是接了 LangChain 但被抽象层折腾得头大的团队这套框架的思路更透明代码量小能快速改出自己想要的行为三是想自己动手撸一个 Agent 骨架、学习 Agent 内部机制的人整个项目结构非常集中看完基本就能理解 Agent 干活的全流程。我不会说它是万能的毕竟每个团队的业务场景不一样但如果你想解决的是如何让 Agent 稳定且可控地调用我们自己的工具这篇文章里的设计思路和踩坑记录应该能给你不少参考。2. 核心设计思路Agent 触达能力的三个圈层2.1 统一工具协议层先把手长规范了开发 Agent 最常犯的错是让模型直接去猜函数的参数。一开始我也这么干给模型塞了一大段自然语言描述说这个函数接收 start_time 和 end_time格式是 ISO 8601结果模型经常传成时间戳或者把时间范围为写成单个时间点。与其让模型靠理解去拼参数不如把每个工具的定义做成严格的结构化 Schema让模型在几个选项里选参数而不是凭空生成。Agent-Reach 里我把每个外部能力都封装成一个统一协议的工具描述底层依赖 JSON Schema。举个例子一个查订单数据服务的工具它对外暴露的 Schema 长这样{ name: query_order, description: 根据日期范围和订单状态查询订单数据, parameters: { type: object, properties: { start_date: {type: string, format: date, description: 起始日期格式 YYYY-MM-DD}, end_date: {type: string, format: date, description: 结束日期格式 YYYY-MM-DD}, status: {type: string, enum: [pending, paid, shipped, cancelled], description: 订单状态} }, required: [start_date, end_date] } }之前我觉得写这种描述是浪费时间后来发现这恰恰是 Agent 能稳定工作的基石。模型虽然笨但只要你给它的选择足够明确——枚举值、格式、必填项都写清楚它的正确率能提升到 95% 左右。为什么因为这让模型的任务从回忆并生成正确的参数变成了从给定约束中选择符合条件的值后者的难度低得多。这一层还顺手解决了另外一个问题不同的工具可能有不同风格的参数定义统一协议之外外部系统的适配器可以各写各的互不干扰。现在这个项目里已经适配了 PostgreSQL、Elasticsearch、HTTP 接口、本地文件系统四类数据源每类就是一个独立目录新增一个数据源只需要实现一个invoke()方法加一个 Schema十几分钟能搞定一个新的能力入口。2.2 规划执行分离层把做什么和怎么做分开管最早的 Agent-Reach 只有一个循环模型收到任务直接尝试调用工具。后来发现一个复杂任务比如把上个月的订单汇总按渠道分析并生成图表让模型自己一口气干完大概率干到一半就上下文混乱了要不就是中间少算了一个渠道。于是我参考了 Plan-and-Execute 的思想但做了一个更务实的调整规划器和执行器用同一个模型但分成两个独立的阶段。模型先看到任务是分析订单并生成图表时它的第一轮输出不是直接调工具而是一个包含步骤的 Plan。这个 Plan 会被我压缩成一串精简摘要留在上下文里真正的执行过程则是逐工具调用的。阶段隔离的好处是上下文干净了。我实测了一个项目一个需要连续查询四次数据库、第三次查询依赖前两次结果的复杂任务在传统 ReAct 模式下每轮都要重新读入全部历史Token 消耗至少 6000 多而在规划执行分离的模式下中间摘要只占了不足 1500 Token最终结果还更稳定。Token 费用的节省是次要的关键是有时候模型在超长上下文里会忘掉自己最初的目标做成一半就把任务改了规划器把这个风险也一并规避了。class SimplePlanner: 一个实用主义的规划器拆步骤不写花哨的 Prompt def build_plan(self, task: str, tool_schemas: list) - list[str]: plan_prompt f请把下面的任务拆成不超过5个步骤每步只做一件事最后一步必须是一个明确的输出动作。\n任务{task}\n可用工具{tool_schemas} ...拆步骤的时候有个小门道不是每个任务都值得拆。单步任务比如查一下订单数为 100 的客户有哪些要是拆成三步反而增加延迟。实际实现里我加了一个判断如果工具只有一到两个且任务描述里没有嵌套关系直接跳过规划阶段进入执行阶段。这个优化能让简单场景的响应速度提升 40%。2.3 触达结果回传层最终产出要回到业务手上框架跑完一个 Agent 任务之后原始的返回值往往没法直接用可能是 Elasticsearch 的 JSON 聚合结果可能是 SQL 查询后的表格数据。Agent-Reach 做了一个统一的结果标准化把不同来源的数据最终都转成两类格式结构化表格数据用于统计分析、图表展示或自然语言摘要用于汇报、通知。这块是我个人很骄傲的设计因为它把Agent 干完活和业务方拿到结果之间无缝对接了。你一分钟后可以调用AgentReachResult拿到一个 DataFrame也可以直接调用.summary()得到一段类似人话的结论汇报。实际上多数企业里Agent 干活的终点不是输出一句我完成了而是要接上下游系统比如发送企业微信通知、填入 BI 报表系统。结果标准化这一步等于给下游少造了很多适配轮子。3. 从零搭建一个 Agent-Reach 实例关键环节拆解3.1 环境准备和项目结构我用三个月时间把 Agent-Reach 打磨成一个可运行的小型框架。建议你用 Python 3.11因为新版里tomllib直接可用配置文件解析方便不少。依赖方面我只用了三个必须的包openai或者你对接任何 OpenAI 兼容接口的 SDK、pydantic用来做工具参数校验、pandas用来处理结果表格。相比动不动就拖几十个传递依赖的框架这个干净程度算很理想了。项目目录被我压到这个程度方便维护agent_reach/ ├── core/ # 核心循环规划、执行、校验、重试 ├── tools/ # 各类工具适配器 │ ├── postgres_tool.py │ ├── es_tool.py │ └── http_tool.py ├── memory/ # 轻量级会话记忆 ├── schemas/ # JSON Schema 定义 └── server.py # 提供阻塞式 API 调用入口我特意没引入异步框架和消息队列因为多数 Agent 任务是同步的引入异步只会增加心智负担。等你跑通了核心逻辑再考虑并发调度也不迟。环境里需要配置好模型 API 的密钥我一般用一个.env文件加载MODEL_API_KEYsk-xxxx MODEL_BASE_URLhttps://your-api-endpoint MODEL_NAMEgpt-4o-mini3.2 定义第一个触达工具连接本地文件我们先用最简单的文件读取来走通整个流程。我需要一个工具它能读取一个 CSV 文件并返回其内容摘要。定义 Schema 时我故意把path描述得特别明确这样模型不会传错路径register_tool class CsvReaderTool: schema { name: read_csv, description: 读取本地 CSV 文件返回文件名、行列数和前5行数据摘要, parameters: { type: object, properties: { path: {type: string, description: CSV 文件的完整本地路径例如 /data/sales.csv} }, required: [path] } } def invoke(self, path: str) - dict: import pandas as pd df pd.read_csv(path) return { filename: path, shape: list(df.shape), head: df.head(5).to_dict(orientrecords) }这里的关键是register_tool装饰器它会在程序启动时自动扫描所有工具收集其 Schema 存入一个全局注册表中。执行时模型能看到的工具列表就是从这个注册表生成的不会多也不会漏。你可能会说read_csv 这么简单的工具模型自己可能就会写代码模拟为什么要注册成工具此言差矣注册成工具后模型不用去猜 CSV 里有几列、列名是什么直接通过工具调用拿回精确结果效率和准确率都高很多。这也体现了 Agent 工具设计的基本原则把不确定的操作交给真实执行系统模型只做决策不做猜测。3.3 核心循环规划-执行-校验-重试Agent 的主循环我保持在五十行以内因为逻辑越简单越不容易出问题。核心流程是收到用户任务后用规划器生成执行步骤如果需要规划每步执行时把步骤描述、可用工具 Schema 和上一轮的执行结果一并交给模型让模型返回一个工具调用请求用 pydantic 按 Schema 严格校验模型输出的参数类型不对就重新要求模型生成绝不宽容调用真实工具拿到原始结果把结果转成结构化的AgentResult并填写回上下文用于下一轮决策如果整个计划步骤完成了最终调一次模型生成自然语言总结。def run(task: str, max_steps: int 8) - AgentResult: context [{role: user, content: task}] steps planner.build_plan(task, registry.schemas()) for step in steps: response llm_call(context, step, registry.schemas()) action parse_action(response) validated validate_params(action.arguments, registry.schema_of(action.name)) if validated.error: context.append({role: assistant, content: f参数错误{validated.error_msg}请重新提供参数}) continue raw_result registry.invoke(action.name, validated.data) context.append({role: tool, tool_name: action.name, content: format_raw(raw_result)}) final llm_call(context, 请基于以上所有工具的返回结果给出最终回答。) return AgentResult(conclusionfinal, raw_stepscontext)max_steps这个参数特别要关注。如果模型陷在调用工具-发现错误-重新调用的循环里没有上限会烧掉大量 Token。我设了 8 步的上限实测对大多数多步骤任务足够了。超过上限后的兜底动作也很直白停止执行返回任务超过最大步骤数请缩小问题范围。校验这步我吃过亏。一开始我不校验模型的输出直接拿它给的参数去调数据库结果有一次模型把end_date传成了中文日期格式数据库直接报错。后来加上了基于pydantic的严格校验格式不对当场打回重试。这里要注意一个细节打回重试时要把错误原因写得很明确比如参数 start_date 格式错误应为 YYYY-MM-DD你提供的是 4月1日模型一般下一次就能修正。3.4 上下文记忆管理别让 Agent失忆多步骤任务里工具调用结果会不断填充上下文。如果不加控制上下文会膨胀。我在 memory 模块里用了最简单的策略只保留最近三轮工具结果更早的历史结果会被压缩成一句摘要比如已完成查询了4月订单总数返回12345条。def compress_old_steps(context: list, keep_latest: int 3) - list: tool_calls [msg for msg in context if msg[role] tool] if len(tool_calls) keep_latest: dropped tool_calls[:-keep_latest] summary summarize_calls(dropped) context [{role: system, content: f旧的执行记录已经压缩摘要{summary}}] tool_calls[-keep_latest:] [msg for msg in context if msg[role] not in (tool, system)] return context这个方法说实话挺粗暴但胜在便宜有效。压缩摘要的生成成本远低于保留完整工具返回值的成本。在很多问答场景里模型只需要知道前面查过什么结论是什么不需要每一条原始数据都在脑子里轮播一遍。如果你要处理的场景是记忆高度敏感的比如多轮对话里用户改口了需求那我觉得可以顺序记录用户的最近五条消息然后单独走一次摘要生成。我还没做这种复杂记忆但 Agent-Reach 预留了memory插槽你可以替换成任意向量库看你的需求。4. 实战记录用 Agent-Reach 做一个销售数据汇总智能体4.1 场景设定与工具准备光讲框架太抽象我拿一套实际场景来演示。假设公司内部要求销售运营每天上午要给负责人发一条销售汇总内容包括昨日订单量、销售额、各渠道占比以及异常波动的提醒。用 Agent-Reach 实现这个场景我需要准备好两个工具PostgreSQL 查询工具执行 SQL 并返回结果企业微信机器人发送工具给指定群发文本消息。PostgreSQL 工具的 Schema 比 read_csv 复杂一丢丢关键在于query参数的编写约束。我不会让模型自由写复杂 SQL而是让它在预置的若干合法查询模板里选择并填入参数。这能避免模型捣鼓出笛卡尔积之类的大坑register_tool class PostgresQueryTool: schema { name: query_sales, description: 执行一个预置的销售统计SQL查询, parameters: { type: object, properties: { query_id: {type: string, enum: [daily_summary, channel_breakdown, trend_anomaly], description: 预置查询的标识符}, date: {type: string, format: date, description: 统计日期 YYYY-MM-DD} }, required: [query_id, date] } } ...为什么不用自然语言 SQL因为我踩过模型生成 SQL 带语法错误的坑。预置模板的方式虽然限制了模型灵活性但换来的是正确率接近 99%。在内部工具里稳定压倒一切。你如果非要让模型自由写 SQL请务必在你自己的 SQL 解析层做白名单限制。发消息工具几乎不需要参数灵活性只需要message和group_id两个字段。真正的消息内容我建议让 Agent 自己组织语言因为模型生成自然语言的功底比模板拼接强太多了。4.2 完整任务执行链路与 Token 消耗请求是一次模拟请生成昨天2024-06-19的销售日报并发送到销售管理群。Agent-Reach 的处理链路是这样的第一步规划器根据任务和可用工具生成四步计划查日汇总 - 查渠道占比 - 检查是否有异常 - 发送日报到群第二步模型调用query_sales(query_iddaily_summary, date2024-06-19)返回订单总数、总销售额等字段第三步模型看到日汇总后再调用query_sales(query_idchannel_breakdown, date2024-06-19)这一步是嵌套依赖的只有先知道昨天的销售规模模型才知道需不需要深挖渠道维度第四步调用query_sales(query_idtrend_anomaly, date2024-06-19)结果发现销售额比前一日下降 12%第五步模型综合三步结果生成一段人类可读的日报文本第六步调用send_wecom_message把日报发送到指定群。我记录了一次完整的实际运行日志Token 消耗明细大概是规划阶段 800前面三步决策消耗 2600最终总结生成 1500加上压缩后的历史摘要大约 2000 多总共不到 7000 Token。相比让模型一次性大乱炖地进行自由 ReAct 循环这个方案的 Token 命中效率高了不少而且每一轮调用的目的都高度可控。有个细节值得记录上下文压缩发生在第三步和第四步之间。因为第一步查出来的原始日汇总数据占了不少 Token等到要生成渠道占比的时候旧数据只保留一个摘要已获取 6 月 19 日订单量 4216 单总销售额 83.2 万元就足够了。这样后面模型在写日报的时候不用担心上下文里原始数据太多导致注意力分散。4.3 执行中途模型飘了怎么办纠偏与兜底实测中最大的一次意外是模型在执行完第三步后自己脑补了一个趋势对比目标想要再查一次上周同期的数据但工具列表里根本没有这个查询模板。正常情况下模型应该老老实实继续后续步骤但它偏不。Agent-Reach 的应对很简单——不允许调用不在注册列表里的工具。模型即使输出一个陌生的函数名解析器也会直接拒绝并提示它只能在注册表中选择。加上步骤上限的兜底这次飘了的模型在被拒绝一次后很快回到了正轨。另一个兜底动作是步骤完成度检查。模型完成所有计划步骤后如果某个步骤没说成功我不让它进最终总结阶段。比如发送企业微信消息失败或者超时链路会重试一次第二次还失败就直接终止并把错误原样抛出不生成误导性的任务已完成。这个设计是吸取了真实事故的教训。有一次调用一个内部 HTTP 工具超时了但 Agent 居然自己脑补说消息已发送成功请查收。排查了半天才发现是模型在结果不可用的时候编了一个成功结果。现在我在结果回传层里强制要求工具的真实返回状态必须是成功Agent 才能基于它做总结如果工具层出错Agent 只有两个选择重试或者上报失败。5. 工具选型与调优细节Agent 能否真正落地的关键5.1 模型选择对触达成功率的影响Agent-Reach 目前我主要测试了两类模型通用旗舰模型和轻量模型。结论很有意思触达成功率这个指标上轻量模型和旗舰模型的差距没有想象中那么大——前提是你把工具 Schema 写得足够细致。我用一个包含 12 个工具、总参数字段 38 个的系统做了对照轻量模型参数错误率大约 6%旗舰模型大约 2%。在加了 pydantic 强校验和错误打回之后两者的最终执行成功率都提升到了 97% 以上。区别体现在另一个维度复杂任务的理解能力。当任务的步骤数超过 5 个时轻量模型偶尔会在中途丢掉某个步骤而旗舰模型基本能跟完。所以我的建议是步骤不超过 3 的简单任务用轻量模型响应快成本低多步骤长链路任务用旗舰模型兜底。你可能会纠结模型 API 的稳定性。我在 server 层做了最简单的重试策略网络抖动导致的请求失败指数退避重试三次间隔分别为 1 秒、2 秒、4 秒。这个后端的策略在实际运行中帮了大忙毕竟工具触达链路里模型 API 的网络波动是最大变量之一。5.2 参数校验宁可慢一点不可错一次校验层是我反复打磨过的地方。除了格式校验我还加了一层业务语义校验。比如日期参数不能只是合法的 YYYY-MM-DD 格式还不能晚于今天的日期。这个语义校验写在各个工具适配器内部不由核心层统一处理。理由很简单不同工具的业务约束千差万别核心层不应该变成一个大杂烩。语义校验与格式校验分开还有个好处错误提示能更精准。格式错误统一返回给模型让它重试语义错误则直接拦截因为这种错误模型一般自己也能修正但如果次数太多我会在上下文里附上一句你多次传了无效参数请仔细阅读工具 Schema 中的描述给模型一个强提示。现在这个校验模块的测试用例我已经攒了 80 多个覆盖了各种刁钻的传参方式传入对象当字符串、少传必填项、枚举值大小写错、日期格式混用。每次改代码我都会把测试用例重跑一遍这个习惯省了无数救火时间。5.3 结构化输出与可观测性别让 Agent 变成黑盒Agent 系统最忌讳的就是黑盒你问它刚才为什么调用了这个工具它答不上来。Agent-Reach 在每次工具调用前后都会打日志内容包括模型决策的原生输出、工具名称、参数、结果状态、耗时。日志我统一转成 JSON 格式方便后续导入 ClickHouse 或 ELK 做分析。{ ts: 2024-06-19T11:23:45, step: 2, tool: query_sales, params: {query_id: channel_breakdown, date: 2024-06-19}, status: success, latency_ms: 340, token_usage: 420 }这些日志不仅是排查问题依据也是我做成本分析的数据源。通过一段时间的日志聚合我能统计出每个 Agent 任务的均摊 Token 成本、每类工具被调用的频率、哪些工具的失败率最高。这是持续调优的基础没有日志优化就是空谈。我还做了一个轻量可视化面板但只是用streamlit快速搭的主要展示近 24 小时的触达成功率、工具调用分布、平均耗时三个指标。对内部使用足够不追求花哨。6. 实操中最常见的五个坑与对应的排查方法6.1 模型不按 Schema 输出该不该生气经常遇到模型明明看到了 Schema 和工具描述却仍然返回一个不存在的参数名。早期我以为是模型理解能力问题后来发现多数原因是 Prompt 里工具描述和系统指令的描述顺序不对或者工具数量超过十个后模型开始混淆。解决办法是每次只给模型暴露与当前步骤最可能相关的 3-5 个工具的 Schema而不是一次性把所有 12 个工具全部塞进去。这个工具按需暴露的策略直接把参数错误率降了一半以上。6.2 工具返回了超长结果上下文爆了查询数据库返回一千行结果模型拿到这些原始数据既不能全记住也没必要全读。我在每个工具适配器里都内置了一个summarize_before_return开关默认打开。当返回结果超过大约 1500 字符时会自动用摘要模型先生成一段精简结论再把这段结论填入上下文原始长数据可以落盘存档。这保证了多步骤任务中每步的信息增量不至于撑爆上下文窗口。6.3 重试循环太频繁把 Agent 逼疯我发现重试逻辑写不好Agent 会像一个偏执狂一样反复用同一组错误参数调用工具。后来我在核心循环里加了一个连续错误次数计数器同一工具连续失败三次就不再允许该工具进入本轮后续的决策转而要求 Agent 换一个思路或者直接向用户请求澄清。这个机制显著提升了跑路率——这里说的跑路是指 Agent 被迫诚实承认我搞不定而不是硬编一个结果。6.4 结果格式化不一致下游解析困难Elasticsearch 的聚合结果和 SQL 查询结果格式差异巨大下游如果做统一分析会头疼。Agent-Reach 在结果回传层做了标准化统一转成columns rows的表格结构。如果你拿到的工具结果是嵌套 JSON我也会在适配器里先摊平成表格。这个标准化处理的价值等你要把 Agent 的结果接入 BI 工具或自动化报表时候才会真正感受到。6.5 任务步骤顺序被模型打乱规划器被无视有时候规划器明明给出了顺序但执行器模型会自作主张调整步骤顺序比如先发消息再查数据。我的处理是在每轮模型调用前把当前要执行的步骤单独放在一条 system 级别的 prompt 里并明确写着请只执行这一步骤不需要提前执行将来的步骤。这样约束下来模型就不会越权乱序了。同时也保留一个例外机制如果模型能明确解释调整步骤顺序的原因比如先获取全部数据再统一分析更合理并且不超过步骤上限执行器允许微调。这个灵活性一开始没有是后面加的因为有些任务的步骤之间确实没有强依赖关系太死板反而影响效率。7. 当前局限与后续演进方向Agent-Reach 目前在单机同步场景下跑得很稳但它肯定称不上一个生产级的高并发 Agent 平台。在持续压测中我发现如果一个进程同时接到几十个任务排队就意味着响应时间直线上升。后续如果要扩展成服务化需要引入两样东西一个是任务队列把 Agent 任务拆成可异步执行的单元一个是分布式会话存储替换掉现有的内存级记忆管理。另外现在的规划器还是比较朴素的 Prompt 式拆分。我在考虑要不要引入一个专门的小模型做最终校验针对复杂任务的规划结果进行步骤依赖检查。这个想法目前还是实验性的因为训练数据和评估指标都还不成熟贸然上可能适得其反。从使用角度看Agent-Reach 的定位是启发式参考实现——它不是给你一个开箱即用、包治百病的框架而是给你一套触达工具调用链路上可以复用的完整思路。你可以把它当骨架根据自己业务场景填充血肉这在 AI Agent 技术仍然快速演进的当下可能是更务实的选择。最后分享一个我个人的体会在做 Agent 项目的时候别一开始就想着把所有模型能力都用上、把框架做得大而全最优先的目标是让链条跑通——尤其是让 Agent 能稳定地触达一个外部工具并把结果带回。当这个最小闭环成立后后续的每一层优化记忆、规划、并发才有意义。这套 Agent-Reach 实际上就是沿着这个思路从一个工具调用示例长成了一个轻量触达框架项目再往后怎么走我目前的想法是继续保持轻盈和透明有余力的话再打磨一下规划器的自适应能力让框架在复杂任务上的表现更进一步。