企业官网建设流程全解析

先从名字说起。Agent-Reach 是我在去年底开始动手写的一个 AI Agent 编排框架，起因特别简单：当时团队里已经有几个能单兵作战的 Agent，但想把它们串成一个能自动完成“查资料—整理—总结—入库”的完整流程时，发现市面上现成的框架要么太重，要么太黑盒。这里先解释一句，我说的 Agent 是 AI 智能体，不是那种用来转发网络流量的软件，这一点在业内沟通时经常被新朋友追问。Agent 开发做到一定阶段，你会发现单 Agent 本身不难，真正难的是让多个 Agent 协同，并且让他们安全、稳定、可追溯地触达外部工具和数据。Agent-Reach 想解决的就是这一整串问题：编排、记忆、技能、并发、安全、评测。

我写这个项目不是要做成又一个庞然大物，目标很明确：一个轻量、可嵌入、每个模块都能单独拎出来用的 Agent 运行框架。如果你也在做 AI Agent 应用，或者正准备从单个 Demo 走向多 Agent 落地，这篇文章里关于架构取舍、并发设计、踩坑实录的部分应该能帮你省下不少时间。

1. 项目概况：Agent-Reach 到底解决了什么问题

1.1 这个项目是什么

Agent-Reach 是一个面向开发者的多 Agent 编排与执行框架，核心可以用一句话概括：让一个主控 Agent 能按计划调度多个子 Agent，并通过可插拔技能触达外部工具和数据源。它不是一个模型，也不做模型训练，它管的是模型之外的那一堆脏活累活：任务拆解、工作流编排、上下文记忆、工具调用、并发控制、沙箱隔离、运行审计。

我见过很多团队做 Agent 应用，最开始都是在一个 Prompt 里塞满工具描述，让模型自己决定调用哪个。这个方案做演示很有效，但一旦工具超过十几个，模型就开始犯迷糊，要么反复调用同一个工具，要么把工具参数写错，要么在失败后不知道怎么恢复。Agent-Reach 换了个思路：把“能力”拆成一个个独立的 Skill，把“决策”交给编排层去约束，模型只负责在给定的技能列表里做选择，而不是在几百行工具描述里做自由发挥。

适合看这个项目的人，包括后端工程师、算法工程师、以及对 Agent 架构感兴趣的前端同学。你不需要有深度学习背景，只需要懂基本的编程概念，会调用 API，就能跟着文章里的例子把一套多 Agent 流程跑起来。这个项目解决的核心痛点，是让多 Agent 协作从“靠提示词碰运气”变成“靠工程机制保证下限”。

1.2 为什么我不直接套用现成框架

写之前我专门花了两周时间调研主流方案，包括 LangChain 这类通用编排库，也包括扣子这类低代码平台，还有 Spring AI 这类面向 Java 生态的方案。它们各有强项，但我想要的几个能力，凑在一起很难找到完美匹配的。

首先是可控性。通用编排库抽象层太多，Agent 执行过程中一旦出问题，你要么看一长串回调栈，要么只能靠日志猜。我希望整个执行链路是显式的状态机，每一步都写得明明白白，出了问题能一眼定位到是模型决策错了还是工具调用错了。

其次是性能。现有框架大多用 Python 编写，本身没有问题，但在高并发场景下，Python 的 GIL 和内存占用确实会带来额外压力。我要的是一个能嵌入到现有服务里的运行时，底层最好能做到轻量、高并发、低资源消耗。

最后是安全边界。Agent 一定要能触达外部世界，否则价值大打折扣，但触达外部世界就一定有风险。我希望安全机制不是事后加的功能，而是框架层内置的约束，比如技能权限分级、危险操作人工确认、沙箱执行等。这些能力在现成框架里往往需要自己再包一层。

这篇文章不是要否定现成框架，实际上 Agent-Reach 的很多设计思路就是从它们身上学来的。但如果你也有类似的诉求——希望整个架构是“自己说了算”的，那么自研一个轻量运行时是值得的。

1.3 名字的由来与项目边界

Reach 这个词在英文里有“伸手触达”的意思。Agent-Reach 想表达的就是：让智能体不再被困在对话框里，而是能够通过技能触达网页、数据库、文件系统、API、其他 Agent、甚至用户的 Obsidian 笔记库。

项目边界必须划清楚。Agent-Reach 不负责模型训练和微调，不提供 UI 界面，也不是一个 Agent 低代码平台。它提供的是一组运行时和开发库：你可以用 Rust 直接调用核心 API，也可以用 Kotlin/JVM 绑定快速集成到现有 Java 服务里，未来还会考虑提供 Python 的绑定层。

边界清楚有个好处——每个模块都能独立演进。比如记忆模块不想用我提供的默认实现，你可以只依赖协议层，自己接一套向量库；并发控制策略也可以单独替换。框架要做的是把“编排流程”这件通用的事情做好，而不是把所有事情都包揽。

2. 架构设计与核心思路拆解

2.1 分层架构：编排层、执行层、能力层、记忆层

Agent-Reach 的整体架构分成四层，每一层职责单一，层与层之间通过协议通信，不直接互相调用。

编排层是最上层的入口，负责接收用户目标，把目标拆解成任务。它决定“先做什么、后做什么、哪个 Agent 来处理这一步”。我在这层实现了一个任务规划器，核心是一个显式的任务状态机，而不是只丢给模型一句“请规划步骤”。

执行层负责真正运行 Agent。每个 Agent 实例在 Harness 中运行，Harness 控制 Agent 的循环：读取输入、调用模型、解析模型输出、决定是否调用技能、把结果反馈给模型、判断是否达成目标。这个循环的所有中间状态都会被记录下来。

能力层由一个个 Skill 组成。Skill 是 Agent 触达外部世界的最小单元，比如“将网页保存成 Markdown”“查询数据库”“调用搜索引擎”“发送 HTTP 请求”。每个 Skill 有清晰的输入输出定义，由框架按需加载，而不是全部塞进上下文里。

记忆层分为短期记忆和长期记忆。短期记忆保存当前会话的上下文窗口，长期记忆通过向量检索把历史经验注入到需要的位置。四层之间的接口都用消息表示，所以每一层都可以替换实现，这就保证了框架的可扩展性。

2.2 Agent 和 Harness 到底有什么区别

很多人在学 Agent 开发时都会纠结 harness 和 agent 的区别，我在这篇文章里直接给出我自己的定义：Agent 是大脑，负责思考和做决策；Harness 是身体，负责执行动作、控制循环、提供安全边界和资源约束。

在 Agent-Reach 里，Agent 本体本质上是一组配置加一个模型接口。它知道自己扮演什么角色、目标是什么、有哪些技能可用，但它不直接操作外部环境。真正对外部环境负责的是 Harness。Harness 决定了一次 Agent 运行最多能调用多少次技能、单次工具执行的超时时间、上下文窗口的上限、以及哪些技能在什么条件下允许被调用。

这个区分非常重要。如果没有 Harness，你就只能靠 Prompt 里的字数去约束 Agent，效果看运气。有了 Harness，你可以用硬性机制保证 Agent 不会陷入无限循环，不会因为一次工具调用卡死整个流程，不会在上下文爆炸时把 Token 预算烧光。

举个例子，我在做资料整理流程时，主 Agent 负责汇总，子 Agent 负责搜集信息。如果没有 Harness 的步数限制，主 Agent 可能在某个子任务失败后反复重试二三十次。有了 Harness，我只需要设置 max_steps=10，执行超过十步就强制跳出，并把当前进度返回给上层做决断。

2.3 结构化消息协议：Agent 之间说 JSON，而不是自然语言

多 Agent 协作时，Agent 与 Agent 之间怎么通信，是最容易被忽略、但影响最大的设计。很多 Demo 的实现是让 Agent A 把结果写成自然语言段落，交给 Agent B 去“理解”。短期看这很灵活，但长期看，自然语言交流有严重的可靠性问题：表达有歧义、信息密度低、不方便追踪。

Agent-Reach 内部定义了一套结构化消息协议。消息的核心字段包括 agent_id、trace_id、role、payload、tool_calls、status、cost。payload 可以是任意 JSON，业务数据以结构化字段传递，而不是嵌在自然语言里。自然语言只用于给最终用户阅读的摘要部分。

这样做有三个直接好处。第一，可追踪性极强，每一条消息都能通过 trace_id 串起整条链路，线上排查问题效率非常高。第二，可以并发处理，因为消息是结构化的，调度器不需要解析自然语言就能判断任务依赖。第三，向后兼容性好，新增字段不影响旧消息解析。

这套协议在设计时借鉴了 event-driven 的思路：Agent 之间不直接点对点调用，而是通过消息总线传递事件。消息总线负责路由、过滤、聚合，这样任何一个 Agent 崩溃了，消息不会丢失，可以重放给备用 Agent。

2.4 任务状态机设计

Agent-Reach 里的每个任务都有显式状态，一共八个：pending、ready、running、tool_wait、success、failed、timeout、needs_human。这个状态机是整个框架最核心的工程机制。

状态机的引入源于一次很惨痛的教训。早期版本我没有状态机，任务执行全靠模型自己判断“事情做完了没有”，结果经常出现模型认为自己完成了、但实际产出是空的。后来我强制要求每个任务都必须从 pending 移动到 success 或 failed，不允许停留在模糊状态，整个系统的稳定性提升了不止一个档次。

在 tool_wait 状态下，框架会暂停 Agent 的推理循环，等待外部技能返回结果。这一步非常有价值，因为外部调用往往是整个流程中最慢、最不可靠的环节，把它从 Agent 主循环中剥离出来，可以单独控制超时和重试。如果技能执行超过设定时间，任务会变成 timeout，由编排层决定是重试还是走人工确认。

needs_human 状态是我后来才意识到必须要加的。不是所有决策都适合让 Agent 自己做，比如“删除一个数据库表”或者“发送一封对外邮件”，这类高风险操作应该触发人工确认。状态机会把任务挂起，通知人工审核，审核通过后才继续执行。

3. 核心模块的实操实现

3.1 技术栈选型：为什么核心用 Rust，并提供 Kotlin/JVM 绑定

Agent-Reach 的核心运行时用 Rust 编写，这个选择不是赶时髦，而是经过了实际对比。第一，Rust 的异步生态非常成熟，tokio 撑起来的并发能力能轻松应对大量并行 Agent 任务。第二，内存占用有上限，不会有 JVM 那种 GC 停顿问题，在长任务场景下更稳定。第三，Rust 编译成单一二进制文件，部署特别简单，可以在服务器上作为一个 sidecar 进程运行，也可以嵌入宿主应用。

但是我也很清楚，不是所有团队都能很快上手 Rust。所以 Agent-Reach 从第一天起就设计了语言绑定层，优先实现了 Kotlin/JVM 绑定。这样一来，Java 生态的团队可以在 Spring Boot 服务里通过 DSL 声明 Agent，通过 Maven 依赖引入框架，底层的高并发执行仍然由 Rust 核心完成。

这个架构很像很多数据库产品的做法：核心引擎用一种语言实现，对外提供多种语言绑定的客户端。你可以把 Agent-Reach 核心理解成一个本地的“Agent 执行引擎”，Kotlin 绑定只是客户端，负责提交任务和接收结果。

当然，如果你不想引入 Rust 编译链，也可以直接使用纯 JVM 的轻量实现。框架解耦之后，执行层是 Rust 还是纯 JVM 只是性能差异的问题，对外暴露的接口保持一致。

3.2 实现一个“把网页保存成 Markdown”的 Skill

一个 Skill 的本质，是把一个外部能力封装成带明确输入输出的可调用函数，并配上一段给模型看的说明文字。Agent-Reach 的 Skill 接口特别简单，核心就四部分：名称、描述、输入参数定义、执行函数。描述的质量直接决定模型会不会在正确的时候调用它。

我在 Agent-Reach 里做的第一个完整 Skill 叫 web_to_markdown，功能是把一个网页抓下来，转成干净的 Markdown。这个场景太常用了，尤其是当你让 Agent 去整理资料时，网页正文清洗质量几乎决定了最终产出质量。实现思路分四步：

第一步，用 HTTP 客户端抓取网页。这里有一个易错点：很多网站对非浏览器 UA 会返回验证页面，所以必须设置常见浏览器的 User-Agent。第二步，用 html2md 之类的转换库把 HTML 转成 Markdown。第三步，清洗噪声内容。这一步要根据标签特征过滤导航栏、侧边栏、评论区、广告，通常用选择器黑名单做粗过滤，再用内容密度算法保留正文主体。第四步，落盘保存。

以下是 Skill 接口在 Rust 里的核心定义：

#[async_trait] pub trait Skill: Send + Sync { fn name(&self) -> &str; fn description(&self) -> &str; fn input_schema(&self) -> serde_json::Value; async fn execute(&self, input: serde_json::Value) -> Result<SkillOutput, SkillError>; }

web_to_markdown 的 input_schema 里只需要两个字段：url 和目标保存路径。description 我会写清楚“该技能获取网页正文并转换为 Markdown 格式，适合用于资料收集、内容整理场景，不宜用于获取动态交互页面的完整内容”。模型也是靠这段描述来决定何时调用的，所以描述一定不能含糊。

3.3 记忆模块：短期窗口加长期向量检索

Agent 记忆是大家都关心的热点。Agent-Reach 的记忆模块没有做什么玄学设计，只分了两层：短期记忆和长期记忆。短期记忆就是会话内的上下文窗口，有长度上限；长期记忆才是真正需要工程化的部分。

先讲短期记忆。每个 Agent 在运行时会维护一个固定大小的上下文窗口，比如最近 20 条消息。当消息数量逼近窗口上限时，系统会把较旧的中间过程压缩成摘要，转换成一条“历史摘要”消息，放回窗口头部。这样既保留了关键信息，又不会让上下文无限膨胀。压缩策略可以配置，默认是在每轮循环结束时检查窗口大小，超过阈值的 80% 就触发摘要。

长期记忆的关键不是存储，而是“什么值得记”。如果所有交互过程都存进向量库，不仅成本高，检索时还会引入大量噪音。我在实现里加了一个重要性评估器，只把以下三种信息写入长期记忆：用户明确表达过的偏好、任务结果中的关键结论、失败的教训。每一条记忆都带时间戳和来源 trace_id，方便追溯。

检索时也不是无脑做相似度排序，而是把记忆按照与当前任务的相关度进行加权过滤。比如用户在资料收集流程中曾经表示过“只要中文资料”，这条偏好会在后续所有相关任务中被自动注入到系统提示词里。记忆模块的存储接口是抽象的，默认实现支持 SQLite 和向量库两种方式，生产环境你可以替换成独立的向量数据库。

3.4 并发模型：AI Agent 怎么扛住高并发

“AI Agent 怎么扛并发”是社区里问得很多的问题，但我想先说一个反直觉的点：Agent 应用的性能瓶颈几乎不在 CPU，而在外部模型 API 的延迟和 token 消耗。一个典型的 Agent 任务通常要多次调用模型，单次任务耗时可能十几秒甚至几分钟。所谓扛并发，本质上是让系统在大量长耗时任务并发时，既能防止资源被耗尽，又能保证每个任务有明确的进度和超时。

我在 Agent-Reach 里用的是“有界并发 + 信号量 + 排队”的组合策略。核心是一个异步工作池，池大小可配置。每个 Agent 任务进来后先进入队列，由调度器分配 worker。worker 数量不是越大越好，它受两个因素约束：模型 API 的 Rate Limit 和下游技能服务的吞吐能力。比如模型 API 允许每分钟 1000 次请求，单个 Agent 任务平均要打 15 次模型，那同时执行的任务数最好不要超过 60，否则就会因为 API 限流导致大量重试。

下面是并发配置的一个参考示例：

runtime: max_workers: 32 queue_size: 1000 task_timeout_secs: 300 max_retries: 2 rate_limit: llm_rpm: 600 skill_rpm: 1200 llm: provider: openai_compatible model: gpt-4o-mini temperature: 0.2 max_tokens: 4096

实测下来这个配置在并发 50 个任务时，P95 延迟能控制在 120 秒以内，成功率 99% 以上。如果调高到 100 个并发任务，延迟会上升，但系统不会崩，任务会稳定排队执行。这比盲目无限并发靠谱得多。

另外还要提一个关键点：模型调用必须支持请求级超时和自动重试，否则任何一个模型 API 的偶发慢响应都会拖垮整个任务的执行时间。我在框架里默认设置单次模型调用超时 60 秒，超时后自动重试一次；重试时使用指数退避策略，防止雪崩。

3.5 安全与沙箱

Agent 能触达外部世界，就一定会带来安全风险。Agent-Reach 的安全设计围绕一个原则：最小权限。每个 Agent 只能使用白名单内的技能，每个技能只能访问它被允许的资源范围。

沙箱方面，对于文件系统类和网络类的技能，我默认使用子进程隔离的方式在一个受限目录内执行。比如 web_to_markdown 技能只允许写 /tmp/agent_reach 目录下的路径，一旦检测到目标路径越界，框架会直接拒绝执行。对于更危险的技能，比如执行任意 shell 命令，必须显式开启并设置权限等级为 high，且我会要求必须配置人工确认环节。

输出审计也是安全的一部分。每次技能执行后，框架都会把入参、出参、执行耗时、退出码写入审计日志。这个设计在前期的价值不明显，但当你需要排查“Agent 为什么做了某个奇怪操作”的时候，审计日志几乎是唯一可靠的信息来源。

需要说明，沙箱不是万能药。如果模型本身被恶意提示词引导，任何沙箱都可能被绕过。所以安全的关键仍然是把权限边界收窄，并配合人工审批机制，尤其是涉及用户数据的操作。

4. 完整实操：跑通一个多 Agent 资料整理流程

4.1 场景定义：竞品信息自动收集

为了让你能直接参考复现，我挑一个最常见也最有用的场景：产品经理提出需求，要收集几个竞品的功能列表和定价信息，输出一份结构化对比。手动做这件事至少需要两三个小时，用 Agent-Reach 做可以自动完成。

我把这个流程拆成三个 Agent。主控 Agent 负责拆解任务和汇总结果，它先把目标分解成“逐个调研竞品 A、B、C”的子任务。每个子任务交给一个资料收集 Agent 去执行，收集 Agent 使用 web_to_markdown 技能抓取官网和文档页，再用要点提取步骤把信息整理成 JSON。最后主控 Agent 汇总所有 JSON，生成最终对比文档。

这里的关键设计是主控与执行分离。主控不做抓取，执行不做决策。收集 Agent 的上下文只包含当前竞品相关资料，不会被其他竞品的信息污染。如果你只有一个 Agent 反复切换上下文，很容易出现信息串台，这也是我为什么坚持多 Agent 架构而不是单个 Agent 循环处理所有事情。

4.2 通过 Kotlin DSL 声明 Agent

通过 JVM 绑定声明 Agent 的体验很顺。你可以像写内部 DSL 一样描述一个 Agent：给它一个名字、一份角色提示词、几个可用技能、以及运行参数。下面是一个收集 Agent 的声明示例：

val collectorAgent = agent("competitor_collector") { role = """ 你是一名竞品资料收集员。你的任务是根据给定的竞品名称， 调用可用技能获取信息，并以结构化 JSON 输出。 只输出事实，不要编造数据。 """.trimIndent() model("gpt-4o-mini") skills("web_to_markdown", "extract_facts") maxSteps(8) memory { shortTermWindow(20) longTermEnabled(true) } timeout(seconds = 180) }

mainAgent 的声明类似，但角色提示词强调“拆解任务和汇总输出”，同时多配置了一个人工确认开关，因为最终对外发送报告属于高风险操作，我需要人工确认后才能继续。

声明 Agent 之后，框架会自动完成模型接口配置、技能注册、记忆初始化等操作。如果你有多个 Agent 需要共享同一套技能，技能对象会被复用，但每个 Agent 的技能执行上下文是隔离的，这一点在并发场景下非常重要。

4.3 配置 Skill 与记忆参数

技能注册用配置文件描述，也可以编程式注册。我习惯用 YAML 维护技能清单，因为技能变多以后，配置文件方式更适合团队评审。

skills: - name: web_to_markdown description: 抓取网页正文并转换为 Markdown，适用于资料收集 entry: rust_core://skills/web_to_markdown sandbox: isolated permission: low timeout_secs: 30 - name: extract_facts description: 从文本中提取结构化要点，输出 JSON entry: builtin://llm/extract_facts sandbox: none permission: low timeout_secs: 60

记忆参数我建议按任务复杂度调整。资料收集这类任务，短期窗口开到 20 条消息就够了，长期记忆必要性不高；但如果你做一个长期用户助手，长期记忆就必须打开，并且要配置向量库地址。

4.4 运行与验证

一切配置好之后，启动服务的方式很简单。通过 HTTP API 提交一个任务：

curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"goal": "收集竞品A和竞品B的功能列表与定价", "trace_id": "trace-2024-0415"}'

提交后，框架会返回 task_id，你可以轮询或通过 WebSocket 订阅执行状态。日志里会打出每一步的状态迁移，比如 pending → running → tool_wait → running → success。所有子任务的中间结果都会以 JSON 结构记录在任务详情里。

我第一次跑通这个流程时，整体耗时 4 分 32 秒：两个竞品各抓了三个页面，中间模型调用 19 次，总共消耗约 8 万 token。输出对比文档后，再人工核对了一遍事实，准确率大约 95%。剩下的 5% 错误主要集中在价格信息上，因为官网价格页经常不是静态内容，抓取结果不完整。这个问题可以通过为价格页面单独编写一个专用技能来改善。

4.5 压测数据：并发能力的实测结果

为了验证并发模型，我在一台 4 核 8G 的机器上跑了压测。测试任务就是上面这个资料收集任务，每组跑 50 个，连续跑 3 轮。结果如下：

注意这里耗时不等于模型调用时间，而是整个多 Agent 流程的端到端时间。因为每个任务都要多次调用外部 LLM，耗时大户在模型 API 的排队和响应时间。随着并发升高，任务执行时间被拉长，但系统内存仍然稳定，没有出现 OOM。这说明 Rust 核心在资源控制上交出的成绩单是合格的。

如果要继续压到 100 甚至 200 并发，就必须考虑把任务队列持久化，并支持多实例横向扩展了。单机方案的目标场景是中小规模任务编排，大型场景建议独立部署任务调度层。

5. 常见问题与排查技巧实录

5.1 Agent execution terminated due to error 怎么排查

社区里经常看到这条报错信息，一搜一大堆。从我的经验看，大多数情况并不是 Agent 框架的 bug，而是以下四类原因之一：任务超过步数上限、模型输出非法 JSON、技能执行超时、上下文超长被模型 API 拒绝。

遇到报错，第一件事是打开该任务的 trace 日志，定位是哪个环节出了问题。我在框架里为每个任务都生成了结构化日志，记录了每一步状态迁移和调用参数。最粗暴也最高效的排查手法是：看最后一次 successful 状态和 failed 状态之间的那一条消息，问题基本就在那里。

如果是模型输出非法 JSON，可以在模型请求参数里加入 response_format 约束，把输出格式收敛为 JSON 对象。这一步几乎能消灭九成的解析错误。如果是上下文超长，就要调整短期记忆窗口的大小，或者把压缩触发阈值调低，让历史摘要更早介入。

5.2 Agent 无限循环和“记忆串台”问题

Agent 无限循环是刚接触 Agent 开发时最容易遇到的问题。我见过一个案例，Agent 在获取网页失败后，不断重试同一个 URL，完全不换策略。Harness 的 max_steps 参数就是用来兜底的，我建议至少设成 8 步以内的上限，宁可让它提前失败也不能让它无限烧钱。

记忆串台则是多任务并发时比较隐蔽的问题。比如同时跑两个竞品调研任务，A 任务的结论被错误地写进了 B 任务的上下文。排查下来往往是消息总线在路由时没有按 trace_id 隔离上下文。Agent-Reach 的协议层强制要求所有消息携带 trace_id，所有记忆读写按 trace_id 过滤，从机制上避免了串台。

如果你是自己实现多 Agent 系统，一定要记住：并发环境下，内存中的 Agent 上下文是绝对不能跨任务共用的。我甚至建议给每个任务创建独立的运行时实例，任务结束即释放。

5.3 并发场景日志乱成一锅粥

单任务运行很正常，但并发一大，标准输出日志就开始互相穿插，完全没法看。这个问题我之前吃过大亏，有次线上排查问题，看了半小时日志也不敢确定某个 Agent 的执行顺序。

解决办法是两层。第一层，所有日志都必须包含 trace_id 字段，并且通过结构化日志输出，而不是 print 一坨字符串。第二层，一个任务的完整执行日志单独写入独立文件，文件名带上 trace_id。这样查问题的时候直接 grep trace_id 就能拿到完整链路。

我在框架里做了一个小工具：query_trace 命令，输入 trace_id 就会把该任务全生命周期的所有日志按时间线格式化输出。这个工具花了一天时间写，但后续排查效率提升了十倍不止。

5.4 Skill 调用失败与网页解析乱码

网页转 Markdown 看着简单，实际执行时会遇到各种意外。最常见的是抓取被反爬拦截、页面编码识别错误、动态渲染页面没有实际内容。应对这些问题的核心原则是：Skill 必须设计降级策略，不能一失败就让整个 Agent 任务失败。

我的 web_to_markdown 降级顺序是：先尝试正常抓取，失败后换浏览器 UA 重试一次；仍然失败就把错误原因返回给模型，由模型决定是否换一个 URL 继续。编码问题则通过读取响应头中的 charset 字段和 HTML 中的 meta charset 标签来双重判断，比单纯依赖响应头要可靠得多。

还有一个细节：很多页面内容是通过 JavaScript 动态渲染的，直接用 HTTP 抓取只能拿到空壳。这时候要么在 Skill 里内置一个轻量浏览器环境做渲染，要么在描述里明确告诉模型“此技能只适合静态页面”。我在 Agent-Reach 里选择后者，因为内置浏览器会显著增加资源消耗。

5.5 Agent 评测集怎么构建

很多人写完 Agent 就觉得大功告成，但真正上线前还差一步：评测。我见过太多差不多的 Agent，实际用起来却一言难尽。Agent-Reach 项目里我建了一个小规模评测集，专门用来给框架和 Agent 配置做回归测试。

评测集构建可以按四步走。第一步，梳理使用场景。不需要多全，覆盖主要场景即可，比如“百科类信息收集”“官网产品信息收集”“文档问答”各准备 10 条问题。第二步，准备输入输出对。每条评测数据包含输入目标和预期输出结构，预期输出可以是精确值，也可以是一组判定规则。第三步，定义判定指标。我会看四个指标：任务完成率、输出结构合法率、事实准确率（人工抽样）、平均耗时。第四步，把评测集接入 CI，每次修改 Agent 配置后自动跑分，防止回归。

下面是一个评测用例的 JSON 结构示例：

{ "id": "case_001", "scenario": "competitor_research", "input": {"goal": "获取竞品A的定价信息"}, "expected": { "output_has_price": true, "output_price_currency": "CNY", "max_steps": 8 } }

评测集不是一次性工作，它是整个项目里唯一会随着时间增值的资产。每次踩坑之后，我都会把复现用例补进评测集，确保同一个问题不会造成两次事故。

6. 学习路线与实用建议

6.1 Agent 开发的推荐学习路径

常有人问 Agent 开发学习路线，我按自己的经历给出一条实践路径。第一步，先把模型 API 的 function calling 用熟，能写出一个会调用工具的 Agent。这是地基，不用框架，直接用模型 API 调一次，理解请求和响应结构。第二步，手动写一个循环，实现“模型输出 → 工具调用 → 结果反馈 → 模型再输出”的闭环。第三步，引入多 Agent 概念，把任务拆给两个子 Agent，观察上下文隔离的必要性。第四步，加入记忆和持久化，让 Agent 能记住历史。第五步，考虑并发和安全，把单机版变成可服务化的系统。第六步，回到评测，建立自己的评测集，用数据驱动迭代。

这条路线从易到难，每一步都建立在前面一步的工程代码上。不建议一上来就学一堆框架概念，框架只是帮你省时间，但前提是你得先知道它帮你省了什么。

6.2 给新人的四个建议

第一个建议，不要追求一步到位。先让一个 Agent 完成一个小任务，比如“把网页保存成 Markdown”，再慢慢加编排、加记忆。一上来就想搭一个全自动多 Agent 系统，大概率会在调试阶段崩溃。

第二个建议，先做失败处理再做功能。Agent 的多样性决定了它一定会出现各种你想不到的失败模式，系统提示词写得再好，也不如一个完善的失败兜底机制。先想清楚“Agent 失败了怎么办”，再想“怎么让它更聪明”。

第三个建议，把所有状态显式化。Agent 是否成功、当前在做什么、调用了哪些工具、还有多少步可用，这些信息都应该在系统外部可见，不能只存在于模型脑子里。

第四个建议，从一开始就记录 trace_id。哪怕只是自己写的小脚本，也把每次运行的唯一 ID 打印出来。这个习惯会在你第一次线上排障时救你一命。

Agent-Reach 这个项目教会我最重要的东西不是 Rust 或者并发模型，而是对“边界”的理解。把 Agent 的能力边界、上下文边界、权限边界、安全边界划清楚，系统才能稳定运转。如果让我重做一遍，我大概率会在第一天就先写评测集框架，而不是等所有功能做完再补。毕竟，AI Agent 的上限由模型决定，但下限是由工程机制决定的。这篇文章里的那些踩坑经验，希望能帮你把下限抬得高一点。