第一次把 Agent-Reach 完整跑通的那个晚上我盯着终端看了很久模型调用了我的搜索引擎工具、抓取了一个网页、然后把内容整理成了 Markdown 笔记全程没有我干预。这台电脑在替我干活——不是帮我优化文案而是真的伸出手去够到了外部世界。这是我一直想要的 AI Agent 形态。Agent-Reach 是我从零开始搭建的一个 AI Agent 开发项目核心目标一句话让大模型不只动嘴还能动手。所谓“Reach”就是“够得着”——够得着网络、文件系统、各类 API 和知识库。这篇东西算是我整个过程的工程复盘覆盖了 Agent 架构选型、工具与技能设计、沙箱安全、评测调试这些环节。不管你是被 LangChain 折腾过的开发者还是刚想入门 Agent 开发的小白应该都能在里面找到能直接抄作业的东西。1. 为什么我不直接用 LangChain而是从零搭建自己的 Agent1.1 聊天机器人不是 Agent动手和自主才是分水岭要弄清楚 Agent 是什么先得看它不是什么。我用了很久 ChatGPT 网页版觉得它很聪明但从来没觉得它像 Agent。区别就在两个动作上动手和自主。一个普通的 Chatbot你问它天气怎么样它只能凭训练数据里的常识回你。你要它“帮我查一下今天北京的天气然后根据是否下雨决定要不要带伞”它就卡壳了——它既没有实时数据来源也没有“查完再决策”的执行链。Agent 的本质是给模型装上闭环的执行能力感知看环境、读数据、决策下一步做什么、行动调用工具改环境、再感知。我更喜欢用一句大白话来概括Chatbot 是张嘴说话Agent 是说话算话。说话算话意味着模型要承担后果——它调用了一个删除命令、发了一封邮件、提交了一笔订单这些动作都会产生真实影响。这就是 Agent-Reach 立项时我给自己定的原则先承认它会犯错然后把容错、审计、权限都设计进系统里而不是让模型裸奔。从工程角度说这个差别会直接影响你的架构。Chatbot 只需要 prompt、模型、上下文窗口Agent 则需要工具注册表、执行循环、记忆管理、沙箱隔离、日志追踪。后面这些件件都是独立的子系统。所以我说入行 Agent 开发第一课不是学某个框架而是理解从 Chatbot 到 Agent 的这个“环境复杂度跃迁”。1.2 现成框架的三个劝退点抽象、升级、黑盒在决定从零写之前LangChain、Dify、CrewAI 这些框架我是真刀真枪用过的说白了也是踩完坑才走的。不是它们不好而是它们的强项和我的需求错位了。第一个劝退点是抽象层次太高。LangChain 里一层套一层Chain 套 Agent 套 Prompt Template 套 Output Parserdebug 的时候经常要拆四五层才能找到真正出问题的模块。模型输出不符合 JSON 倒是小事最怕的是框架在中间默默给你截断了字段、改写了 prompt 你都不知道。遇到诡异行为我第一反应是去翻框架源码翻着翻着就变成在跟框架作者的思路搏斗。第二个问题是升级不兼容。两三个月没跟进API 就变了为了跑通示例还得看文档考古。对一个要长期维护的项目来说这是致命的——我不可能每隔几个月陪框架重写一遍业务逻辑。社区里经常有人问“LangChain、Dify、CrewAI 到底哪个好”我的答案是如果你要快速做原型、验证想法Dify 这类低代码平台最快如果你已经确定要深度定制 Agent 行为哪个框架都会成为你的瓶颈。第三个问题更本质框架的封装给了你太多默认行为但 Agent 的核心价值恰恰在于可定制。我希望 Agent 的每一步都在我的掌控里工具调度按我的规则来、上下文裁剪按我的策略来、危险操作按我的审批流程来。用别人的框架这种掌控感很难拿到。所以 Agent-Reach 一开始就定了个原则框架可以不用但架构必须清晰循环自己写套件自己拼。1.3 先把术语对齐Agent、Harness、Tool、Skill 谁是谁圈子里术语满天飞很多人栽在概念没对齐上。这里我按 Agent-Reach 里的分工捋一遍后面的内容也都在这套术语上展开。概念角色类比Agent最上层的决策实体读任务、做规划、调工具、看结果餐厅厨师长Harness承载运行的骨架循环调度、解析模型输出、执行工具、管上下文、记日志后厨基础设施Tool最小能力单元一个函数、一个 API、一条命令单个厨具Skill多步组合技能按固定流程串联多个 Tool成熟菜谱Agent 是大脑负责“聪明”Harness 是骨架负责“可靠”。很多人争论“harness 和 agent 区别”一句话总结Agent 做决策Harness 保运转。模型是司机也好、厨师长也好没有车、没有灶台你有再多想法也使不出来反过来车和灶台再完备没人开、没人掌勺也出不了活。两边配合才是完整系统。Tool 是原子操作Skill 是由 Tool 串起来的流程。比如“将网页保存成 Markdown”这个 Skill内部就是“抓取页面 → 转格式 → 清理噪音 → 写入笔记”四步。模型不需要重新发明每一步只需要知道这个 Skill 能完成什么目标、需要什么输入。这套分层现在是 Agent 开发的主流范式Claude 的 Agent Skills、OpenAI Codex 里面的命令行工具本质都在往这个方向收敛。2. 动手前先把 Agent 架构拆明白Agent-Reach 的设计稿2.1 核心循环怎么落地Observe-Think-Act-ReflectAgent 能不能稳定干活关键看主循环是否写得干净。Agent-Reach 用的是广义的 ReAct 模式工程上我把它拆成四步Observe观察、Think思考、Act行动、Reflect反思。Observe 阶段Agent 收集所有可用的当前状态用户任务、系统提示、工具执行结果、记忆检索结果。Think 阶段模型基于这些信息输出规划它决定下一动作调哪个工具、传什么参数或者判断任务已完成、给出最终答案。Act 阶段就是 Harness 接管解析模型输出、执行工具、把结果打包。Reflect 阶段最容易被偷懒省掉但它恰恰是区分“笨重循环”和“可控循环”的分水岭。我的实现里把 Reflect 拆成两个时机。动作前做一次预检这个动作合理吗和上一轮结果矛盾吗有没有明显要撞墙的倾向动作后再做一次复盘上一步结果和期望一致吗还需要继续吗这两个钩子合起来就是“三连问”。最典型的场景是工具调错了参数没有 Reflect模型拿到报错后大概率继续用同样参数再撞一次墙有了 Reflect它会意识到“上一步失败原因可能是参数格式不对”从而换一种姿势重试。我做过的统计里加上 Reflect 之后同一批任务的成功率从 43% 提到 61%平均步骤数从 9.3 降到 7.8。别小看这个变化在多步骤任务里少撞一次墙就少烧一批 token。2.2 工具层怎么设计给 Agent 装“手”的三个要点给 Agent 装手不是简单地把函数列表塞进 prompt 就行。工具层设计有三件事必须做好描述、校验、容错。描述指的是工具说明。模型是靠自然语言理解工具的函数名、参数说明、示例写得越具体模型就越不容易理解偏。我在 Agent-Reach 里给每个工具维护一份 JSON Schemaname、description、parameters含类型、必填、枚举值限制外加一两个 few-shot 示例。这个 Schema 同时用于两件事拼进模型工具调用上下文以及在 Act 阶段做严格校验。换句话说模型就算脑补了一个不存在的参数在真正执行前也会被我拦下来而不是让错误一路传到副作用环节。这个习惯帮我在开发期少炸了很多次。容错比校验更隐蔽。工具是会和真实世界打交道的网络请求可能超时、文件可能不存在、API 接口可能限流。Agent-Reach 的运行策略是“工具永远不抛致命异常”——每个工具调用都返回结构化结果包里包含 ok/error 状态、业务数据、错误原因和建议重试参数。模型拿到结果后判断自己是换个姿势重试还是换一个工具而不是直接读到一行刺眼的 panic。这套约定看似枯燥却是一切后续自动化的地基。2.3 技能层怎么抽把“网页保存成 Markdown”做成可复用 SkillTool 是原子操作但真实任务很少只用一个工具。比如用户说“把某某网页保存成 Markdown 存到我的笔记库里”拆开得走四步抓网页、转 Markdown、清理导航噪音、写入笔记库。每步调用一个工具但组合逻辑完全可复用这就是 Skill 要解决的问题。Agent-Reach 的技能层用声明式配置来定义一个 YAML 文件描述 Skill 的名称、描述、适用场景、输入输出参数以及内部步骤序列。步骤之间允许数据传递比如第 2 步的输出直接作为第 3 步的输入。对“网页转 Markdown”这个 Skill 而言模型侧只需要看到一句话“把 URL 对应的网页保存为 Markdown 文件并自动分类到 Obsidian 对应目录。”具体怎么抓、怎么转、怎么分类模型完全不用关心。技能层的价值不止于“少几句提示”。很多人想做的“让 Agent 自动发一条小红书笔记”拆开无非也是选题生成、文案撰写、图片处理、发布接口调用完全可以做成一个 Skill想让 Agent 画图同样是写文案、生成图片、保存文件这几步的组合。技能层收得越多Agent 的复杂度就越低、可预测性就越高。但抽 Skill 有个关键判断什么该收、什么该留在模型自由发挥我的标准是三步以上的固定流程才值得抽。抽早了反而坏事——流程还没稳定就固化每次都要套模板灵活性大降。比较稳的节奏是先让模型自由调用跑两周把高频出现、流程稳定的步骤沉淀下来再固化。2.4 记忆层怎么分短期上下文与长期向量记忆的配合Agent 干活总有上下文放不下的那一天。Agent-Reach 当前把记忆拆成两层各管各的问题。短期记忆就是当前任务的上下文窗口。它的核心问题不是“存不下”而是“怎么裁”。我在项目里做了上下文压缩策略当 token 逼近上限时按重要程度逐级裁剪——工具返回的原始长文档最先压缩成摘要然后是历史对话的早期轮次最后才动正在执行的任务规划。这个顺序是反直觉的很多 Agent 一上来就裁早期对话结果后面的反思步骤失去了“之前试过什么”的信息重试变量常常就是从这丢的。长期记忆走的是向量库加结构化笔记双轨。向量库管语义检索用于匹配“类似任务以前怎么做的”结构化笔记管事实比如用户偏好、固定配置项。我目前把长期记忆直接落在 Obsidian 的库上用文件系统做持久化这样 Agent 写进去的每条记忆都是人可读的 Markdown随时能人工审计和修正。这也是那阵子 Hermes Agent 在 Obsidian 圈挺火的原因——把 Agent 记忆和人的知识库放在同一层透明度高太多。向量的相似度检索负责“模糊找”文件系统负责“精确存”两个配合起来记忆才不会变成黑盒。2.5 安全边界怎么划沙箱隔离、权限分级、审计日志Agent 一旦有了“动手”能力安全问题就绕不开。我的原则是任何时候都不要让模型裸奔在宿主环境里。Agent-Reach 的安全设计有三条线。第一条线是环境隔离。工具执行放进沙箱容器Agent 的代码在容器内跑宿主文件系统、网络端口默认不可达。我在项目里提供两种沙箱模式轻量模式用 Linux 用户命名空间加 seccomp 做进程级隔离适合开发期生产模式直接跑 Docker 容器给每个任务分配一次性容器任务结束销毁环境。用哪种模式取决于任务类型只读网页这种任务隔离要求不高为每个工具调用都起容器反而拖慢速度。第二条线是权限分级。我做了四级操作权限只读查询、普通写入、危险操作、高危操作。Agent 可以自由执行只读和普通写入危险操作比如删除文件、发邮件必须经过审批钩子高危操作比如安装系统包、修改系统权限默认禁止需要管理员手动放行。这个设计在开发期会被嫌麻烦但它能挡住“模型突然决定删除整个项目目录”这类事故。第三条线是审计日志。所有工具调用、参数、结果、由谁发起、属于哪个任务全部落日志出问题时能完整回放。我曾经排查过一个诡异 bug模型在第五轮突然天马行空调了一个不该调的工具。没有审计日志这种问题连定位都无从谈起。安全设计不是要限制 Agent 的能力而是给它的能力划一条可回退的护城河。3. 从零手写 Agent-Reach核心代码、工具注册与沙箱配置3.1 技术选型Rust 写核心、Python 写工具脚本的原因聊具体实现之前先交代技术栈Agent-Reach 的核心循环和 Harness 用 Rust 写工具层和实验脚本用 Python。很多人问为什么理由有三。第一性能与资源占用。Agent 任务往往要开几十上百个并发循环Rust 的 Tokio 异步运行时扛并发很稳内存占用比 Python 进程低一个量级。做长任务、批处理的时候这个成本差是实打实的。第二单二进制分发。一个编译产物丢到服务器就能跑不依赖 Python 环境和一长串 pip 依赖给非技术协作方部署时优势巨大。第三类型安全。工具参数校验、结构化输出解析这类逻辑用 Rust 的强类型写起来很难糊弄过去反而逼你把边界情况处理干净。代价也很明显Rust 开发速度比 Python 慢生态里的 Agent 库也还在早期。可以挑 HTTP、Serde JSON、Tokio 这些基础库自己搭积木但不要指望有一个像 LangChain 那样的全功能一站式 Agent 框架至少目前还没有。所以我的约定是算法骨架、工具框架这种“地基”用 Rust爬虫脚本、数据分析这种一次性逻辑用 Python两边优势互补。选型前做好心理准备你将享受到自由也将承担造轮子的时间成本。3.2 最小可用的 Agent 主循环长这样直接上一段简化核心代码展示 Agent-Reach 的主循环长什么样。错误处理和上下文压缩都被我省略了只保留骨架。// agent_loop.rs简化版 use serde_json::Value; async fn run_agent(task: String, tools: VecTool) - ResultValue, AgentError { let mut context Context::new(task); for step in 0..MAX_STEPS { // 1) Observe把模型决策需要的所有信息拼进上下文 let observation context.observe().await?; // 2) Think模型输出结构化的下一步动作JSON let plan: Value llm_think(observation, tools).await?; let action: Action serde_json::from_value(plan) .map_err(|_| AgentError::PlanParseFailed)?; // 任务完成直接返回最终输出 if action.is_final() { return Ok(action.output); } // 3) Reflect预检拦截明显不合理的动作 let check pre_flight(action, context.last_result()).await?; if check.should_abort() { return Err(AgentError::PlanAborted(check.reason)); } // 4) Act执行工具结果永远返回结构化错误而不是 panic let result match execute_tool(action, tools).await { Ok(res) ToolResult::ok(res), Err(err) ToolResult::err(err), }; context.record(action, result); // 5) Reflect复盘让模型意识到上一步结果与期望是否一致 let review post_land(result, context.history()).await?; context.record_review(review); } Err(AgentError::MaxStepsExceeded) }这段代码有几处容易被忽略的设计。首先模型输出直接被解析成 Action 结构而不是让模型自由发挥文本——我把输出格式约束得很死不然后续解析全是地雷。其次预检在 Act 之前跑能拦截一部分明显要撞墙的动作。最后ToolResult 永远不 panic错误也作为一种结果进入上下文让模型在下一轮里学习。跑起来之后你会发现现实任务的难点不在主循环而在工具结果的可用性。模型读到过长、过乱的工具输出很容易在下一轮思考中迷失位置。我建议在 Act 阶段加一个“结果压缩”钩子超过阈值的输出先自动摘要再记入上下文。这一步收益非常高模型失误率肉眼可见地下降。3.3 工具注册和 Skill 加载的落地实现工具注册我用 Rust 的宏加 trait 实现。每个工具实现一个 Tool trait声明自己的元数据和执行函数然后通过宏一次性注册进工具表。// tool.rs #[async_trait] pub trait Tool: Send Sync { fn metadata(self) - ToolMetadata; // 名称、描述、JSON Schema async fn run(self, args: Value) - ToolResult; } register_tool!(WebFetchTool); register_tool!(FileWriteTool); register_tool!(ShellExecTool);Skill 加载走的是目录约定项目skills/目录下每个子目录算一个 Skill里面有skill.yaml和可选的实现脚本。启动时扫描目录、解析配置、注册到技能表。这样新增一个 Skill 不需要改核心代码团队协作时其他人直接往目录里丢主程序完全无感。# skills/web2md/skill.yaml name: web2md description: 将 URL 对应的网页抓取并保存为 Markdown 文件 inputs: url: type: string required: true title: type: string required: false steps: - tool: web_fetch input_map: url: {url} - tool: html_to_markdown input_map: html: {steps[0].result} - tool: cleanup_noise input_map: markdown: {steps[1].result} - tool: obsidian_write input_map: title: {title | sanitize} content: {steps[2].result}关于 Skill 的输入映射我一开始踩过坑直接让步骤之间传递完整数据结果大 JSON 在上下文里占了几千 token。后来改成显式映射只有步骤声明需要的字段才会传过去等于给上下文做了一层按需裁剪。当你的 Skill 数量超过 20 个时还要做描述压缩——把低频技能的描述浓缩成一句话只让高频技能保留完整参数说明这是控制 prompt 长度最有效的办法之一。3.4 Token 与上下文管理三个必须设置的参数Agent 项目绕不开 token 这个话题。光知道 token 是计费单位没用你得把它当运行时资源来管理。我在 Agent-Reach 里设了三个关键参数颜值不高但个个保命。参数作用我的设置参考max_tokens_per_step限制单步思考输出长度简单工具调用 1024复杂规划 2048context_budget上下文预算触发压缩的提醒值视模型窗口而定我常用 12ktoken_usage_ratio使用率阈值超过后不再接新任务默认 80%第一个参数防止模型输出过长的“内心戏”。大模型思考过程有时特别啰嗦不设上限它可能一口气输出上万 token 的内心独白。第二个参数解决上下文瘦身问题触发后按优先级压缩工具结果、历史早期轮次、任务规划一层层降级。核心思路是保住“当前正在执行的任务主线”和“关键工具结果”这两个丢了 Agent 会立刻降智。第三个参数是我用一次惨痛教训换来的。某次并发任务没设阈值上下文被塞爆模型开始胡言乱语一批任务全废。设了之后虽然偶尔任务变慢但行为变得可预测。顺便解答一个常见疑问“AI agent token 是什么意思”在 Agent 语境下token 不只是计费单位更是决策和记忆的载体——模型每一轮思考、每个工具参数、每条历史记录都换算成 tokentoken 上限直接决定 Agent 能“看多远、想多深”。把 token 当作随时可能耗尽的内存Agent 架构就会自然地往压缩、摘要、缓存方向设计。3.5 沙箱落地Docker 和用户命名空间怎么选沙箱具体怎么搭我给 Agent-Reach 写了两种模式各有清晰的适用场景。轻量模式基于 Linux 的用户命名空间加 seccomp profile。进程以非 root 用户运行在隔离命名空间里禁止 mount、禁止绑定网络端口、限制文件系统访问白名单。优点是毫秒级开销直接在宿主机上启动适合大量低频工具调用和日常开发调试。缺点是隔离强度有限如果模型被诱导执行复杂的内核级攻击理论上存在逃逸风险。重量模式直接上 Docker给每个任务起一个一次性容器。容器内只有任务需要的环境和工具网络策略通过 bridge 控制默认只放行必要域名。任务结束容器直接销毁痕迹清零。性能代价明显每次起容器要几百毫秒不等但换来更强的隔离和快照能力。我的实践建议对外提供服务、Agent 会接触外部输入时必须上重量模式纯本地个人使用比如让 Agent 整理笔记轻量模式足够否则每步都等容器起来体验会很糟糕。沙箱这件事我还要强调一个反直觉的经验沙箱隔离的不是恶意模型而是失控行为。大模型不是坏它是不可预知。今天测试好好的工具组合明天换一个问题就可能调出你完全没想到的参数组合。沙箱的作用就是把这层不可预知关在笼子里。4. 跑通不是终点Agent 评测、调试与安全审查4.1 Agent 评测集从零搭建除了成功率还要看三个指标Agent 跟普通软件有个根本区别它没有固定的正确输出只有“任务是否完成”。所以 Agent 评测集必须自己建而且应该往“任务”而非“问答”方向设计。我建议从三个维度收集任务样例。第一是核心能力覆盖每一个 Tool、Skill 至少要有一条对应任务。第二是异常路径模拟参数缺失、外部服务返回错误、中途打断这些情况看 Agent 会不会死循环或误重试。第三是边界场景超长输入、模糊指令、互相矛盾的需求。每条任务写清楚输入、期望结果、可接受的成功标准——注意是标准而不是唯一答案因为 Agent 完成任务允许多种路径。指标方面成功率只是起点。每次回归我都会同时统计三个数平均步骤数越少代表效率越高平均 token 消耗优化空间所在任务总时长含工具调用耗时能暴露沙箱或网络瓶颈。三个数合起来才能反映 Agent 的“质量”而不只是“能不能成”。另外强烈建议把评测跑进 CI每次改主循环、加新工具都自动跑一轮防止回归。Agent 项目里最常出现的情况就是“修好一个 bug另一个任务莫名开始失败”没有回归测试兜底会很痛苦。4.2 高频报错排查Agent execution terminated due to error 怎么定位开发期最常见的报错就是Agent execution terminated due to error一个特别笼统的终止信息。我遇到它的排查顺序是固定的先看审计日志里最后几轮工具调用99% 的情况是某个工具返回了意外错误格式再看是不是触发了 Reflect 预检的拦截最后才怀疑模型输出解析失败。现象常见根因排查思路Agent execution terminated due to error某个工具返回非预期错误格式先查审计日志最后几轮工具调用模型反复调用同一工具并失败工具错误信息太笼统模型无法区分错误类型给错误信息加分类和建议重试姿势模型输出无法解析为 JSON思考过程和输出混在一起用宽容解析器提取 JSON失败后回喂错误并重试任务中途上下文被塞爆工具结果过长、未做压缩设置 context_budget超限先压缩工具结果模型输出解析失败是另一个高频坑。模型偶尔不按 JSON 输出尤其让它先想再写的时候。我的对策是两层第一层是宽容解析器尝试从文本里提取 JSON 片段、修正轻微逗号错误第二层是重试机制解析失败后把错误信息喂回模型要求重新输出合法 JSON。实测下来重试成功率很高但必须设置重试上限否则会形成无限循环烧钱。最迷惑人的问题是工具循环死锁Agent 反复调同一个工具拿到失败后不换策略无脑重试直到步数上限。根源往往是工具错误信息太笼统模型分辨不出“参数错误”和“网络超时”是两类问题。解法是给工具错误分类并给出重试建议同时配合 Reflect 三连问让模型真正意识到“这条路走不通得换一条”。4.3 值得参考的对象Claude Agent Skills、Codex、Cline、Hermes 的启发做 Agent 开发一直盯着别人的项目看特别有收获。我把这段时间研究过的几个对象整理一下不是推荐你去抄而是拆解它们各自解决了什么问题。Claude 的 Agent Skills 是我认为当前落地最扎实的范式之一。它把可复用的技能包做成清晰的文件结构技能说明、指令、模板、示例、资源统统打包。Agent 执行任务时按需加载对应技能而不是把全部技能塞进上下文。这个“按需加载”思路我直接搬进了 Agent-Reach 的 Skill 层设计里收益很大。OpenAI Codex 是很好的 Harness 范本。它本质是一个跑在终端里的命令行编码 Agent把工具调用封装成命令行的自然延伸。最值得学习的是它和开发环境的交互密度模型随时能看到编译报错、测试输出、diff 结果再决定下一步。这种紧密反馈环对写代码类任务特别有效也提醒我工具结果的回传密度会直接影响模型的判断质量。Cline 和 Hermes Agent 则是社区工具的代表。Cline 的配置体系做得很细模型能力、权限级别、MCP 服务都能灵活组合Hermes Agent 尤其适合研究 Agent 与 Obsidian 工作台的结合——它把技能、笔记、工作流放在可视化界面里让你直观看到 Agent 每一步到底调了什么工具、改了什么文件对调试 Agent 的“黑盒”状态很有帮助。研究这些项目的原则是别照搬拆出对自己架构有启发的那一两块然后用自己的方式实现。4.4 外部 API 调用前的最后一道闸门策略引擎与审计快照第 2.5 节讲了架构层面的安全设计这里补一个实操层面的细节外部 API 调用前Harness 必须能拦截并强制走审批。因为 Agent 太容易“擅自行动”了——它可能为了完成任务直接去调一个会产生费用的接口、给第三方发送请求或者在没确认的情况下修改线上配置。我在 Agent-Reach 里实现了一个 Policy 引擎每个工具调用在正式执行前都会过一遍策略表。每条规则描述“什么条件下做什么操作需要什么级别的审批”调外部付费 API 需要二次确认写入非白名单路径需要确认删除操作一律禁止。这个引擎是纯规则配置不依赖模型判断因为安全决策不该交给概率模型拍板。审计日志在这个环节再次登场而且我建议配一个“快照”功能。被拦截或高风险的操作把当时的上下文、工具参数、模型推理片段一起存下来。以后回溯“为什么它会想这么做”时这些材料能帮你改进 prompt、调整工具描述从根上减少危险意图。安全检查不是要把 Agent 锁死而是给它一个隔离试错的缓冲区——这是 Agent 逐步变得可靠的前提。5. 多 Agent 协作与后续扩展让 Agent 真正“够得着”更多5.1 多 Agent 编排supervisor-worker 模式怎么落地单 Agent 做到一定规模你自然想拆成多 Agent。原因很朴素一个 Agent 的上下文就那么大把所有能力塞给一个 Agentprompt 臃肿、token 浪费、决策质量下降。拆开以后各管一摊效果反而好。Agent-Reach 的多 Agent 编排用的是经典 supervisor-worker 模式一个调度 Agent 负责任务分解、分配和结果汇总一组工作 Agent 各负责一个具体技能域。调度 Agent 先写一份简短执行计划然后把子任务发给匹配的工作 Agent收集结果后做整合输出。这个模式的优点是结构清晰、易扩展缺点是调度 Agent 本身容易成为瓶颈——它的上下文要装下所有子任务的结果摘要任务多时压力很大。我踩过的一个坑是结果格式没定义清楚。如果工作 Agent 返回一堆自由发挥的自然语言调度 Agent 就不得不靠提示词去猜整合质量大打折扣。解决方案是给每个工作 Agent 定义输出 schema成功/失败状态、关键数据字段、遗留问题列表。调度 Agent 拿到的是结构化 JSON而不是一篇小作文。这个细节直接决定多 Agent 协作的上限。5.2 下一步计划浏览器自动化、向量记忆与开放评测集项目目前的路线图上有三件事。第一件是把长期记忆从 Obsidian 文件库升级到真正的向量数据库并加入自动摘要能力——文件库虽然人可读但检索效率和语义匹配都还不够。第二件是完善 Harness 的可观测性给每一步工具调用挂上 trace 可视化让非技术人员也能看懂 Agent 在做什么。第三件是扩大评测集规模目前两百多条任务还是太少我打算引入社区共建评测集的方式开放一些典型任务模板让更多人一起覆盖边界场景。工具层面我最想补的是浏览器自动化能力让 Agent 能真正“看”网页操作界面而不只是通过 API 抓数据。这会把 Agent 的触达范围再往外推一步——真正意义上的 reach everything。至于多 Agent 之间的通信协议我也考虑过。基于 HTTP 的回调会比较重计划换成消息队列让每个 worker 可以异步消费任务调度 Agent 不必一直轮询等结果。这个改进预计能把并行任务的吞吐再提一两倍。5.3 给新入坑的同学Agent 开发学习路线怎么排经常有人问我 Agent 学习路线怎么走这里按我自己的复盘给一条实践过的路径。第一阶段先把基础概念打通prompt 工程、工具调用、RAG、上下文窗口这些都是后续的地基。建议选一个现成 harness 把最小 Demo 跑通先感受“模型调工具”是个什么手感。第二阶段开始拆架构自己写一个简化版的主循环重点理解模型输出怎么变成工具调用、工具结果怎么回灌上下文。第三阶段再做专项深挖想搞生产化就学沙箱、权限、审计想搞能力扩展就学 Skill 设计、记忆管理想搞效率就做评测集、看板指标。面试里高频考的点也基本落在这几条线上ReAct 的原理和局限、工具调用的格式设计、上下文管理策略、Agent 与 RAG 的异同、评测集怎么构建、多 Agent 如何编排。与其背概念不如把一个最小 Agent 亲手写出来把这些环节都走一遍比什么速成教程都管用。Agent 这个方向的门槛不在某一个算法而在你能不能把模型、工具、状态、安全这些碎片高效地编排起来——这是纯工程能力练得越多手感越扎实。Agent-Reach 从立项到现在我做过最大的改动是砍掉第一版里所有花哨的东西复杂的记忆网络、华丽的 UI、一长串预置技能全部下架换成一个干净的主循环和十来个稳定工具。事实证明这套极简版才是能够持续演化的核心。项目走到这里我最深的体会是Agent 开发的第一性原理不是“让模型更聪明”而是“给聪明一个可靠的执行环境”。模型负责天马行空Harness 负责脚踏实地两边都不缺位Agent 才能真的干出活。如果你也准备动手折腾自己的 Agent我建议从最小闭环开始一个主循环、三个工具、一条评测用例。跑通之后再一点一点加能力。别看市面上的框架和教程眼花缭乱真正决定你的 Agent 能不能用的永远是那些地基环节可靠的循环、清晰的工具协议、严格的沙箱边界。先把这些夯实后面自然水到渠成。