1. Agent-Reach 是什么把会聊天变成能动手的那一层Agent-Reach 这个项目名我第一次看到的时候第一反应不是又一个 Agent 框架而是想起了去年让我们半夜爬起来的那次线上事故。模型的回答漂亮得挑不出毛病工单系统里的状态却一动不动——它能说但它碰不到真实世界。Agent-Reach 想解决的恰恰就是碰不到这件事它是 Agent 与外部系统之间那层负责真实触达的中间件管的是工具注册、参数校验、权限闸门、幂等重试、结果裁剪和全链路可观测。说得再直白一点如果你的 Agent 需要调接口、写数据库、发消息、改工单那它早晚要有这么一层只是有人把它散落在业务代码里有人把它抽出来单独做成项目。这篇东西适合三类人看。第一类是在做 AI Agent 开发、已经踩过模型说做完了其实没做这个坑的工程师第二类是在设计 Agent 架构、纠结 harness、skill、agent 三者边界的技术负责人第三类是刚开始学 agent 开发想找一条能落地的学习路线的新手。我会按照为什么这么设计—核心机制怎么实现—最小可用版本怎么搭—出问题怎么查的顺序讲中间会给出可以照着抄的工具协议、权限分级表、上下文预算计算公式和排查速查表。凡是原文没提到、属于我基于常见实践补全的部分我会明确说明是补充内容。1.1 从一次线上事故说起那次事故的现场大概是这样用户提了一句帮我把这批客户里超过 30 天没联系的标记成待跟进。模型的回答是已完成共标记 47 位客户。运营同事去后台一看一个都没改。查日志才发现模型确实发起了一次工具调用参数里带了limit: 50而我们的接口默认单页上限是 20多余的直接被静默丢弃接口返回 200模型看到成功两个字就宣布任务完成。这个链条里暴露了三个问题。工具执行结果没有做真实性校验接口返回 200 不等于业务成功分页参数没有任何地方告诉模型你这一批只处理了 20 个信息在 Reach 层被吞掉了最关键的是整个执行过程没有一条能串起来的 Trace我们花了两个小时才定位到是哪一次调用丢的数据。这三个问题后来成了 Agent-Reach 这个项目最核心的三个模块结果归一化、执行事实回灌、链路可观测。很多人做 Agent 项目一上来就卷提示词我觉得顺序反了。提示词决定上限Reach 层决定下限而线上事故全部发生在地板上。1.2 Reach 的三层含义触达、受控触达、可观测触达把 Reach 拆开看它其实有三层递进的含义理解这三层整个项目的设计动机就清楚了。第一层是触达也就是能不能调通。这一层最基础把 HTTP 请求、SDK 调用、数据库操作包成模型能理解的工具描述让模型知道有这么个能力、要传什么参数。绝大多数人卡在这一层就以为做完了。第二层是受控触达也就是允不允许这么调。这里涉及权限、风险分级、参数白名单、频率限制。一个能改数据的工具和一个只读工具风控等级完全不同。我在实践里的做法是读操作放开写操作必须过闸门破坏性操作删除、批量修改、资金相关一律走人工确认模型只能生成待确认的任务不能直接执行。第三层是可观测触达也就是刚才到底发生了什么。每一次工具调用都要有完整的输入、输出、耗时、成本、是否命中缓存、是否重试、幂等键是什么。没有这一层你的 Agent 就是一个黑盒出了问题只能靠猜。三层缺一层都不算完整。我见过不少 agent 项目只做了第一层demo 阶段惊艳上线两周就被业务方叫停。1.3 什么样的人需要认真看这套东西坦白说如果你的 Agent 只是做问答、做总结、做单轮文本生成不碰任何外部系统那你不需要 Reach 层硬加只会增加复杂度。但只要出现下面任意一种情况这层就是刚需需要调用三个以上的外部接口需要在执行过程中保存中间状态需要多 agent 协作且共享同一批工具需要对执行做审计或者计费。还有一个判断标准很有意思当你的团队开始讨论这个工具该不该给模型用的时候就说明你已经需要 Reach 层了因为这个问题本身就是权限闸门要回答的问题。没有这层的时候这个讨论的结果通常是一堆散落在业务代码里的if判断三个月后谁也不敢动。2. 架构设计为什么 Reach 必须独立成层2.1 和 harness、agent、skill 的边界怎么划这几个词现在混着用的情况特别严重热词里harness 和 agent 区别skill 和 agent 的区别被反复搜说明大家是真的分不清。我按自己的理解给一个能指导工程实践的划分。harness是运行外壳管的是生命周期循环怎么转、上下文怎么攒、什么时候停、工具怎么执行、日志怎么写。它本身不智能是一套确定性代码。agent是决策主体是模型加上提示、记忆、工具集之后那个会自己判断下一步干什么的东西。skill是可复用的能力封装比单个工具高一层通常是提示词流程若干工具的组合包比如生成周报这个 skill 内部会调数据查询、汇总、格式化三个工具。Agent-Reach在这套划分里属于 harness 的一部分是 harness 中专门负责外部交互的那个子系统。我坚持把它独立出来是因为它的变更频率和 harness 主体完全不同。循环逻辑半年不改一次工具和权限规则一周改三次。混在一起写每次加个接口都要动核心循环回归测试成本高得吓人。补充一句我的经验如果你的 Agent 项目现在还处于所有工具定义写在一个 3000 行的文件里的阶段先别急着拆架构先把工具描述结构化那一步的收益最大。2.2 工具注册表 vs 硬编码分支早期我用的方案很土在提示词里手动列出所有可用工具模型选了之后用一长串if/elif分发。这个方案在 5 个工具以内能跑到 15 个就崩了——提示词本身占掉大量上下文if链条长得没法维护新增一个工具要改四处地方。后来换成注册表模式工具用声明式描述定义运行时统一注册、统一分发。两种方案的对比我整理成了表对比维度硬编码分支注册表模式新增工具改动点提示词、分发函数、文档、测试一个描述文件提示词占用全量塞入随工具数线性增长可按需检索只注入相关工具权限控制分散在各分支里集中在注册表元数据测试方式只能端到端测可对单个工具做单元测试适用规模5 个工具以内10 个工具以上注册表模式还有一个隐性好处工具描述本身变成了文档。新人接手的时候读一遍注册表就知道系统能干什么比读代码快得多。2.3 上下文预算Reach 层最容易被忽略的成本项工具一多上下文就成了稀缺资源。这里给一个可以直接套用的预算分配算法也是我在实际项目里用的。假设模型上下文窗口是 128k token预留规则如下系统提示与角色设定3000历史对话保留20000模型输出预留8000安全缓冲应对 tokenizer 误差5000那么留给工具相关内容的预算是128000 - 3000 - 20000 - 8000 - 5000 92000token。这 92000 还要再分成两半工具描述占 30%工具结果占 70%。也就是工具描述约 27600工具结果约 64400。再往下算单次工具结果的上限。如果一轮里平均可能触发 4 个工具那单个结果裁剪上限就是64400 / 4 ≈ 16000token。实际操作中我会再打个七折取 11000留出应对某个工具结果特别大的余量。注意这个计算是估算不是精确值。不同模型的 tokenizer 差异能达到 15%所以安全缓冲那一项千万别省。我见过不止一个项目因为把缓冲压到 1000导致长对话到后半程直接被截断模型的回答质量断崖式下跌。3. 核心机制拆解协议、权限、幂等、异步3.1 工具描述协议的三段式写法工具描述写得好不好直接决定模型调用准不准。我总结的写法是三段式做什么、什么时候用、不能用来干什么。很多人只写第一段结果模型在不该用的场景也调它。下面是一个可以直接抄的 YAML 结构name: crm.contact.update version: 1.2.0 summary: 更新 CRM 联系人中的单个字段 when_to_use: 用户明确要求修改某个联系人的姓名、标签或跟进状态时 when_not_to_use: 用户只是询问信息、或要求批量修改超过 10 条记录时应改用 batch 工具 risk: write idempotent: true idempotency_key: {{contact_id}}:{{field}}:{{value}} params: contact_id: type: string required: true pattern: ^C[0-9]{8}$ field: type: string required: true enum: [name, tag, follow_status] value: type: string required: true max_length: 64 returns: success: boolean changed: boolean previous_value: string几个关键点。enum一定要写死不要让模型自由发挥字段名这是参数错误最大的来源。when_not_to_use这一项看起来啰嗦实测能减少三成左右的误调用。idempotency_key提前在描述里声明执行层才能自动算出来不需要模型操心。返回值里我特意加了changed字段因为很多场景下接口成功但数据没变模型需要知道这个区别。3.2 三级风险分级与权限闸门权限这件事我的做法是只分三级分太细没人记得住。风险等级典型操作处理策略是否需要确认read查询、检索、统计直接执行记录日志否write新增、修改、发送执行前校验参数白名单记录变更前后值视场景destructive删除、批量覆盖、资金操作生成待确认任务不直接执行是闸门的实现位置很关键。我把它放在工具执行器的最外层任何调用进来先过闸门而不是散在各自的工具实现里。这样加新工具的时候只要在注册表里标好risk字段闸门自动生效不会漏。还有一个细节值得说参数白名单要和风险等级绑定。同样是 write 级别允许改tag不等于允许改owner因为后者的影响面大得多。我在注册表里加了一个allowed_callers字段标记哪些 agent 角色或者哪些 skill 可以调这个工具。多 agent 协作的场景下这一项特别重要——检索 agent 不应该有写权限这是基本的隔离原则。3.3 幂等键设计让重试变成安全动作Agent 执行过程中失败是常态。网络抖动、接口限流、模型超时任何一环都可能中断。没有幂等设计的时候重试就变成了赌博运气好是重复执行运气不好是重复扣款。幂等键的设计原则是从业务语义里提取而不是从请求里提取。用 UUID 每次重试都不同等于没做。正确的做法是把这次操作在业务上唯一标识什么抽出来。以上面的联系人更新为例contact_id:field:value三个拼起来就能唯一标识一次修改意图重试十次和执行一次的效果一样。对于创建类操作可以用业务主键加时间窗口比如order:{{user_id}}:{{date}}:{{amount}}同一用户同一天同金额的创建请求在 5 分钟内视为同一次。执行器这边的实现很朴素拿幂等键去查缓存我用的是带 TTL 的键值存储TTL 设 24 小时命中就返回上次的结果没命中就执行并写入。这里有个坑缓存要存错误结果不只是成功结果。如果一个操作上次因为参数非法失败了重试时应该直接返回同样的错误而不是再打一次接口。注意幂等键的长度要控制。我见过把整个请求体序列化后做哈希的写法键长到 200 多字符缓存层直接被撑爆。正常控制在 64 字符以内。3.4 长任务的异步触达与回执闭环同步调用有天然的上限。凡是可能超过 10 秒的操作我都改成异步工具调用立即返回一个任务 ID后台任务执行完之后把结果写回会话。这个模式最大的难点不是异步本身而是回执怎么让模型理解。我的做法是给异步任务定义一个统一的状态查询工具模型拿到任务 ID 之后可以选择轮询或者结束本轮等下一轮用户交互时再查。同时后台任务完成时会往会话历史里追加一条系统消息格式固定为任务 {{task_id}} 已完成结果摘要...这样即使模型没有主动查下一轮也能看到。轮询策略也要控制。我给的默认参数是首次等待 2 秒之后按 1.5 倍退避最大间隔 15 秒总超时 120 秒。超过之后就告诉用户任务还在处理中完成后会通知你。别让模型无脑循环那会烧掉大量 token还会把上下文塞满重复的状态查询记录。4. 动手搭一个最小可用的 Reach 层4.1 目录结构与依赖清单我倾向用 Python 写这一层生态成熟、调试方便。目录结构按职责切分不按技术分层agent_reach/ registry/ # 工具描述文件与加载器 tools/ crm_contact_update.yaml ticket_query.yaml gate/ # 权限闸门与风险分级 policy.py executor/ # 执行、重试、幂等 runner.py idempotency.py shaper/ # 结果裁剪与归一化 trimmer.py normalizer.py observe/ # 埋点与 Trace tracer.py router/ # 路由识别节点 intent_router.py依赖不用多pydantic做参数校验、httpx做异步请求、pyyaml读描述文件就够了。别一上来就上重型编排框架Reach 层的逻辑本身不复杂被框架的抽象层挡住反而不好排查。补充一句如果你的项目已经在用某个主流 agent 框架Reach 层依然建议自己做因为框架给的工具调用通常只有最基础的封装幂等和权限这些都得自己补。4.2 工具注册与路由识别节点实现注册表加载器的核心是把 YAML 转成内存对象并做一次启动时的自检。自检包括名字是否重复、参数 schema 是否合法、幂等键模板引用的字段是否都在 params 里声明。这一步能拦掉大量低级错误。import yaml, hashlib, json from pathlib import Path from pydantic import BaseModel, ValidationError class ToolSpec(BaseModel): name: str version: str summary: str when_to_use: str when_not_to_use: str risk: str idempotent: bool False idempotency_key: str | None None params: dict returns: dict class ToolRegistry: def __init__(self, tool_dir: str): self.tools: dict[str, ToolSpec] {} self._load(Path(tool_dir)) def _load(self, root: Path): for f in root.rglob(*.yaml): data yaml.safe_load(f.read_text(encodingutf-8)) spec ToolSpec(**data) if spec.name in self.tools: raise ValueError(fduplicate tool name: {spec.name}) if spec.idempotent and not spec.idempotency_key: raise ValueError(f{spec.name} 声明幂等但缺少幂等键模板) self.tools[spec.name] spec def render_idem_key(self, name: str, args: dict) - str | None: spec self.tools[name] if not spec.idempotent: return None raw spec.idempotency_key for k, v in args.items(): raw raw.replace({{%s}} % k, str(v)) return hashlib.sha256(raw.encode()).hexdigest()[:48]路由识别节点这一块热词里出现过路由识别节点很多人理解成要用一个小模型做意图分类。我的实测结论是工具数量在 30 个以内不需要额外模型。把工具名和 summary 拼成候选列表丢给主模型让它自己选准确率已经够用。只有当工具超过 50 个、且存在大量语义相近的工具时才值得上一个轻量检索做粗筛把候选压到 10 个以内再交给主模型。多一次模型调用就是多一次延迟和成本能省则省。4.3 结果裁剪的参数计算与代码裁剪不是简单截断字符串那会截掉关键字段导致模型理解错误。我的策略是结构化裁剪先按字段重要度排序保留核心字段对列表类字段按条数截断并明确标注还有 N 条未展示。def trim_result(payload: dict, max_tokens: int, core_fields: list[str]) - dict: # 粗略换算中文约 1.5 字符/token英文约 4 字符/token取保守值 2 budget_chars max_tokens * 2 out {} for f in core_fields: if f in payload: out[f] payload[f] items payload.get(items) if isinstance(items, list): kept, used [], len(json.dumps(out, ensure_asciiFalse)) for it in items: cost len(json.dumps(it, ensure_asciiFalse)) if used cost budget_chars: break kept.append(it) used cost out[items] kept if len(kept) len(items): out[_truncated] f共 {len(items)} 条已展示 {len(kept)} 条剩余请用分页参数继续查询 return out_truncated这个字段是精髓。它让模型知道数据不完整从而选择翻页或者告知用户而不是像文章开头那次事故一样以为 20 条就是全部。我后来复盘时认为这一个字段的价值超过了当时整个提示词优化的总和。4.4 可观测性埋点Trace、Span 与成本归因埋点我按三层来。会话级 Trace记录整轮对话的起止、总 token、总耗时。工具级 Span每次调用一条记录工具名、参数哈希、耗时、重试次数、幂等命中情况。异常级 Event记录所有非预期情况包括参数校验失败、闸门拦截、超时。import time, uuid, logging def traced_call(registry, gate, runner, name, args, trace_id): span_id uuid.uuid4().hex[:16] t0 time.time() decision gate.check(name, args) if not decision.allowed: logging.warning(span%s gate_blocked tool%s reason%s, span_id, name, decision.reason) return {error: blocked, reason: decision.reason} try: result runner.run(name, args) return result finally: logging.info(span%s trace%s tool%s cost_ms%d, span_id, trace_id, name, int((time.time() - t0) * 1000))别小看这几行日志。上线之后你会发现排查问题的时间有七成花在这次调用到底有没有发生而不是为什么失败。日志只需要回答有没有发生问题就解决大半。5. 常见问题与排查速查表5.1 那两条最吓人的报错到底怎么回事搜 agent 相关问题时有两类报错出现频率极高一个是agent couldnt generate a response, please try again另一个是agent execution terminated due to error。表面上看是模型的问题实际上我遇到的情况里超过一半出在 Reach 层。第一种情况模型没能生成回复常见原因是工具返回的结果把上下文塞满了模型没有剩余空间组织语言于是返回空。处理方式是检查那一轮的工具结果总量如果接近或超过预算上限立刻收紧裁剪参数。另一个原因是工具结果里包含了大段二进制或乱码内容污染了上下文需要在归一化阶段就把这类内容过滤掉。第二种情况执行意外终止通常是某个工具抛了未捕获的异常直接把整个循环打断了。正确做法是在执行器里做全量异常捕获任何工具失败都转成一个标准的错误结果返回给模型让模型有机会换个思路。一个工具失败不应该导致整轮任务失败这是我用血换来的原则。5.2 排查速查表现象高概率原因处理动作模型说已完成但数据没变工具返回成功但业务失败缺少changed字段补充结果归一化返回真实业务状态同一工具被反复调用相同参数结果没有回灌到上下文或幂等未生效检查结果注入逻辑与幂等缓存长对话后半程质量骤降上下文超限被静默截断复核预算分配收紧工具结果上限参数类型错误频发描述里缺少enum和pattern补全参数约束宁严勿松执行中途整体中断工具异常未捕获执行器加全量异常兜底多 agent 互相覆盖数据缺少调用方隔离注册表加allowed_callers字段成本突然翻倍重试没有上限或轮询过于频繁加重试上限与退避策略5.3 几条用血换来的经验第一条永远不要相信接口返回 200 就是成功。归一化层必须从业务响应体里读真实的成功标记很多系统会把错误包在 200 响应里字段名还各种各样。第二条工具描述里的when_not_to_use比when_to_use更值钱。写前者逼你想清楚边界而模型的误调用几乎全部发生在边界模糊的地方。第三条别在 Reach 层做业务逻辑。我曾经为了让某个流程更智能在工具执行器里加了一段自动补全参数的逻辑结果三个月后没人能解释清楚为什么某个字段会变成那个值。Reach 层只做四件事校验、授权、执行、记录。6. 测试与上线前检查6.1 Agent 测试的分层方法Agent 的测试难做是因为输出不确定。我的应对是分层测把不确定性尽量往上推。最底层的工具测试完全确定给定参数、断言结果用常规单元测试框架就行覆盖率要做到 100%因为这一层没有不确定因素。中间层是路由测试给定一批用户表达断言模型选中的工具在预期集合内。这一层允许一定误差我的标准是核心场景 100% 命中边缘场景 85% 以上。最上层是端到端测试给定完整任务描述断言最终的业务状态变化。这一层不检查中间过程只看结果。我会准备 20 到 30 个真实场景的用例集每次改动 Reach 层都全量跑一遍。补充一个技巧端到端测试用固定随机种子并且把模型的温度调到 0。虽然不能完全消除波动但能大幅提高可复现性。6.2 上线前自查清单上线前我会逐条过一遍下面这些有一条不满足就不发。所有写操作都有对应的回滚方案或者本身就是幂等可重入的destructive 级工具全部走人工确认没有任何例外幂等缓存的 TTL 覆盖了最长的重试窗口每个工具都有超时设置没有依赖底层默认值工具结果裁剪有明确的_truncated标记Trace 能通过一个 ID 串起整轮对话的所有调用关键路径有告警且告警能定位到具体工具名有一套可以在本地复现线上问题的回放机制最后这条我觉得最容易被忽略。把线上那次调用的工具名、参数、结果序列化存下来本地能直接回放排查效率能提升一个数量级。这个机制搭起来其实不难一次序列化加上一个回放入口几十行代码的事。我自己在这一层反复调整过好几轮最后留下来的体会很简单Reach 层不需要聪明它需要的是可预测。所有让它变聪明的冲动最后都会变成三个月后别人看不懂的一段代码。