Agent 开发这件事过去半年给我的最大感受是大家聊的好像都是Agent但做的事情完全不是一回事。有人在调 Prompt 套壳有人在搞多智能体编排有人在给 Agent 加记忆和工具还有人被并发和安全性折腾得睡不着觉。前阵子团队复盘项目时我们发现真正让 Agent 从玩具变成生产力工具的不是模型选得多强而是把触达这件事想清楚了——Agent 能触达哪些工具、触达多少上下文、触达什么级别的稳定性。这就是我把这篇总结叫 Agent-Reach 的原因一个 Agent 的价值上限取决于它能安全、稳定、高效地触达真实业务场景的深度和广度。这篇文章不是从入门到放弃的教程也不是单点功能的流水账。我想把过去在 Agent 开发里踩过的坑、验证过的架构、反复改过的设计按定义 → 架构 → 技能 → 工程化 → 学习路径这条线完整梳理一遍。无论你是刚准备入行、正在做技术选型还是已经在生产环境里被 Agent 折磨过这篇都能给你一些可以直接落地的参考。1. Agent 到底是什么先分清聊天机器人和能干活的主体很多新手上来就问Agent 是什么但真正需要先厘清的不是定义而是你想要的 Agent 属于哪一层。1.1 从模型能力到任务闭环Agent 的分层逻辑一句话版本Agent 大模型 规划能力 工具调用 记忆 环境反馈。但这句话说了等于没说。我更愿意把 Agent 拆成三个层级L1 对话代理模型接收指令生成文本回复。没有工具调用没有外部状态。市面上大部分AI 助手其实停留在这层。L2 工具代理模型能调用 API、执行代码、读写文件。典型特征是感知 → 决策 → 行动 → 观察的循环也就是常说的 ReAct 模式。L3 自主主体具备长期记忆、多步规划、跨系统协作能力能在无人干预的情况下完成一个多阶段目标。多 Agent 系统、复杂工作流编排通常落在这层。认清层级非常关键。因为不同层级的技术选型完全不同。如果你只是想让 Agent 帮忙写周报那 L1 就够了根本不需要上框架如果你要做Agent 自动把网页转成 Markdown 并存入知识库那就必须至少到 L2开始考虑工具定义、权限控制、错误恢复这些事。1.2 单 Agent 还是多 Agent热词背后的真实边界多 Agent是热度最高的词之一但我在实际项目里的结论是能用单 Agent 解决的事绝不上多 Agent。多 Agent 引入的复杂度是线性甚至指数级上升的——你要处理 Agent 间的通信协议、任务分配策略、死锁问题还要为每个子 Agent 单独设计上下文窗口。什么场景才值得上多 Agent我这边验证过比较靠谱的几种场景单 Agent 表现多 Agent 价值调研写作长文中途容易丢失早期上下文研究员和写手分工各自维护窄上下文代码生成测试生成的测试和代码容易互相污染开发 Agent 和测试 Agent 独立迭代客服工单处理一次对话里多个意图互相干扰分诊 Agent、处理 Agent、回访 Agent 各司其职一个判断标准供参考如果任务的多个子步骤需要访问完全不同的外部系统且每个系统都有复杂的内部状态多 Agent 才有意义。否则一个 Agent 加几把好用的工具性价比高得多。这也是为什么现在主流的 Agent 框架——比如 LangGraph、AutoGen、CrewAI——都在做可控的编排而不是完全放飞的多 Agent 自治。1.3 Agent 框架并不是必须的热词里有一堆框架Spring AI、Pi Agent、Cline Agent、Hermes Agent、Rust 写的 Agent……我见过太多人把先选个框架当成第一步结果被框架绑定遇到问题还得去读框架源码。我的建议是第一次做 Demo直接用模型原生 API 一个工具调用循环手写 200 行代码跑通。这样你能真正理解 Agent 的底层机制。做生产系统再上框架。框架解决的是状态管理、持久化、并发控制这些工程问题而不是帮你想清楚逻辑。做边缘实验比如语音 Agent、本地笔记 Agent、用 Rust 追求极致性能可以考虑轻量方案甚至自己写编排层。我见过最成功的几个 Agent 项目反而不是用了多牛的框架而是把模型、工具、记忆这三块的边界切得非常干净。这就像写代码架构清晰比用什么库更重要。2. Agent 架构的核心决策Harness、编排模式与记忆设计架构选型这一块是 Sekai 上讨论最多、也最容易混淆的区域。我先把几个高频热词拉出来对比再逐个讲透。2.1 Harness 和 Agent 到底什么关系很多人搜harness 和 agent 区别是因为在 Claude Agent SDK 这类项目里老看到这两个词。用大白话讲Agent是大脑负责推理、决策、决定下一步做什么。Harness是身体和骨架负责提供 Agent 生存所需的基础设施——模型接口、工具注册表、上下文管理、执行循环、错误处理、安全边界。类比一下Agent 是司机Harness 是汽车。司机的水平决定了开得好不好但车的底盘、刹车、油箱这些是 Harness 提供的。你不可能让一个司机在没有车的情况下去跑长途。实际开发中Harness 承担了很多看不见的脏活循环控制管理模型输出工具调用参数 → 执行工具 → 把结果返回给模型这个循环何时终止。没有好的终止策略Agent 会在一次简单任务里调用几十次工具白白烧掉 token。上下文窗口压缩工具返回结果往往很长比如读取一个大文件、网页抓取正文Harness 要做摘要或截断防止上下文爆炸。工具调用的 Schema 校验模型偶尔会输出格式错误的工具调用参数一个好的 Harness 不是简单报错而是尝试修复或重试。所以当你在评估一个 Agent 框架时不要只看它支持多少个模型而要仔细看它的 Harness 设计好不好——终止策略、上下文管理、错误恢复这才是决定生产可用性的关键。2.2 三种主流架构范式ReAct、Plan-and-Execute、GraphReAct推理 行动每一步都让模型先想再做适合需要实时反馈的任务比如网页操作、代码调试。优点是灵活缺点是 token 开销大、容易出现绕圈子。Plan-and-Execute先规划后执行Agent 先产出一份完整的计划然后按计划逐步执行。适合目标明确、步骤可预测的任务比如生成报告并发送邮件。优点是可控性强、token 开销低缺点是遇到计划外情况时灵活性差。Graph图编排把 Agent 流程建模为有向图节点是工具或子任务边是条件跳转。适合复杂业务逻辑比如客服系统需要条件分诊。LangGraph 是这个范式的代表。我在生产项目里最喜欢的组合是Plan-and-Execute Graph 的折中先用 Graph 定义好主干流程和关键分支再在叶子节点上用 ReAct 模式让 Agent 灵活处理细节。这样既不会失控也不会死板。2.3 Agent 记忆短期、长期、外部记忆的取舍Agent 记忆在热词里出现频率极高但很多项目的记忆设计是先加后想为什么加。记忆至少要分三层短期记忆上下文窗口最简单直接。但每个模型都有窗口上限超过就忘了——这就是上下文爆炸问题。实用做法是在中间步骤把工具结果做摘要后再返回给模型而不是原样塞回去。长期记忆对话历史/用户偏好需要持久化。可以存到数据库、向量库或者简单的 JSON 文件。关键是要有明确的写入策略——不是每轮对话都存而是当模型判定这是值得记住的信息时才写入。我在项目里用的策略是加一个独立的记忆提取步骤在任务结束后由模型输出结构化记忆条目再由程序写入存储。外部记忆知识库/文档库一般搭配 RAG 使用。但我的实践体会是RAG 的瓶颈不在向量检索本身而在**什么时候该去检索和检索结果怎么进入上下文**。所以我会在 Agent 的工具列表里单独定义一个search_knowledge_base(query)工具让模型自己决定什么时候查。这样比每次都把全部知识塞进去省太多 token。2.4 工具调用与沙箱边界从热词agent 沙箱说起搜索词里有agent 沙箱这是所有做生产级 Agent 的人迟早要面对的问题。Agent 一旦有了工具调用能力就有能力访问文件系统、发 HTTP 请求、执行 shell 命令。这时候安全问题就不是可选项了。我在项目里把工具分成三个信任等级信任等级工具示例处理方式只读读文件、搜索网页、查询数据库可以直接执行但记录日志受限写生成 Markdown、写临时文件、发内部消息限制路径/目标需要审批流高危执行 Shell 命令、删除文件、转账、发布内容默认拒绝人工确认后放行沙箱到这里才真正有意义——不是把所有工具都装进沙箱而是把不同信任等级的工具放进不同安全边界。我自己的做法是优先用 Docker 隔离 Agent 的文件系统和网络环境同时给高危工具接一个人工审批接口。这样即使模型被诱导输出恶意工具调用也最多触达一个只读环境造成不了实质破坏。3. Skills 开发实操让 Agent 真正会干活的核心技术热词里反复出现 Agent Skill、Claude Agent Skills、skill 教程这确实是 Agent 开发里最值钱的部分。一个没有技能的 Agent 就像只有驾照没有车的司机。这一章我从原理到实战讲透。3.1 Skill 与 Function Calling、Plugin 到底有啥区别Function Calling函数调用模型通过结构化输出触发后端函数。通常是单步的——模型说我要调用这个函数然后函数执行结果返回。粒度细、偏底层。Plugin插件一组预先定义好的函数集合通常带 UI 配置。偏用户交互。Skill技能Agent 按需加载的完整行为包不仅包含能调用什么函数还包含什么场景用这个技能使用步骤是什么有哪些注意事项。我用一个类比Function Calling 是打电话叫外卖你告诉老板要什么老板给你送Skill 是一整套家庭聚餐方案包括买菜清单、做菜步骤、餐桌布置、上菜顺序。Agent 遇到吃饭场景时就加载聚餐 Skill按里面的指导一步步执行。Skill 的核心价值是让 Agent 具备程序性知识而不仅仅是指令响应。3.2 实战写一个把网页保存成 Markdown的 Skill热词里有一条agent 将网页保存成markdown 的 skill我用这个例子完整演示 Skill 的开发流程。假设目标用户给一个 URLAgent 自动抓取网页正文并转成 Markdown 文件存入本地指定目录。第一步定义 Skill 的元信息和触发场景每个 Skill 需要一个清晰的描述让模型能判断当前任务该不该加载这个技能。我的 SKILL.md 开头是这样的--- name: webpage_to_markdown description: 将任意 URL 的网页正文提取并转换为 Markdown 格式保存到本地目录。 适用于用户给出一个网页链接并要求保存内容、整理成笔记、生成文档素材等场景。 不适用于需要登录认证的页面、SPA 动态渲染的页面会有部分缺失。 ---这段描述里最关键的是**不适用于**——这能极大减少模型在错误场景加载技能的概率。我见过很多 Skill 设计失败就是因为描述写得太宽泛导致模型经常加载错技能。第二步提供明确的执行指导Procedures## 执行步骤 1. 使用 fetch_webpage 工具获取 URL 的 HTML 内容。 2. 使用 extract_main_content 工具提取正文区域优先尝试 article 标签若无则回退到 main 或正文密度分析。 3. 将正文 HTML 转换为 Markdown - 标题映射h1-h6 → # ~ ###### - 列表映射ul/ol → - / 1. 2. 3. - 链接保留a href → [text](href) - 图片引用img src →  - 代码块pre/code → 带语言标注的 代码块 4. 清理冗余移除导航、侧边栏、页脚、广告位。 5. 将 Markdown 保存到 ./notes/{URL 的域名}/{日期}_{标题}.md并返回文件路径。 ## 注意事项 - 如果网页编码不是 UTF-8需要先进行编码转换。 - 如果提取出的正文长度小于 200 字判定为页面异常向用户确认是否继续。 - 保存前对文件名做安全处理去掉 / : * ? | 等非法字符。这个 Skill 我实际跑下来最大的体会是步骤写得越具体模型执行越稳定。如果你只写把网页转成 Markdown模型会自己发明一套流程有时候好用有时候就翻车。把步骤、错误处理、边界条件都写清楚相当于把老师傅的经验喂给了 Agent。第三步测试 Skill热词里有agent skills测试我自己做 Skill 测试的清单正常页面测试一个标准博客文章页内容应完整保留。复杂页面测试包含表格、代码块、嵌套列表的页面。异常测试404 页面、JS 渲染页面、空页面、超大页面。重复执行测试同一个 Skill 跑 10 次观察输出是否稳定。我强烈建议给每个 Skill 建一个独立测试集配上自动化脚本。Skill 质量的核心指标不是能跑通而是在遇到边界情况时不崩。3.3 多 Skill 的管理按需加载而不是全量注入当 Agent 的技能数量超过 10 个之后就出现一个经典问题技能描述本身也在抢占上下文窗口而且技能太多会让模型选择困难。我的解法是把所有 Skill 的元信息名称 一句话描述存成一个索引Agent 先看索引再决定加载哪个 Skill 的完整内容。在索引里加场景标签比如网页处理数据分析文档生成模型可以按标签筛选。每个 Skill 的完整文档只在被选中时才加载进上下文。这套方案在项目里效果不错上下文省了不少技能选择的准确率也上升了。这其实就是借鉴了 RAG 的思路——技能文档不是常驻内存而是按需检索。我把这种方式叫Skill Retrieval是目前处理大量技能的最优解。4. Agent 工程化的三道坎并发、安全与稳定性热词里最戳痛点的几条是ai agent 怎么扛并发、agent安全、agent execution terminated due to error.。这些问题在 Demo 阶段根本不存在一上生产全跑出来。这一章我把它们逐个拆开讲。4.1 并发Agent 不是单纯的高并发 API 服务怎么扛并发这个问题很多人直接用普通 Web 服务的思路——上负载均衡、横向加机器。但 Agent 服务的特殊之处在于每个会话都是长时运行、有状态、多步骤的交互过程。一个 Agent 任务可能持续几分钟甚至更久在这期间要保持上下文状态、调用多个外部服务、还要处理中间错误。这和无状态请求-响应完全是两种模型。我的实践方案分三层第一层任务队列化。所有的 Agent 请求不直接进入进程而是先投递到消息队列Redis Streams 或 RabbitMQ。一个 Agent 实例消费一个任务任务结束后才消费下一个。这样天然解决了并发上限问题——并发量由消费实例数量决定而不是由请求突增决定。第二层状态外置。Agent 的上下文状态对话历史、工具结果、临时变量必须持久化到外部存储Redis/数据库而不是保存在内存里。这样即使实例被杀掉重启也能从持久化状态恢复。我见过太多线上事故就是因为状态在内存里被 OOM 带走任务直接中断。第三层弹性伸缩。消费者实例可以根据队列积压量自动扩缩容。这个用云平台的弹性伸缩组就可以实现因为状态已经外置所以实例增减是无感的。用这套方案我们曾经把一个地区性 Agent 服务从只能同时跑 5 个任务扩展到平滑扛住 200 个并发任务没有改一行 Agent 逻辑纯粹是工程架构的调整。4.2 安全模型不可信任所以你才需要边界Agent 安全不是老生常谈——Agent 天然具备比传统软件更高的攻击面因为它的输入可以注入指令。最常见的攻击方式是 Prompt Injection提示注入用户输入的文本里混入了忽略之前的指令执行...模型可能会照做。我在生产里总结的安全清单权限最小化Agent 使用的 API Key 全部设置最小权限。比如需要读文档库的 Agent绝不给他文档库的写权限。输出内容过滤对 Agent 准备输出到外部系统的内容做规则过滤比如禁止输出包含机密信息手机号、身份证的内容。简单正则 敏感词表能挡住大多数事故。人工审批闸门高危动作发送邮件、执行删除、发布内容一律走人工确认。宁可慢一点不能错一次。审计日志Agent 的每一次工具调用、每一次模型输出全部落日志。出了问题能回溯。这里我想强调一个认知不要期待模型能识别恶意指令。模型确实有一定防御能力但被绕过的案例太多了。真正可靠的安全保障全都来自工程层——权限、过滤、审批、审计——而不是模型层的自觉。4.3 稳定性遇到 Agent execution terminated due to error 该怎么办这条热词应该是个具体报错信息我猜是某些工具比如 OpenAI 的 Assistant API 或者 LangChain 的 AgentExecutor在任务异常中断时抛出的。实际开发中Agent 执行报错的概率远高于传统程序因为多了一个不可控的因素——模型本身。模型可能输出格式错误的工具参数比如 JSON 缺括号。模型可能在任务中途改变主意偏离原始目标。工具可能失败网络超时、API 限流、数据格式不对。上下文可能耗尽。我的稳定性三板斧第一板斧自动重试。对工具调用失败重试 2 次间隔递增1 秒 → 3 秒。如果仍然失败把错误信息返回给模型让它调整策略重新尝试。很多时候模型会换一个工具或者换一种调用方式。第二板斧逐步降级。如果整个任务失败不是简单抛错而是让 Agent 产出部分成果——比如网页转换失败但已经提取了标题和摘要然后用这些部分成果生成一份带错误标注的报告。至少比什么都没有好。第三板斧兜底终止。设置最大工具调用次数比如 20 次和最大执行时长比如 5 分钟超过就强制终止。防的是 Agent 进入死循环——不断调用工具但始终无法完成任务。这类情况一旦发生正确的选择往往就是及时止损。5. Agent 的学习路径与能力评测从入门到精通的路线图最后是热词里的大量学习相关词条agent开发学习路线、agent学习、agent面试题、agent评测集构建。我结合自己带过几个新人的经验整理一条我认可的学习路径。5.1 学习路线分四个阶段的进阶阶段一跑通最小闭环2-3 周不碰框架。直接用模型 API写一个最简单的工具调用循环定义 2 个工具比如查天气、做计算让模型根据用户输入决定是否调用工具然后循环执行。这一步的核心目标是理解 ReAct 模式的本质——感知、决策、行动、观察这四个步骤循环。阶段二掌握生态工具3-4 周在理解底层机制之后再开始玩框架。从 LangChain / LangGraph 入手因为它最主流、资料最多。重点掌握工具定义方式、状态管理、记忆插件的原理、Flow 图的编排能力。同时开始接触Agent Skills的概念如果用的是 Claude SDK 就学它的 Skill 体系用别的框架就学它对应的技能/工具管理方式。阶段三工程化能力4-6 周开始处理生产问题把 Agent 包装成服务、接消息队列扛并发、做状态持久化、加安全策略。这个阶段我不能光靠教程一定要真实跑一个小项目——比如做个自动搜集行业资讯并生成每日简报的 Agent中间要处理网页抓取、内容摘要、定时调度、失败重试这些全是工程问题。阶段四系统设计与评测长期到了这个阶段你基本具备独立设计 Agent 系统的能力。接下来的深耕方向是评测体系如何衡量一个 Agent 做得好不好不能只看能不能完成任务还要看 token 消耗、工具调用次数、失败率、用户满意度。评测集构建针对你的业务场景收集几十甚至上百个典型的用户任务标注预期结果和关键步骤形成回归评测集。每次改版都跑一遍防止引入新问题。复杂架构多 Agent 协同、人机协同Human-in-the-loop、跨系统集成。5.2 评测集构建很多人忽略但极其重要的环节搜索词里agent评测集构建我很想多说几句。做 Agent 评测和做模型评测不太一样。模型评测关心的是回答质量Agent 评测关心的是任务完成度。我建议每个正式 Agent 项目都要配一个评测集结构如下维度说明示例任务成功率任务是否完成网页转 Markdown 是否生成文件过程合理性工具调用路径是否高效是否调用了多余工具、绕远路Token 成本完成任务的消耗单任务 token 数是否在预算内错误恢复遇错后能否自我修正网页抓取失败后是否能换方案边界处理极端场景的表现空 URL、超大网页、无正文页面评测集不需要很大30-50 条高质量任务足矣。关键是每条任务都要有明确的判定标准。我见过最有效的评测方式是人工评分 自动指标结合自动指标管成功率、token 消耗人工评分管结果是否符合预期。这项工作看起来繁琐但没有评测集的 Agent 项目永远在靠感觉做优化。有了评测集每次改一个参数、换一个模型都能定量看到效果变化。这是从Demo 开发者走向专业工程师的分水岭。5.3 从热词里看趋势后端语言、前端框架与生态繁荣热词里出现了 Rust 语言写 Agent、Spring AI、Kotlin JVM 跑通 Agent、Hermes Agent 第三方工作台等词条。这反映出一个明显的趋势Agent 开发正在从 Python 一家独大走向多语言生态繁荣。Rust 写 Agent追求极致的性能和内存安全适合对延迟敏感、资源受限的边缘场景。Spring AI让 Java 生态的老牌团队能用熟悉的 Spring Boot 接上 Agent企业级集成成本大大降低。Kotlin JVM在 Android 或服务端场景跑通 Agent说明轻量 Agent 已能满足移动端需求。Hermes Agent挂在 Obsidian 这类第三方工作台上体现了Agent 融入个人知识管理的实用需求。我的观点是不要被语言/框架的选择绑住手脚。Agent 的核心机制模型 API 交互、工具调用循环、状态管理在所有语言里都是想通的。真正值钱的是你对这些机制的深入理解以及你在工程实践里踩过的坑。换一套技术栈花两周适应语法核心能力完全迁移。6. 写在最后Agent 开发中最容易被低估的三件事文章到这里核心内容已经讲完了。最后我想分享三个在真实项目里反复被验证的体会算是我个人踩过坑换来的经验。第一上下文管理比模型选择更重要。很多团队一上来就纠结用 GPT-4 还是 Claude却忽略了同一套系统里上下文窗口的利用效率才是决定任务成败的关键。我看到过不少用顶级模型但上下文管理混乱的项目效果反而不如用普通模型 精心设计的摘要和状态管理。上下文就像你的工作台——工具再好台面堆满垃圾也干不了活。第二Agent 工程的本质是降不确定性。模型本身就是不确定的所以工程上所有努力都在降低这种不确定性详细的 Skill 指令、严格的工具 Schema、终止策略、错误恢复、人工闸门。你写的每一行工程代码本质上都是在给疯狂的天才画家装上画框。如果你觉得一个 Agent 系统很难测、经常抽风大概率不是模型的问题而是工程化不够。第三组织知识比模型知识更容易成为瓶颈。一个 Agent 好不好用最终取决于你给它配了多少高质量的工具和技能。与其天天研究新模型不如花时间把你所在领域的 Know-how 沉淀成 Skills——这可能是 Agent 时代最值得投入的方向。我自己最近的一大半精力都花在把业务里老师傅才懂的经验写成结构化的 Skill 文档上。Agent 开发的浪潮才刚刚开始今天看起来复杂的前沿玩法两年后可能就是基本功。但无论技术怎么变理解任务边界、设计清晰架构、构建可靠的工程防护这些核心能力永远不会过时。希望这篇基于 Agent-Reach 思路的总结能帮你在自己的 Agent 项目里少走一段弯路。