做 AI Agent 的人大概都经历过同一个尴尬时刻演示的时候模型在屏幕上噼里啪啦调用工具、查数据、发通知台下掌声一片真到了生产环境跑了三天日志里全是超时、参数错位、重复下单、接口被限流运维半夜给你打电话问这个自动改配置的东西是谁开的。我去年下半年接手的就是这么一个烂摊子后来花了一个多月时间重构成了一套内部框架我们内部管它叫 Agent-Reach——Reach 是触达的意思专门负责让智能体把手伸出沙箱、稳稳地够到外部的系统、接口和通道。Agent-Reach 本质上是一层介于大模型和真实世界之间的触达层。它做的事情不玄乎把外部能力统一注册成可被模型理解的工具描述、在模型动手前把参数校验干净、给每一次调用打上权限闸门和幂等键、失败的时候按策略重试而不是瞎撞、把每一次伸手的完整链路记下来以便复盘。它能解决的核心问题只有一个让 Agent 从能聊变成能干活而且是可预测、可追溯、可回滚地干活。这篇文章适合两类人看一类是已经把 LLM 应用跑起来、正准备往自动化执行方向走的中级开发者一类是正在被Agent 效果不稳定折磨、想搞清楚到底是模型问题还是工程问题的技术负责人。不管你是刚摸到工具调用的小白还是已经写过几套编排逻辑的老手接下来的内容都能直接抄走用。1. 为什么能聊和能干活之间隔着一整套工程1.1 一个把我逼到重写的真实场景先说清楚痛点在哪儿。我们最早的那个版本非常朴素用户提一个需求模型输出一段 JSON写个 if-else 解析出来就去调对应的函数。跑通第一个场景只用了半天但接下来两个月这套东西几乎把我耗干了。第一个问题是参数漂移。模型今天返回{order_id: 12345}明天返回{orderId: 12345}后天可能给你套一层{arguments: {...}}。类型也飘有时候是字符串有时候是整数。你永远猜不到它下一次会怎么组织语言。第二个问题是副作用失控。有个清理过期资源的工具模型在一次对话里连续调了四次因为它觉得第一次调用没有返回它期待的结果于是再试一次。四次调用叠加上并发直接把一个资源池清空了。第三个问题是排查黑洞。出问题的时候你手上只有一条最终的错误日志中间模型看了什么、决定调什么、传了什么参数、外部接口回了什么全都不知道。你只能靠猜。提示如果你的 Agent 现在还是模型出 JSON 代码解析的裸奔结构只要它开始产生任何写操作你就已经踩在雷上了越早抽象越省钱。这三个问题的共同根源在于我们把决策和执行混在一起了。模型的输出是不可靠的自然语言而外部系统的调用需要的是确定性的、类型安全的、带约束的契约。中间缺的就是一层翻译和保护层。Agent-Reach 要填的就是这个位置。1.2 Agent-Reach 在整条链路里的定位我习惯用身体来打比方。大模型是大脑负责理解意图、拆解任务、决定下一步做什么工具本身是各种外部器官——手能开门、脚能走路、嘴能说话而 Agent-Reach 是神经和肌腱。神经负责把大脑的模糊指令翻译成精确的肌肉信号肌腱负责限制力度、控制节奏、在拉伤之前收回来。具体来说它承担四件事。第一是契约化把每一个外部能力定义成带类型、带描述、带示例的结构化工具让模型有明确的说明书可看。第二是防护在真正发请求之前完成参数校验、权限判定、频率控制、幂等去重。第三是编排处理多步任务之间的依赖、并行、中断、恢复以及跨工具的上下文传递。第四是观测把整条链路留痕支持事后回放和成本核算。这里有个很关键的设计判断Agent-Reach 不做决策。它绝不判断这个任务该不该做那是模型或者更上层的策略引擎的活。它只保证一旦决定要做就一定按规矩做。这个边界划清楚之后整个系统会变得非常好维护——因为执行层的逻辑是确定的可以写单元测试而决策层的效果波动可以单独用评测集去调。1.3 方案选型为什么没直接裸用现成框架很多人第一反应是直接用现成的编排框架不就行了。我不反对用但我们内部评估之后还是选择自己在触达层做一层封装原因有三个。第一现成框架的能力边界通常覆盖到工具调用循环就停了而真正上生产需要的权限模型、审批流、幂等、审计、密钥托管它们大多只给了扩展点没给实现。你的业务越靠近核心系统这些没给的部分就越占工作量的大头。第二绑定风险。工具描述、会话状态、回溯格式一旦跟某个框架深度耦合半年后想换一套编排思路迁移成本高得吓人。我们把 Agent-Reach 的工具描述定义成纯数据结构跟任何框架无关上层换谁都能接。实测下来后来我们换过一次编排引擎触达层一行没改。第三可控性。外部调用的超时、重试、熔断参数必须是可调、可观测、可按工具粒度覆盖的。框架给的默认值往往不适合你的业务——比如一个查库存的接口和一个下单接口合理的重试策略完全不同前者可以乐观重试后者一次都不能瞎重试。注意自己写触达层不代表什么都自己造。参数校验、HTTP 客户端、指标上报这些轮子用成熟库就行我们真正花时间自研的只有工具描述契约、权限判定和幂等去重这三块因为它们跟业务强相关没有通用解。2. Agent-Reach 的整体架构与核心概念拆解2.1 四层结构意图、编排、触达、观测搭起来之后回头看结构其实很清晰就四层每层职责单一。意图层负责把用户的话变成结构化任务。这一层最容易犯的错是过早优化——我见过有人一上来就搞多智能体协作、搞反思循环结果连最基础的意图识别都没做稳。我的建议是这一层保持极简一个系统提示词加一两个示例能把意图分类清楚、把关键实体抽出来就够了。编排层是 Agent 的主循环把可用工具列表喂给模型接收模型的工具调用请求交给触达层执行把结果回灌给模型如此往复直到模型给出最终答复。这一层的难点在于循环终止条件和中途打断的处理——你必须设一个硬性的最大轮次否则模型可能陷入调工具-不满意-再调的死循环。触达层就是 Agent-Reach 的核心所有跟外部系统打交道的事情都在这里发生。工具注册、参数校验、权限、幂等、重试、限流、结果裁剪全部在这一层闭环。观测层负责把所有环节串起来。每一轮模型调用、每一次工具执行都挂在同一个run_id下面附带时间戳、耗时、入参、出参摘要、token 消耗。出了问题我只要拿一个run_id就能把整条链路完整重放一遍。这四层之间的接口要尽可能窄。我们现在的规矩是编排层只知道工具名 参数字典完全不知道底层是 HTTP 请求还是数据库操作还是脚本执行触达层只知道执行 返回结构化结果完全不知道是谁在调用。这条线守住后面加任何新工具都是纯增量。2.2 工具描述一个工具该暴露多少信息这是我认为整个项目里最值得反复打磨的地方。工具描述写得好不好直接决定模型能不能正确使用它。我们踩过的坑是一开始描述写得太随意只写了功能名和参数名结果模型频繁用错工具、传错参数。下面是我们最终定下来的工具描述字段一个都不能少字段作用常见错误写法name全局唯一的工具标识用do_stuff这种模糊命名description一句话说清什么时候用它只写查询订单没写适用场景parameters参数名、类型、是否必填、约束类型写成any模型直接乱传returns返回结构说明省略导致模型不会解析结果risk_levelread / write / destructive全部标成 read权限形同虚设examples一到两个正确调用示例完全没有示例我特别想强调description这一栏。很多人写的是查询订单信息这等于没写。有效的写法是把它写成适用条件加边界说明比如根据订单号查询订单的当前状态和金额。仅用于已知订单号的场景如果用户给的是手机号或姓名请先调用 search_orders 工具获取订单号。后面这半句话非常关键它直接把模型最容易犯的错堵住了。examples也不是装饰。模型对示例的模仿能力远强于对抽象描述的理解。我们在每个写操作工具上都放了一条完整的调用示例实测下来参数格式错误的比率下降了一大截。另外工具数量要控制。我们内部的经验是单个 Agent 暴露的工具最好不要超过二十个超过之后模型的选择准确率会明显下滑。如果确实有很多能力就按业务域拆成多个子 Agent各自持有自己的工具集。2.3 权限与沙箱在它伸手之前先上锁这是最容易被忽略、出事最狠的一环。我的原则很简单默认拒绝。任何工具如果没有被显式授予某个 Agent 调用权限就是不可调用的。我们把权限分成了三档。read档是最低风险的只读操作比如查数据、拉列表可以放开自动执行。write档会产生状态变更比如创建工单、发送消息、更新字段这一档我们要求必须有明确的会话上下文并且带幂等键。destructive档是删除、清空、批量修改这类操作无论模型多有把握一律走人工确认而且是那种把影响范围明明白白列出来给操作人看的确认。除了分档还有几道硬闸门。域名与目标白名单触达层维护一份允许访问的目标列表配置里写死的模型无法影响。配额每个工具、每个会话、每天都有调用上限超了直接拒绝并记录。参数边界像limit这种参数必须有最大值我见过模型传limit100000把数据库打挂的。密钥隔离外部系统的凭据只存在于触达层的运行时环境里绝不进入模型的上下文模型看到的只有工具名和参数。注意权限判定失败时返回给模型的应该是清晰的拒绝原因而不是一个笼统的错误。比如该操作需要人工审批已提交审批单 #123模型拿到这个信息可以继续推进流程如果只返回permission denied它大概率会换个姿势反复重试。3. 核心细节与实操要点把一次触达做稳3.1 工具注册与描述符设计工具注册我建议做成声明式用装饰器或者配置文件都行重点是让新增工具的成本降到最低。下面是我们简化后的写法from dataclasses import dataclass, field from typing import Any, Callable, Literal dataclass class ToolSpec: name: str description: str parameters: dict # JSON Schema 片段 returns: str risk_level: Literal[read, write, destructive] timeout_s: float 8.0 max_retries: int 0 idempotent: bool False rate_limit: str 60/min handler: Callable[..., Any] field(reprFalse, defaultNone) def to_schema(self) - dict: return { name: self.name, description: self.description, parameters: self.parameters, }注意to_schema()这个方法它只把模型需要知道的三样东西吐出去——名字、描述、参数结构。风险等级、超时、重试这些是给触达层自己看的不进上下文。这么做的好处是省 token也避免模型看到这个工具重试三次也没事之类的信息去做危险的推断。注册表用一个字典管理启动时做一次全局冲突检查重名直接报错退出。不要等到运行期才发现两个工具同名。3.2 参数校验与幂等两道最值钱的防线参数校验不要手写 if-else用 JSON Schema 校验器统一处理。我们流程是模型返回参数 → 类型和必填校验 → 业务规则校验 → 归一化。归一化这一步很重要比如把2024-01-05、2024/1/5、01-05-2024统一成标准格式再往下走能消掉一大类偶发错误。校验失败时返回给模型的内容必须是可修复的提示而不是堆栈。我习惯这样组织返回值{ ok: False, error_type: invalid_argument, field: start_date, message: start_date 必须是 YYYY-MM-DD 格式收到的是 2024/1/5, hint: 请把日期改写为 2024-01-05 后重试 }实测这种做法把模型连续三次传错同一个参数的概率压得很低因为它拿到了明确的修复方向。幂等是第二道防线而且只对write和destructive生效。核心逻辑是调用前用hash(run_id tool_name 规范化参数)生成幂等键去重存储里查一下。如果这个键在有效窗口内已经成功执行过直接返回上次的结果不再真正调用外部系统。有效窗口我们设的是 24 小时具体到你的业务可以调。def idempotency_key(run_id: str, tool_name: str, args: dict) - str: normalized json.dumps(args, sort_keysTrue, ensure_asciiFalse, separators(,, :)) raw f{run_id}|{tool_name}|{normalized} return hashlib.sha256(raw.encode(utf-8)).hexdigest()这里有个细节容易出错参与哈希的一定是规范化后的参数。如果参数字典里混进了一个每次都变的时间戳字段幂等就彻底失效了。所以我们在工具定义里会显式标注哪些字段不参与幂等计算。3.3 超时、重试与熔断参数怎么算出来这三个参数最忌讳拍脑袋。我的算法是这样的。超时先看外部接口的延迟分布。假设你手上有监控数据某接口 p50 是 120msp99 是 900ms。那超时就不要设 8 秒这种保险值设成 p99 的 1.5 倍也就是 1.35 秒左右取个整数 1500ms。设太长的后果是一旦接口卡住你的 Agent 整条链路都在等用户端看起来就是卡死。重试次数取决于失败类型。我把失败分成三类处理方式完全不同网络类错误连接超时、连接重置可以重试服务端 5xx 可以谨慎重试参数错误、权限错误、业务校验失败绝对不能重试重试一万次结果都一样。所以重试策略是绑在错误类型上的不是绑在工具上的。次数上读操作最多两次写操作如果不是幂等的就零次。退避用指数加抖动公式是delay min(cap, base * 2 ** attempt) * random.uniform(0.5, 1.5)。base 取 200mscap 取 3 秒。抖动这一项千万别省它能有效避免多个 Agent 在同一时刻一起重试造成的二次冲击。最后算一下总耗时预算这是很多人漏掉的一步项取值说明单次超时 T1500msp99 的 1.5 倍最大重试次数 N2仅网络类错误退避总和200 400 到 600ms带抖动单工具最坏耗时约 5.1sN×T 退避Agent 最大轮次8硬上限整轮最坏耗时约 41s需要在这里设整体熔断看到 41 秒这个数字你就明白为什么必须要有整体预算和熔断。我们现在的做法是给每次 run 设一个总时间预算比如 30 秒超过就直接中断把已经拿到的中间结果整理成一份部分完成的答复返给用户而不是让他一直等。熔断则按工具粒度做。连续失败次数超过阈值我们设 5 次且在统计窗口内60 秒失败率超过 50%就把这个工具短路一段时间我们设 30 秒期间所有调用直接返回服务暂不可用请稍后重试。这能防止一个坏掉的下游把所有 Agent 都拖垮。4. 实操过程从零搭起一条可用的触达链路4.1 环境准备与目录结构先把工程骨架立起来。我的目录结构是这样的逻辑是按层分而不是按实体分agent_reach/ specs/ # 工具描述定义一个工具一个文件 validators/ # 校验器和归一化函数 guards/ # 权限判定、限流、幂等 executors/ # 真正干活的适配器http / db / script observe/ # 日志、指标、链路追踪 registry.py # 工具注册表 reach.py # 对外的统一入口依赖上校验用jsonschemaHTTP 用httpx指标用你手头现成的方案就行。我建议不要引入太多重依赖触达层是基础设施越薄越稳。配置分两份一份是工具声明可以进代码库、走代码评审一份是运行时配置密钥、白名单、配额走配置中心或环境变量。这两份绝对不能混密钥进代码库是低级但极其常见的错误。4.2 编排循环的实现编排层的循环是整个系统的心脏。我把它写成一个显式状态机而不是递归这样中断恢复和轮次控制都好做MAX_TURNS 8 TOTAL_BUDGET_S 30 def run_agent(user_input: str, ctx: dict) - dict: messages build_initial_messages(user_input, ctx) tools registry.list_schema_for(ctx[agent_role]) started time.monotonic() trace [] for turn in range(MAX_TURNS): if time.monotonic() - started TOTAL_BUDGET_S: return partial_answer(messages, trace, reasonbudget_exceeded) resp llm.chat(messagesmessages, toolstools) messages.append(resp.as_message()) calls resp.tool_calls if not calls: return final_answer(resp, trace) results reach.execute_batch(calls, ctx) # 并行执行见 4.3 for r in results: messages.append(r.as_tool_message()) trace.extend(results) return partial_answer(messages, trace, reasonmax_turns)几个值得说的点。MAX_TURNS硬上限必须有8 是我们调出来的经验值大多数任务 3 到 5 轮就收敛了。TOTAL_BUDGET_S在每轮开头检查一次避免把时间都耗在一轮里。execute_batch支持并行因为模型经常一次返回多个互不依赖的调用串行执行纯属浪费——但要注意只有read档的工具允许并行有副作用的工具一律串行否则你无法保证执行顺序。4.3 接一个真实场景工单自动处理光看框架没感觉说个具体的。我们用它接的第一个场景是内部工单的自动分派和处理流程是这样的用户提交一段描述 → 模型判断工单类型 → 调用分类工具 → 根据分类调用不同的处理工具 → 需要人工介入的走审批 → 最后回复客户。工具集我们定义了五个classify_ticketread、search_similar_ticketsread、assign_ticketwrite、update_ticket_statuswrite、send_notificationwrite。注意这里没有 destructive 档的工具因为我们在第一阶段刻意不给模型任何删除能力。reach.execute_batch的内部逻辑大致是这样对每个调用做 schema 校验和归一化失败的直接构造错误结果不往下走。按工具名排序后分组read 组并行write 组串行。read 组用信号量限制并发度我们设 5避免瞬时打爆下游。write 组逐个执行每个都走幂等检查和权限判定。所有结果统一裁剪后返回。结果裁剪这一步我想多说两句。外部接口经常返回一大坨 JSON直接回灌给模型会让 token 消耗暴涨还容易把关键信息淹没在噪声里。我们的做法是每个工具在定义时就声明返回摘要模板只把关键字段提取出来超过阈值的长文本截断并标注。实测一个原本 4000 token 的返回被压到 300 token 以内模型的理解效果反而更好了。第一版上线之后跑了大概两周工单自动处理率稳定在一个我们比较满意的水平误分派率比人工基线还低一点。当然这不是因为模型有多神而是因为触达层把那些容易出错的地方都堵住了。4.4 观测与回放出事之后怎么定位没有观测的 Agent 就是黑盒。我们的观测有三层。结构化日志每一次工具调用写一条 JSON 日志字段包括run_id、turn、tool_name、args_digest参数哈希不记原文避免敏感信息落盘、duration_ms、status、error_type、retry_count。注意是args_digest不是args这个取舍很重要日志里不该出现用户手机号、身份信息这类内容。指标每个工具的上线指标包括调用量、成功率、p50/p95/p99 延迟、重试率、熔断触发次数。这几个指标要挂到看板上出问题第一时间能看出来是哪个工具在拖后腿。链路回放这是我们最得意的功能。因为所有调用都挂在run_id下而且每一步的输入输出都有摘要记录我们可以写一个回放脚本把某次失败的完整流程按时间顺序打印出来。定位问题的效率提升了非常多——以前要跟用户来回沟通半小时现在三十秒就能看出是模型选错了工具还是工具本身挂了。提示回放功能的价值不只是排查线上问题。我们还用它来构造评测集把线上真实跑过的失败案例固定下来每次改提示词或者改工具描述就跑一遍回归避免修好一个坏掉三个。5. 常见问题与排查技巧实录5.1 高频故障速查表下面这些是我们真真切切踩过的坑整理成表方便对照现象大概率原因处理方式模型反复调用同一个工具返回值里缺少明确的成功信号返回结构中显式加ok和summary让模型知道已经成功参数类型频繁出错工具描述里类型定义过于宽松用严格 JSON Schema并在 description 里写明类型要求同一个写操作执行了两次缺少幂等键或幂等键不稳定引入规范化参数哈希剔除时间戳等易变字段某个工具突然全部超时下游服务异常或网络抖动检查熔断配置是否生效必要时手动短接该工具Agent 整体响应很慢单工具超时设置过长或存在串行依赖按 p99 的 1.5 倍重设超时检查是否能并行token 消耗异常高工具返回结果没裁剪直接回灌增加返回摘要模板限制单次回灌长度权限判定总是通过工具风险等级标注错误逐个复核 risk_level写操作绝不能标成 read并发时出现数据错乱有副作用的工具被并行执行强制 write 档串行read 档才允许并行用这张表自查一遍能解决掉大部分Agent 不听话的问题。经验之谈是Agent 表现异常的时候先怀疑工程再怀疑模型。我统计过我们内部的问题分布大概七成出在触达层配置上只有三成是模型本身的判断问题。5.2 几个不写在文档里的坑第一个坑是错误信息泄露。有次一个下游接口报错把内部的服务名和一段 SQL 直接返回给了模型模型又把它写进了给用户的答复里。从那以后我们规定所有对外返回的错误信息必须经过一层映射只保留可展示的用户友好描述 内部错误码。内部细节只进日志。第二个坑是长上下文下的工具遗忘。对话轮次多了之后模型有时候会忘记某个工具的存在。我们的解决办法不是加大上下文而是在每轮重新注入一份精简的工具清单只有名字和一句话描述完整的定义只在需要时按名字拉取。这招在多轮长会话里效果非常明显。第三个坑是时间与时区。这个看起来很小但我们栽过。服务端用 UTC用户说昨天的订单模型算出来的时间范围跟用户理解的不一样。现在我们在系统提示词里明确写清楚当前时区并且在触达层对所有时间参数做统一转换只接受带时区的标准格式。第四个坑是空结果不等于失败。查询类工具返回空列表的时候如果返回结构里没有明确标注查询成功但无数据模型经常误以为调用失败了然后换参数重试。我们在返回结构里专门加了ok: true, count: 0, hint: 查询成功确实没有匹配数据不要重试这一句话消掉了一整类无效循环。5.3 成本与延迟的压榨技巧跑起来之后成本和延迟就成了要天天盯的指标。分享几个我们试出来确实有用的做法。合并只读调用。如果模型在同一轮里请求了三个查询工具而它们访问的是同一个数据源可以在触达层做一次批量合并一次拿回来再拆分。我们的场景里这招把平均延迟降了大概三成。结果缓存。只读类工具的结果做短时缓存key 用工具名加参数哈希TTL 设 30 秒到几分钟。对于高频重复查询命中率相当可观。写操作当然不能缓存。精简系统提示词。提示词越长每轮消耗越大。我们把系统提示词从最初的一大段压缩到只保留角色、边界、输出格式三块工具说明全部搬到工具描述里每轮 token 消耗明显下降效果不但没变差反而因为信息更聚焦而更稳定了。按需注入工具。前面提过工具数量超过一定阈值之后准确率会掉。我们的做法是根据当前会话的意图先做一次粗分类只把相关的十来个工具注入上下文。这样一来每次请求的 token 省了模型的选择也更准。最后分享一个我个人的习惯给每个工具加一个演练模式。在演练模式下触达层照样走完整的校验、权限、幂等流程但最后一步不发真实请求只返回一个模拟的成功结果。新工具上线前我会先让它跑几百次演练看看模型会怎么用它、会传什么参数确认没问题了再切换到真实模式。这个习惯帮我避开了至少两次可能造成生产事故的改动。踩过这些坑之后我最大的体会是Agent 这条路上模型能力其实是最不用操心的那一环——它一直在进步。真正决定你的系统能不能上生产的是那些枯燥的、没有技术含量的活儿参数校验写全了吗、幂等做了吗、超时算对了吗、日志留够了吗。Agent-Reach 这个名字听起来挺唬人做起来其实就是把这几十件小事一件件做扎实。后面如果要继续扩展我下一步打算做的是把审批流做成可插拔的——不同风险等级对接不同的审批通道让高风险操作的处理路径也变成配置项而不是写死在代码里。