1. Agent-Reach 到底是什么从一个反复失败的任务说起1.1 先讲一个我踩过的真实坑去年我接过一个内部需求让 Agent 每天早上自动把三个系统的数据汇总成一份运营日报。听起来不难第一版两天就跑通了——调接口、拼模板、发出去。结果上线第三天就出事了某个系统的接口换了个字段名Agent 没报错直接拿着一堆空值生成了份看起来很正常的日报还发给了业务方。事后复盘发现问题根本不在模型能力而在于整个链路里没有一个环节负责确认自己真的够得着数据。模型以为它够到了实际上它摸到的是空气。这件事让我重新理解了一个词触达。大模型本身是个封闭的推理器它的知识上限就是训练截止日期和上下文窗口。真正让它变成能干活的 Agent的是它伸出去的那些手——工具调用、记忆检索、外部系统访问、其他 Agent 的协作。手伸不伸得到、伸到之后拿回来的是不是真东西、拿错了怎么办这一整套能力我后来统称为Agent-Reach。所以这篇文章聊的 Agent-Reach不是指某一个具体的 SDK 或者某个开源仓库而是指围绕Agent 能触达什么、怎么触达、触达失败怎么办这一整套工程能力。你可以把它理解成一个能力框架或者设计范式落到代码上它表现为工具注册表、记忆层、路由节点、协作协议、权限边界这一堆具体的东西。1.2 Reach 解决的是模型不会自己承认失败这个顽疾很多人做 Agent 开发第一反应是把 prompt 写好一点、把工具描述写详细一点。但你只要跑过几十个真实任务就会发现模型有个非常讨厌的特性它倾向于给出一个答案而不是承认自己拿不到答案。你给它一个查询订单的工具订单不存在的时候返回空数组它不会说查不到它会说该订单状态正常。Agent-Reach 这个思路的核心就是把这种盲目自信从工程层面堵死。它的做法不是靠 prompt 求模型诚实而是靠结构强制每一次外部触达都必须有明确的返回契约返回不符合契约就直接中断链路而不是把不确定的东西继续往下传。这一点非常关键因为它把可靠性从模型行不行转移到了工程约束够不够硬。适合看这篇内容的人大致分三类一是刚开始做 Agent 开发、还在纠结框架选型的人二是已经跑通了 Demo 但一上生产就翻车的人三是想把单 Agent 拆成多 Agent 协作、但不确定该怎么拆的人。下面我按我自己的实践顺序一层一层拆给你看。1.3 别把 Agent 和 Harness 搞混这是两码事网上经常有人问 harness 和 agent 的区别其实一句话能说清Agent 是谁在做事Harness 是做事的环境和约束。Agent 包含模型、prompt、决策循环Harness 包含工具沙箱、执行超时、重试策略、权限控制、日志。你可以把 Agent 想成一个外包员工Harness 就是公司的门禁、报销制度和考勤系统。员工再聪明没有门禁他也进不了机房。我做 Agent-Reach 相关实践时会把大部分精力放在 Harness 这一侧。原因很现实模型能力是外部变量你控制不了但工具契约、超时、重试、权限这些全是你能拍板的东西。一个工业级 Agent 和玩具 Demo 的差距八成在这里而不是在模型换了哪个版本。顺带说一个高频困惑skill 和 agent 的区别。我的理解是Skill 是原子能力是会做一件事Agent 是决策主体是决定什么时候做哪件事。Skill 不该有自己的目标它只负责把输入变成输出。一旦你发现某个 Skill 里出现了如果不行就换个方案这种逻辑说明它在偷偷变成 Agent这时候就该把它拆出来了。2. 架构拆解Reach 的四层触达模型2.1 感知与路由层先判断该谁上场路由识别节点是我在 Agent-Reach 里最先落地的模块也是最容易被忽略的模块。很多人的做法是把所有工具描述一股脑塞给主模型让它自己选。工具少于 10 个的时候还行超过 20 个就开始乱选超过 50 个基本没救——上下文被工具描述吃满了模型反而看不清任务本身。我的做法是加一个轻量路由层先用小模型或者规则做一次粗分类把候选工具从 50 个收敛到 5 个以内再交给主模型精挑。路由层的输出必须是结构化的别让它自由发挥ROUTE_PROMPT 你是路由节点只输出一行 JSON不要任何解释文字。 候选意图: {intents} 用户输入: {query} 输出格式: {{intent: 意图名, confidence: 0.0, slots: {{}}}} 判定规则: - confidence 低于 0.6 时 intent 填 unknown - slots 只填能从输入里直接读到的参数不要推测 这里有个细节值得展开为什么要求 confidence。因为路由层最大的风险不是分错而是分错了还挺自信。有了置信度你就能设阈值做兜底——低于 0.6 就直接走澄清流程问用户一句您是想查订单还是想改地址成本远低于让 Agent 一路错到底。路由还有个隐形收益它让每个下游 Skill 面对的输入都变得干净。我见过太多项目Skill 里一半代码在处理输入可能是三种格式的兼容逻辑这种脏活应该全部收口在路由层解决。2.2 记忆层分三层存别混在一起Agent 记忆这块我的经验是必须物理分层而不是靠一个数组硬扛。混在一起的下场就是上下文越来越长、检索越来越不准、成本越来越高。我一般分三层层级存什么生命周期典型实现工作记忆当前任务的对话与中间结果单次会话内存滑窗带 token 预算情节记忆历史任务的摘要与结论数天到数周结构化存储 定期压缩语义记忆稳定事实、用户偏好、领域知识长期向量检索 元数据过滤工作记忆的关键是预算控制。我见过有人直接开maxlen100的队列结果 30 轮之后上下文爆掉。正确做法是按 token 估算来裁剪而不是按条数class WorkingMemory: 滑动窗口 重要性打标严格控制进入上下文的 token 预算 def __init__(self, max_items20, token_budget3000): self.buf deque(maxlenmax_items) self.token_budget token_budget def push(self, role, content, importance1.0): self.buf.append({ role: role, content: content, imp: importance, ts: time.time() }) def dump(self): # 先按重要性排序挑再按时间排回去 picked, used [], 0 for it in sorted(self.buf, keylambda x: x[imp], reverseTrue): cost len(it[content]) // 2 # 中文粗略按 2 字符 1 token 估 if used cost self.token_budget: continue picked.append(it) used cost return sorted(picked, keylambda x: x[ts])importance从哪来我的做法是给几个固定场景打标用户显式纠正1.0、工具返回的确定性事实0.9、普通对话0.5、模型的中间推理0.3。中间推理最容易占地方也最不该被长期保留——它过期极快留着只会干扰后续判断。题外话现在热词里经常把 llm、embedding、agent 混着讲其实三者关系很清楚LLM 是推理引擎Embedding 是把文本变成可比较的向量的编码器Agent 是拿这两样东西加上工具去干活的调度者。搞混了就容易在选型时做出奇怪的决定比如指望用 embedding 模型去做逻辑推理。2.3 编排层串行、并行、层级选错了会拖垮延迟编排这件事没有万能解。我一般按任务形态来选串行步骤之间有严格依赖比如先查库存再下单。优点是链路清晰好排查缺点是延迟累加五步就要五倍时间。并行多个子任务互不依赖比如同时查三个数据源。这时候一定要给每个分支设独立超时否则最慢的那个决定整体延迟。层级主 Agent 拆任务子 Agent 各自执行再汇总。这是我用得最多也最容易翻车的一种翻车点几乎都在上下文传递上。层级编排有个反直觉的坑子 Agent 不该看到主 Agent 的全部上下文。我早期图省事把整个对话历史透传给每个子 Agent结果子 Agent 被无关信息带偏输出质量比单独调用还差。正确做法是给每个子 Agent 一份最小任务包——目标、约束、输入数据、输出格式四样东西多一个字都不给。2.4 执行层与 Skill 边界把副作用关进笼子执行层是所有副作用发生的地方写数据库、发消息、调第三方。这里我给自己定了三条硬规矩后面第五节会展开。第一条所有写操作必须有幂等键。Agent 会重试网络会抖动没有幂等键就等着重复下单吧。第二条返回值必须是强类型结构不能是自然语言。工具返回一句操作成功啦模型接下来就只能瞎猜。第三条超时必须显式设默认不设超时等于默认允许永久挂起。Skill 的边界也在这层体现。我的判定标准是如果一个 Skill 需要知道上一个 Skill 干了什么那它就不该叫 Skill它是个流程节点。Skill 应该是无状态的纯函数——给同样的输入给同样的输出不读全局变量不依赖调用顺序。做到这一点你的 Skill 才能被复用、被测试、被别的 Agent 调用。3. 手把手搭一个最小可用原型3.1 环境准备与依赖选型先说我自己的选型逻辑。做原型阶段我倾向于用最少的依赖跑通最完整的一条链路而不是一上来就上重量级框架。理由很直接框架能帮你省掉编排的体力活但也会把触达失败的现场包起来你反而看不见问题在哪。等链路跑通了再决定要不要换框架也不迟。语言上Python 生态在这块最顺手。如果你团队是 Java 栈Spring AI 那套也能做只是工具注册和流式处理的写法差别不小迁移时注意别照搬。这里我用 Python 演示python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install httpx pydantic jinja2 python-dotenv # 向量那部分先用本地实现原型阶段没必要上服务几个选择理由httpx是因为它原生支持异步和超时配置工具调用场景几乎全是 IO 等待pydantic是用来做返回契约校验的这是整个 Reach 思路的地基jinja2负责 prompt 模板别在代码里拼字符串改一次 prompt 要重启一次服务太痛苦。注意原型阶段就不要引入向量数据库服务了。先用内存写一个最简单的余弦相似度检索几十条数据完全够用等数据量上千了再换。3.2 目录结构让触达链路一眼可见agent-reach/ ├─ core/ │ ├─ loop.py # 决策循环 │ ├─ router.py # 路由识别节点 │ └─ contracts.py # 返回契约定义 ├─ tools/ │ ├─ registry.py # 工具注册表 │ └─ impl/ # 具体工具实现 ├─ memory/ │ ├─ working.py # 工作记忆 │ └─ longterm.py # 长期记忆 ├─ skills/ # 原子能力无状态 └─ config/ └─ limits.yaml # 超时、重试、并发上限这个结构里我特意把contracts.py和limits.yaml单独拎出来。原因是它们是全局约定——所有工具、所有 Skill、所有 Agent 都要遵守同一套契约和同一套限额。放在一起改的时候不会漏。我见过把超时时间散落在二十个文件里的项目最后没人说得清到底哪个工具没设超时。3.3 工具注册与返回契约先定义契约再写工具顺序不能反。契约长这样from pydantic import BaseModel, Field from typing import Optional, Literal class ToolResult(BaseModel): ok: bool code: Literal[OK, NOT_FOUND, TIMEOUT, UPSTREAM_ERROR, BAD_INPUT] data: Optional[dict] None message: str Field(default, description仅用于日志不进入模型上下文)注意message字段的注释——它不进模型上下文。这个设计非常有用因为工具内部的错误详情堆栈、上游返回的脏数据对模型毫无价值反而会污染上下文。模型只需要知道ok和code然后根据code决定是重试、换方案还是上报。然后是注册表from dataclasses import dataclass from typing import Callable, Any dataclass class Tool: name: str desc: str schema: dict fn: Callable[..., Any] class ToolRegistry: def __init__(self): self._tools: dict[str, Tool] {} def register(self, name, desc, schema): def deco(fn): self._tools[name] Tool(name, desc, schema, fn) return fn return deco def get(self, name): return self._tools.get(name) def describe(self, namesNone): items self._tools.values() if names is None else \ [self._tools[n] for n in names if n in self._tools] return [{name: t.name, description: t.desc, parameters: t.schema} for t in items]关键点在describe(names)这个可选参数。路由层筛出来的候选工具名直接传进来只把这几个的描述塞给模型上下文立刻瘦下来。这是我觉得投入产出比最高的一个小改动。3.4 一个真实 Skill 的写法拿生成周报举例展示一下无状态 Skill 该长什么样def build_weekly_report(rows: list[dict], lang: str zh) - str: 纯函数输入结构化数据输出 Markdown不读全局、不写磁盘 total sum(r[count] for r in rows) top sorted(rows, keylambda r: r[count], reverseTrue)[:5] if not rows: # 关键空数据要显式表达不能返回本月表现良好 return 数据源返回空结果无法生成汇总请检查上游状态。 lines [f本周总量{total}, , | 项目 | 数量 |, | --- | --- |] lines [f| {r[name]} | {r[count]} | for r in top] return \n.join(lines)看到那个if not rows了吗这是我在 1.1 里那个坑的直接产物。任何 Skill 都必须显式处理空输入而且处理方式必须是报错而不是编一个合理的结果。这一条我建议直接写进团队代码规范。3.5 跑起来并调试组装主循环三个要点单步超时、最大步数、每一步都落日志。async def run(query: str, max_steps: int 8, step_timeout: float 15.0): mem WorkingMemory(token_budget3000) mem.push(user, query, importance1.0) for step in range(max_steps): route await route_intent(query, mem) if route[confidence] 0.6: return 我不太确定你的意图能再说明一下吗 tools registry.describe(candidates_for(route[intent])) action await decide(mem.dump(), tools) # 让模型决定调哪个 if action[type] final: return action[content] try: raw await asyncio.wait_for( registry.get(action[name]).fn(**action[args]), timeoutstep_timeout ) result ToolResult(**raw) # 强制走契约校验 except asyncio.TimeoutError: result ToolResult(okFalse, codeTIMEOUT) if not result.ok: # 注意只把 code 塞回上下文不塞 message mem.push(tool, f调用 {action[name]} 失败原因码 {result.code}, 0.9) continue mem.push(tool, json.dumps(result.data, ensure_asciiFalse), 0.9) return 任务步骤超出上限已停止请人工介入。这里三个数字我都是踩坑踩出来的max_steps8超过 8 步基本说明路由出了问题继续跑只是烧钱step_timeout15.0内部接口 P99 在 8 秒左右留一倍余量confidence阈值 0.6低于这个数走澄清的准确率明显比硬猜高。4. 多 Agent 协作与 A2A 协作卡设计4.1 单 Agent 的天花板在哪什么时候该拆多 Agent我的判断标准只有一条是不是出现了能力冲突。具体表现为三种情况。一是工具集太大路由准确率掉到 70% 以下二是 prompt 里塞了互相矛盾的指令比如既要严格按格式输出又要灵活应对各种输入三是不同任务需要不同的温度、不同的模型、不同的上下文策略。如果只是任务步骤多那不该拆多 Agent该做的是把流程编排好。我见过把查数据和写报告拆成两个 Agent 的项目结果两个 Agent 之间为了传个 JSON 写了三百行胶水代码还不如一个 Agent 干。拆分的收益必须大于通信成本这是硬账。4.2 Agent Card协作前先自报家门多 Agent 协作第一步不是写通信代码是让每个 Agent 把自己的能力说清楚。这套东西一般叫 Agent Card本质就是一份能力声明清单{ name: report-writer, version: 1.0.0, description: 根据结构化数据生成周报支持中英双语, capabilities: { streaming: true, pushNotifications: false }, defaultInputModes: [application/json], defaultOutputModes: [text/markdown], skills: [ { id: weekly-report, name: 周报生成, description: 输入 rows 数组输出 Markdown 周报, examples: [帮我出一份上周的周报] } ], securitySchemes: { bearer: {type: http, scheme: bearer} } }我在实践中发现几个字段最容易被写漏但恰恰最影响协作成功率defaultInputModes不写这个调用方不知道该传 JSON 还是纯文本只能试。securitySchemes认证方案必须提前声明否则运行到一半才发现鉴权不匹配整条链断掉。examples这个字段价值被严重低估。调用方 Agent 判断该不该找这个 Agent时示例比描述管用得多。关于协议版本的差异我接触下来的感受是早期草案阶段 Agent Card 的字段比较少基本只有名字、描述、一个能力列表后续版本陆续补上了能力开关、安全方案、默认输入输出模式这些字段整体思路是从我能做什么扩展到了我以什么方式、在什么前提下能做。跨版本对接的时候别假设字段一定存在所有可选字段都要做缺省兜底。4.3 三种编排模式的实际取舍多 Agent 编排我常用三种各自有明确的适用场景和坑模式适用场景主要风险我的应对顺序接力工序明确的流水线中间某个 Agent 输出格式漂移每个环节做 schema 校验并行广播多源检索、多方案对比慢分支拖累整体延迟每分支独立超时 部分结果可用主管调度任务需要动态拆解主管上下文膨胀只传任务包不传全量历史顺序接力最容易被低估的风险是格式漂移。A Agent 输出的是结构化对象B Agent 拿到之后顺手转成了自然语言描述C Agent 就抓瞎了。我的做法是在每个交接点强制做一次 schema 校验不通过就打回重做绝不宽容处理。并行广播的关键设计是允许部分成功。三个数据源有两个超时剩下的一个仍然要能出结果并且在最终输出里明确标注哪个源缺失。这一点比追求 100% 完整重要得多。主管调度模式我踩过最大的坑是上下文膨胀。主管 Agent 跑十几轮之后自己的上下文里塞满了各个子 Agent 的原始输出。后来我改成子 Agent 只回传结构化结论原始输出留在子 Agent 自己的日志里主管需要细节时再按需拉取。上下文立刻降了一半。4.4 上下文传递的坑别传历史传契约我把上下文传递的经验浓缩成一句话Agent 之间传的是契约不是对话历史。契约包含四样任务目标、约束条件、输入数据、输出格式。对话历史里 90% 的内容对下游 Agent 都是噪声。还有个小技巧给每个子 Agent 的返回加一个confidence字段。主管 Agent 汇总时低置信度的结论单独标出来而不是和其他结论平起平坐。这个字段在最终输出的可信度评估上特别有用尤其是当你要把结果直接给人看的时候。5. 安全、测试与可观测性5.1 权限收敛Agent 不该拿万能钥匙Agent 安全这块我见到最多的错误是图省事给了一把万能凭证。这是绝对不能做的。我的三条原则是第一工具级最小权限。每个工具用独立的凭证只能访问它需要的那部分资源。查询工具就只给读权限别顺手给写。第二参数白名单。凡是涉及资源路径的参数都要在代码里做前缀校验不能直接拼进请求里。第三危险操作二次确认。删除、发送、支付这类不可逆动作必须显式走一次人工确认环节不能由 Agent 自主决定。还有个容易被忽略的点Agent 的日志本身就是敏感信息。它可能包含用户数据、内部接口地址、业务规则。日志的访问权限要单独控制保留期限要明确不要默认永久保留。5.2 测试流程分四层做别只测能不能跑通Agent 测试和传统软件测试差别很大因为输出是非确定性的。我的分层做法是这样单测层测 Skill 和工具。这层必须确定性输入固定输出就固定覆盖率要拉满。契约层测返回格式。用大量边界输入空数组、超长字符串、特殊字符去撞看契约校验会不会漏。路由层测意图识别。准备一个几百条的真实 query 集合标好正确答案算准确率和混淆矩阵。别只测 happy path把那些模棱两可的 query 全都放进去。端到端层测完整链路。这层用评估集跑重点看成功率、平均步数、平均耗时三个指标跟上一版做对比。注意端到端测试不要追求每次都完全一致。Agent 有随机性同一任务走的路可能不同只要结果达标就该算通过。把断言写在结果上不要写在过程上。路由层的测试集我建议持续积累。每次线上出现误判就把那条 query 加进测试集跑一轮回归。三个月下来这套测试集比任何评估框架都管用因为它测的是你的真实业务。5.3 日志与追踪出问题时能三分钟定位Agent 的调试难度在于链路长、环节多。我的做法是给每个任务生成一个trace_id从头到尾贯穿所有工具调用、路由决策、子 Agent 调用。日志格式固定成几列[2024-06-11 09:12:33] tracea8f2 step3 noderouter intentquery_inventory conf0.87 slots{sku:A1024} [2024-06-11 09:12:33] tracea8f2 step4 nodetool nameinventory_query codeOK cost412ms rows1 [2024-06-11 09:12:34] tracea8f2 step5 nodedecide actionfinal steps_used5 total1.8s有了这个格式排查就变成 grep 一把梭grep tracea8f2整条链路全出来。哪一步慢了、哪一步返回码不对、路由置信度多少一目了然。我强烈建议原型阶段就把这套日志建起来否则后面几十个并发任务一起来你会完全不知道发生了什么。另外提醒一句工具调用的耗时必须单独记录。很多性能问题不是模型慢是某个外部接口慢。不记耗时你只能靠猜。6. 常见问题排查速查把我在实际项目里遇到的高频问题整理成表遇到对应的现象可以直接查现象大概率原因排查动作Agent 说已完成但实际没调工具工具描述与用户意图不匹配检查工具 desc补上 examples工具选择总是挑错候选工具太多上下文被挤满加路由层收敛候选集到 5 个以内同一步反复调用同一工具返回没有明确的终止信号返回码里加 NOT_FOUND别返回空对象上下文几轮就爆工作记忆没做 token 预算改成按 token 裁剪 重要性打标子 Agent 输出质量骤降透传了主 Agent 的全量历史改成只传最小任务包偶发重复执行写操作没有幂等键每个写操作加业务唯一键整体延迟忽高忽低并行分支没设独立超时每个分支 wait_for 单独设时限路由准确率上不去测试集不覆盖模糊输入补边界样本标混淆矩阵看分布报错信息进上下文污染判断工具 message 字段透传了message 只进日志不进上下文长任务跑到一半莫名中断没有断点续跑机制每步落盘状态支持从最后一步恢复再说两个表里放不下、但我觉得很值得说的经验。第一个是**模型胡编工具参数**。这个问题的根因通常是参数 schema 写得太宽松比如type: object不写具体字段模型就只能猜。解决办法是把 schema 写到最细每个字段都写description和example必填项明确标注。实测这一招能把参数错误率降一大截。第二个是**任务中途异常回滚**。热词里经常出现安装中途回滚的问题本质是一样的多个步骤只完成了一半。我的做法是每一步执行前先写一条状态记录执行成功后标记完成。恢复的时候从最后一条未完成的记录继续而不是从头重来。对于有副作用的步骤一定要配合幂等键否则重跑就会重复执行。7. 学习路线与进阶方向如果你从零开始我建议的顺序是这样的。先把一个纯工具的 Agent 跑通——就是那种只有一个工具、一个循环的极简版本重点体会模型怎么决定调工具这件事。这一步别着急上框架手写一遍对理解帮助极大。然后加记忆层先做工作记忆的 token 预算再做长期检索。接着加路由层把工具数从 5 个逐步加到 30 个观察准确率的变化曲线这条曲线会让你对什么时候该拆分有直觉。再往后就是多 Agent 协作和 A2A 协议这部分建议先看协议规范文档把 Agent Card 的字段含义吃透再动手写。最后才是工业级 Harness 那一套——超时、重试、幂等、权限、可观测性。很多教程把顺序反过来讲先讲架构图再讲代码听着很有道理但落地时全是坑。关于面试我自己参与过几次 Agent 方向的面试高频问题基本集中在几个点工具调用的完整链路是怎么走的、上下文超限怎么处理、多 Agent 之间怎么保证信息不丢、怎么评估一个 Agent 的效果。这几个问题背后考的都是同一件事——你有没有真正处理过触达失败。只会讲框架 API 的答不好这类问题因为答案不在文档里在你踩过的坑里。工具选型上还有个现实建议别一次性把所有东西都换成最新最好的方案。模型换代、框架升级、协议改版这些变化的收益往往没有你想象的那么大而迁移成本是实打实的。我自己的节奏是一个新方案只有在解决了我当前明确痛点时才引入否则就先记在本子上等痛点真出现了再说。最后分享一个我自己一直在用的小习惯。每次 Agent 出了新问题我不急着改代码先把那条完整的 trace 日志抄到一个小本子上写清楚现象、根因、修法三行。攒到几十条之后你会发现很多问题其实是同一个模式的变体——比如缺少显式失败信号这一条我在完全不同的项目里反复遇到。把这些模式抽象出来就成了属于你自己的 Reach 经验这部分东西在任何一份官方文档里都找不到也只能靠自己一条一条攒出来。
