企业官网建设流程全解析

做Agent开发这几年，我最大的感受是：Agent不缺思考能力，缺的是触达能力。模型在脑子里面能把逻辑盘得很顺，但是一旦需要查个文档、调个接口、读一下用户的历史偏好，或者让另外一个Agent配合干点活，整条链路立刻变得乱七八糟。市面上关于agent框架、agent开发学习路线的资料很多，但大多把重心放在"思考—行动—观察"这个循环本身，对"行动怎么落下去"讲得很浅。我自己的项目Agent-Reach就是冲着这个缺口去的——它不是一个传统意义上的Agent框架，而是一层专门解决"触达"问题的中间层。这篇文章把它的核心设计、落地细节、以及我实测过程中踩过的坑完整写出来，希望能给正在做agent开发、被agent记忆、多agent协作、工具调用这些问题卡住的朋友一些参考。

1. 为什么我不把Agent-Reach叫Agent框架，而是叫"触达层"

先解释下这个命名。Agent-Reach里的Reach，直译是"够到、触达"。我做这个项目的初衷很简单：Agent的思考在模型内部，但它的价值必须体现在模型外部。一个只能在大脑里推理、却够不到任何外部资源的Agent，本质上就是个高级聊天机器人。

市面上很多Agent框架解决的是"循环"问题，也就是怎么让模型不断迭代思考、调用、观察、再思考。但真正做落地项目的时候你会发现，"循环"只是骨架，真正决定项目上限的是骨架外的那层"触达能力"——它决定了Agent能碰到哪些数据、以什么方式碰、碰了之后结果如何回流。Agent-Reach做的就是这一层。

1.1 "Agent是什么"这个问题，其实卡住了很多人

在agent学习相关的社群里，我经常看到有人问：skill和agent的区别是什么？harness和agent有什么区别？agent框架到底是干什么的？这些问题背后透露出的困惑是：Agent这个概念的边界太模糊了。

按我自己的理解，把几个概念放一起对比会更清楚：

很多人把Skill当成Agent的一部分，把Harness当成Agent的壳，这些说法都没错，但它们都不直接回答一个问题：Agent到底通过什么机制去够到那些外部资源？一套好的触达层，应该把这件事从"业务代码里散落的临时实现"变成"有协议、有路由、有安全边界的统一设施"。这正是Agent-Reach存在的理由。

1.2 Agent-Reach的设计立场：把触达当作一等公民

大多数Agent框架是把"调用工具"当成循环里的一小步——模型在ReAct循环中决定"我需要调用工具X"，然后框架帮你执行一下。而Agent-Reach反过来，把触达作为整个架构的中心。一个Agent可以绑定任意多的触达节点，但触达本身有一套固定的协议，节点之间不能绕开协议直接互相访问。

当时做这个设计决策，是因为我在项目里吃了太多"临时触达"的亏：今天给Agent接个搜索，就是在代码里写个search函数；明天要加上向量检索，又写个retrieve函数；后天要多Agent协作，直接在prompt里告诉模型"你可以向其他Agent发消息"。结果Agent的触达路径完全无法观测，出了问题根本说不清是模型判断错了，还是触达环节实现错了。Agent-Reach把触达抽象成"源—路由—节点—回流"四段，每一段都可观测、可审计、可单独测试。

2. 三个核心抽象：节点、触达路由、上下文口袋

Agent-Reach内部没有太玄乎的设计，主要抽象就三个：节点（Node）、触达路由（Reach Router）、上下文口袋（Context Pocket）。把这三件事想明白，Agent的外部协作能力基本就立住了。

2.1 节点：能力的最小单元

节点是Agent能触达的每一个外部能力的封装。一个工具（比如"联网搜索"）、一个技能（比如"生成流程图"）、一个记忆区（比如"用户长期偏好"）、甚至另一个Agent的入口，在Agent-Reach里都被建模为节点。

每个节点对外暴露统一的访问协议，核心字段包括：

{ "node_id": "project_docs_search", "node_type": "tool", "protocol": "function_calling", "endpoint": "internal_doc_retriever", "visibility": "internal", "auth_scope": "agent_runtime", "schema": { "type": "object", "properties": { "query": {"type": "string"}, "top_k": {"type": "integer", "default": 5} }, "required": ["query"] } }

这个设计让所有触达行为长一个样子。无论是调用外部API、查内部知识库、读写长期记忆，还是给另一个Agent派活儿，上层只用处理一种协议。我在早期项目里最大的痛点之一，就是工具A走HTTP、工具B走Python函数、记忆系统走向量库SDK，Agent的调用路径五花八门，改成统一节点模型之后，维护成本直接降了一个量级。

2.2 触达路由：决定这个请求该碰到谁

触达路由解决的是"模型想触达某个目标，但不知道该找哪个节点"的问题。本质上它是一个意图分发器，输入是Agent当前的目标和已有上下文，输出是一个节点或者一组节点的组合。

在Agent-Reach里，路由层维护了一张路由表，每条路由由三部分组成：触发条件、目标节点、置信度阈值。模型在思考过程中产生一个触达意图，我先通过轻量级分类模型做一个预路由，如果置信度高就直接绑定节点；置信度不够，则把候选节点列表交给大模型做一次选择。这样做的好处是：既控制了模型做路由选择时的随机性，又保留了大模型处理复杂语义的弹性。

这里我需要特别提一下很多人问的"在Agent中，路由识别节点到底是什么"。它不是一个物理节点，而是路由层里的一个逻辑角色——负责识别当前应该激活哪个触达节点。Agent-Reach把角色单独拆出来，是为了把"识别"这个动作和"执行"这个动作解耦。这样即使模型偶尔判断失误，至少你在日志里能清楚看到是哪一步错了。

2.3 上下文口袋：隔离局部信息，别让主上下文爆炸

上下文口袋是Agent-Reach里对Agent记忆和上下文管理的核心实现。它的思路非常朴素：不要把所有信息都塞进模型的主上下文，而是让每个节点拥有自己的局部上下文，只在必要时把摘要回流到主干。

打个比方：一个团队开项目会，不可能让每个成员把自己手头的五千字笔记全念一遍。大家各自记自己的本子，汇报的时候只讲结论。上下文口袋就是这个"本子"。

实现上，Agent-Reach为每个节点分配独立的context pocket，节点执行过程中产生的原始返回内容先落在自己的口袋里。只有当Agent的主规划器需要基于这些结果做下一步决策时，才做一次摘要压缩，把几百上千行的原始结果压缩成一小段结构化要点放回主干。这个机制直接解决了Agent开发里最常见的"上下文越跑越长、费用越跑越高、效果越跑越差"的恶性循环。

3. 落地实操：给Agent-Reach接入第一个工具的完整过程

抽象讲完，上点实际的。我带你把一个最普通的工具——"项目文档检索"——接入Agent-Reach，整个过程中最容易踩的坑都在这一步。

3.1 工具定义：JSON Schema要写得"窄而明确"

工具接入的第一步是给节点写Schema定义。很多初学者喜欢把description写得又长又泛，比如"这个工具可以搜索项目中的所有文档"，实测下来这种定义会让模型的幻觉调用率直线上升。Agent-Reach要求每个工具描述同时包含三部分：工具能做什么、工具不能做什么、什么情况下不要调用它。

TOOL_NODE_DEF = { "node_id": "project_docs_search", "node_type": "tool", "name": "search_project_docs", "description": ( "检索项目内部文档库。" "仅适用于查找已经沉淀在知识库中的项目文档、技术方案、会议纪要。" "不要用它搜索外部公开网页，不要用它回答与项目文档无关的常识问题。" "当用户询问的内容明显不在知识库中时，请不要调用该工具。" ), "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "搜索关键词，尽量用名词短语，例如'支付模块 超时问题'" }, "top_k": { "type": "integer", "description": "返回结果数量", "default": 5, "minimum": 1, "maximum": 10 } }, "required": ["query"] } }

我见过很多团队把"不要用它做什么"写在内部文档里，而不是写进schema。但实际上大模型构造function calling请求的时候，看不到你的内部文档，它只看得见你塞进请求里的schema文本。所以一切约束都得写进schema，别指望模型"自己悟"。

3.2 为什么"窄而明确"的工具正确率更高

这个问题的本质，是function calling在底层被模型当成一次"意图分类"任务。你给模型一个工具清单，它要判断当前这步该不该调用、调用哪个、参数怎么填。意图分类最怕的就是类别边界模糊。

举个例子，如果"项目文档检索"的描述是"一个检索工具"，同时系统里还有一个"天网搜索"工具描述是"一个搜索外部网页的工具"，模型在这两者之间就容易犯迷糊。但如果你把第一个工具的用法限制成"只查内部知识库"，第二个工具限制成"只查外部公开网页"，并且都写明"不是这个场景就不要调用"，正确率会明显上升。我在Agent-Reach的实测里，光是给工具描述加上反向约束这一项，无意义工具调用率就降了大概三成。

3.3 注册、执行、回流的标准三步

节点定义好之后，接入链路如下：

1. 注册：把节点定义加载进Agent-Reach的节点注册表，同时挂载对应的执行函数。执行函数必须是纯函数式的，输入是schema校验后的参数，输出是原始结果。
2. 执行：路由层把模型传入的参数做类型校验和准入判断，然后调用执行函数。这里要设置两个硬性指标——超时时间和最大返回字节数。任何一个超了，直接返回"节点执行失败"，不让异常状态污染主流程。
3. 回流：原始结果先进上下文口袋，由口袋做一次抽取式摘要，把"命中了哪些文档、各自的核心结论是什么"提炼成不超过几百字的要点，写回主上下文。

回流这个环节特别建议不要省。很多生产事故的源头就是某个工具返回了几千行JSON，模型根本处理不过来，于是开始瞎编。让口袋先消化一遍，给模型的永远是"压好的干粮"而不是"带壳的稻谷"。

4. Agent-Reach的记忆设计：长期记忆存的是"决策足迹"

Agent记忆是agent框架里绕不开的话题。最开始我以为记忆就是"把历史对话存起来，下次带上"。后来发现单纯这么做，上下文很快就装不下，而且存进去的大量垃圾信息会严重干扰模型判断。Agent-Reach把记忆拆成三层，并且在长期记忆里不再存"用户说了什么"，而是存"Agent做了什么决策、结果如何"。

4.1 三层记忆的职责划分

三层记忆在Agent-Reach里分别对应不同的上下文口袋。工作记忆就是主干上下文本身，情景记忆走向量检索写入口袋，程序记忆则以Skill的形式注册为节点。这个划分思路和很多人问的"skill和agent有什么区别"是对应的：Skill本质上就是程序记忆的固化，Agent则是把这些记忆和节点组合起来完成目标的执行者。

4.2 决策足迹：不存"结论"，存"决策路径"

在情景记忆这块，Agent-Reach做了一个关键设计：长期记忆的主索引不是用户原话，而是Agent的决策足迹。

什么叫决策足迹？举个例子，过去存记忆的方式是：在某个key里写"用户偏好：喜欢红色主题、不喜欢大段落文字"。但这句话本身就是一次信息压缩，压缩错了怎么办？用户当时说的是"这个红色挺好看的，但是文字能不能别这么密"，模型把它压缩成"喜欢红色、不喜欢大段落"，信息其实已经失真了。

Agent-Reach改成了这样一条结构化记录：

{ "memory_id": "mem_20250613_001", "scenario": "用户审阅数据分析报告", "agent_action": { "node_hit": ["report_renderer"], "rendered_style": "default_dark_theme", "proposal": "使用了红色主题并保持段落密集排版" }, "user_feedback": "肯定了红色主题，但要求段落间距加大", "derived_rule": "数据分析报告中可使用红色强调色，段落需保持宽松间距", "confidence": 0.7, "review_status": "pending" }

你会发现，这条记忆的关键不是derived_rule，而是前面的scenario、agent_action、user_feedback三段事实。决策足迹保留了完整的"场景—动作—反馈"链路，即便后来模型从这条记忆里提炼出的derived_rule是错的，系统也能基于原始事实重新推导，不至于被一条坏记忆带偏。

4.3 记忆写入时机：只在任务边界处落盘

另一个经验是：记忆不是在每轮对话都写入的，而是在一个任务闭环结束的边界处写入。我见过不少团队把记忆当聊天记录用，每轮对话结束就存一次，结果记忆库里堆满"用户说好的谢谢"这种毫无价值的信息。

Agent-Reach的做法是：每个任务都有一个生命周期，任务结束时由"记忆整理节点"统一扫描本次任务的关键节点命中情况和用户反馈，然后生成一批候选记忆，经过置信度筛选后写入长期记忆库。这一步既控制了记忆数量，又保证了记忆质量。

5. 多Agent协作：我把自己项目里的Agent拆成了四个

Agent-Reach最初被设计成单Agent的触达层，但实际跑了两个项目之后，我发现单Agent一旦任务链路变长，表现会明显下降。后来我在Agent-Reach上做了多Agent协作的实验，把自己的一个内容生产项目拆成了四个Agent：研究Agent、写作Agent、质检Agent、发布Agent。

5.1 拆分的动机：让每个Agent的上下文更干净

为什么拆？最直接的原因是上下文隔离。一个单Agent如果既要研究技术资料、又要写文章、又要检查事实错误、又要排版发布，它的主上下文会被各种任务碎片塞满。拆成四个Agent之后，每个Agent的主上下文只维护自己岗位相关的信息，研究Agent不需要关心发布格式，发布Agent不需要关心技术细节。

在Agent-Reach里，每个Agent都是一个独立运行单元，它们之间的通信不靠共享上下文，而是通过节点协议互相调用——这其实就是把Agent本身也变成了另一个Agent的触达节点。这里的核心经验是：多Agent协作的关键不是让它们多说话，而是让它们少说话。通信越频繁，整体出错率越高。Agent-Reach里默认Agent之间只通过"任务派发—结果交付"的方式通信，其余信息一律不进对方上下文。

5.2 编排与harness：谁来管理整条流水线

四个Agent不能是平级的，否则没有人对最终结果负责。Agent-Reach里有一个"主协调Agent"（相当于很多框架里说的harness角色），负责整体任务拆解、调度和结果验收。但它不干具体的活，只做四件事:

• 把用户的目标拆成可派发的子任务
• 决定当前该激活哪个Agent节点
• 对Agent交付的结果做初步质量检查
• 结果不合格时，决定是退回重做还是降级处理

说实话，这个主协调Agent一开始就是个大模型的prompt，后来我把它也节点化了，让它能调用质检Agent的能力来做验收。这个设计让我对"harness和agent区别"有了更实在的理解：harness是流水线本身，agent是流水线上的工位。Agent-Reach同时担任了流水线骨架和工位间传送带的角色。

5.3 冲突仲裁：当两个Agent给出矛盾结果

多Agent协作里最麻烦的是结果冲突。比如研究Agent找到的资料说方案A更好，写作Agent按方案B写了一版草稿，质检Agent在事实核查时发现了矛盾，这时候谁说了算？

Agent-Reach的仲裁机制很简单：不仲裁内容，只仲裁标准。主协调Agent在和质检Agent交互时，传的不是"你自己看着办"，而是几条可验证的硬标准（例如"结论必须引用研究中标记为高置信度的文档"）。一旦发现冲突，以标准为准，触发重写流程。这样避免了两个Agent在内容层面无休止的扯皮。

6. 实测中最容易翻车的三个点

Agent-Reach从开发到实际跑业务，我踩过的坑不少，挑三个最有代表性的说说，基本每个做agent开发的人都会碰到。

6.1 幻觉调用工具：模型"以为"自己需要工具

最典型的现象：用户问一个内部知识库里根本没记录的问题，模型不去回答"我不知道"，而是硬调用文档检索工具，检索出的结果和问题毫不相关，它还要硬总结。根因通常是工具描述没有把边界写清楚，或者路由层的置信度阈值设得太低。

我的解决办法有两层。第一是写schema时给工具加"否定条件"，明确写清"当问题不在知识库覆盖范围时，必须拒绝调用并返回NO_RESULT"。第二是在路由层加一道实测校准：预先准备二十条覆盖"该调用/不该调用"的测试样本，每次调整prompt后跑一遍，工具误调率超过5%就不准上线。

6.2 超时与重试：触达外部世界，就要面对外部世界的不稳定

接外部API时，超时是最容易被低估的问题。大模型发起一次工具调用，底层执行可能涉及外部服务，动辄几秒钟。如果Agent在一个循环里要调用三四次工具，整个链路可能变得不可接受地慢。

Agent-Reach对每个节点设了三档超时：快路径（2秒）、标准路径（10秒）、慢路径（30秒），不同类型的节点走不同档位。同时所有节点执行都带自动重试，但重试策略不是固定的——幂等节点可以重试三次，非幂等节点默认不重试，避免重复扣费或重复写入。这个细节看着不起眼，在实际项目里非常救命。

6.3 上下文口袋的边界：口袋太多也容易乱

上下文口袋也不是越多越好。我早期设计的粒度很细，每个小步骤都配一个口袋，结果主协调Agent反而失去了全局视角，做决策时经常"看不到森林"。后来我把口袋分为两级：节点级口袋只存原始执行结果，Agent级口袋存当前任务的关键状态。主上下文只和Agent级口袋交互，节点级口袋完全对主上下文透明。这个"两级口袋"的模型是我最终稳定下来的方案。

7. 一次完整落地：Agent-Reach从需求到上线的检查单

最后分享一个完整的落地流程。假设现在要做一个"智能周报助手"，基于Agent-Reach来搭建，按下面几步走基本不会乱。

7.1 需求拆解与节点规划

先不写代码，把Agent需要触达的所有外部能力列出来：

• 读取项目成员本周提交的代码和文档
• 检索团队知识库中的项目进展
• 查询本周未关闭的问题单
• 调用模板渲染器生成周报文档
• 发送周报到指定的协作群

对应规划成五个节点。注意：这一步不要急着想"要不要用大模型思考什么"，先想清楚Agent要碰到哪些东西。触达资源的梳理，比选型重要得多。

7.2 测试流程与方法

Agent测试不能单测"模型输出好不好"，要拆成三层来测：

1. 节点测试：每个工具独立测试，重点验证参数校验、超时、异常返回是否正常。工具本身不能出幺蛾子，否则Agent再聪明也没用。
2. 路由测试：用一批典型任务验证路由层能不能选中正确的节点，特别是边界情况。比如用户问"本周有谁请过假"，正确节点应该是查考勤，而不是查问题单。
3. 端到端测试：完整跑一遍"目标输入→周报生成→发送"的链路，重点盯上下文回流有没有丢关键信息。

我在Agent-Reach项目里维护了一套"黄金测试集"，大约一百条覆盖各种任务场景的输入，任何一次节点定义或路由策略调整后都全量回归一遍。没有这套回归，我不敢随便动路由配置。事实上，agent测试流程与方法在网上讨论得很少，大部分人是靠肉眼调prompt，这是我在项目后期最想补上的一课。

7.3 安全边界：触达能力越大，责任越大

Agent一旦能触达外部资源，安全问题就必须前置。我的硬性要求是：所有节点默认拒绝，只对显式授权的资源开放。特别是涉及到发消息、写数据、调外部付费API这类节点，必须走额外的授权确认流程，模型不能仅凭用户一句话就触发。

日志审计也得完整。Agent-Reach会对每一次触达行为记录四要素：哪个Agent发出的、触达了哪个节点、传了什么参数、返回了什么结果。出了问题能回溯到具体某一次调用，而不是靠猜。

这个项目做到现在，我最深的体会是：Agent的智能程度固然取决于模型能力，但在工程层面，决定一个Agent项目能不能稳定运行的，往往是那些看似不起眼的"触达细节"——工具边界有没有写清、上下文有没有控制好、多Agent通信有没有克制、测试集有没有覆盖边界场景。Agent-Reach的Reach这个词，其实时刻在提醒我：让Agent够到外部世界很简单，但让它够得准、够得稳、够得安全，才是真正见功夫的地方。

最后再分享一个实操心得：如果你也想做类似的触达层，不要一上来就铺很大的架构。先拿一个你手头最痛的工具接入场景，把节点、路由、上下文口袋的最小闭环跑通，再逐步扩展。很多问题在规模小的时候不会暴露，但等架构铺开了再改，成本就完全不一样了。