企业官网建设流程全解析

做大半年Agent项目，我最深的感受是：模型能力再强，也常常卡在"够不着"这三个字上。用户问一个稍微复杂点的问题——比如"把这三份报表合并，按部门做个对比，再发到工作群里"——很多Agent框架就哑火了。不是模型答不上来，而是它根本没有把任务拆透、把工具串起来的那条"触达半径"。Agent-Reach就是专门解决这个问题的：它不是一个新模型，也不是要从头搭建的Agent框架，而是一套给已有Agent补上任务规划、状态持久化、工具联动和结果回环能力的工程实践方案。如果你正在做LLM应用、搞AI员工、写工具调用的自动化流程，这篇文章大概率能帮你少走几个月的弯路。

1. 为什么要做Agent-Reach：从Agent的能力边界说起

1.1 单次对话的"够不着"困境

先说一个我从项目里抽出来的真实场景。用户丢过来一句话："把上周的项目周报按人员整理成表格，标出异常项，并给每位负责人发一封通知邮件。"

听起来不难对吧？但你要是用最朴素的"对话式Agent"去做，大概率会卡在第三步。模型第一轮生成一个看似完美的计划：读取周报文件、按人分组、识别异常、调用邮件接口。然后它在读取文件时发现，那份所谓的"周报"其实是一堆分散在不同目录下的CSV和一张多Sheet的Excel，数据口径还不一致。这时候普通Agent就开始"表演"了：要么胡编一个统计结果，要么重复调用同一个读文件的工具死循环，要么直接告诉用户"我做不到"。

我问过很多同行，大家遇到的情况大同小异。根因其实非常一致：当前的会话循环里，系统只维护了一段对话上下文，没有"任务状态"，没有"子目标检查点"，更没有"哪步已经完成、哪步正在做"的过程记录。大模型本身确实有推理能力，但它缺一个外部骨架来锚定这个能力，一旦中间某个环节失败，前面所有工作直接归零。

你可以这么理解：只靠短期记忆去做八件事，中间接个电话就全线崩盘。人遇到这种情况会把待办写在小本本上，做完一件划掉一件。普通Agent没有这个小本本，Agent-Reach就是来补这个小本本的。

1.2 "触达半径"到底是什么

我项目里定义了一个词：触达半径。它指的是——从用户发起一个目标，到最终完成这个目标，Agent在一次任务生命周期内能覆盖的工具调用层数、外部状态记录范围，以及多轮反馈纠错的能力总和。

市面上很多框架解决的是"模型怎么生成下一步动作"，比如各种Agent框架的Loop机制。但模型生成动作之后呢？工具返回值往哪里放？子任务的完成标准怎么判断？一个工具挂了是重试还是跳过？这些恰恰是决定一个Agent能不能真正跑通复杂业务的关键。

Agent-Reach不碰底层大模型，也不替代现有的调度框架。它在这两者之间加了三个模块：

• Reach Planner：把用户目标拆成可验证的子任务序列；
• Reach Memory：分工作记忆和长期记忆，解决"干着干着忘了前面干嘛"的问题；
• Reach Gateway：所有工具调用的进出口，负责参数校验、超时控制、返回值压缩。

打个比方：大模型是发动机，Agent框架是变速箱，Agent-Reach是导航+仪表盘+行车记录仪的组合。你没有导航也能开车，但跑长途一定迷路；发动机再好，不带仪表盘你连水温爆表了都不知道。

2. Agent-Reach的核心机制：规划、记忆、网关如何配合

2.1 规划器：把大目标折叠成可验证的小步

Reach Planner做的事情不是简单地让模型写一个TODO List，而是强制它输出一个结构化任务图。我们线上用的规划Schema大概长这样：

{ "goal": "整理周报并按人推送", "subtasks": [ { "id": "sub_01", "intent": "定位并读取所有周报数据源", "tool_hint": "file_reader", "acceptance_criteria": "output包含至少2个数据源的文件路径与行列数", "depends_on": [] }, { "id": "sub_02", "intent": "按人员维度聚合各表数据", "tool_hint": "table_aggregator", "acceptance_criteria": "output包含人员维度的汇总表，且有完整性校验字段", "depends_on": ["sub_01"] } ], "checkpoints": [ "sub_01完成后，工作记忆中必须包含数据源清单", "sub_02完成后，必须生成一张可直接转Markdown的中间表" ] }

这个Schema的核心价值，是为每次子任务提供一个可以机械判断的"验收标准"。模型不再说"我大概完成了"，而是必须输出符合验收标准的结构化结果。

我一开始不是这样设计的。最早我让规划器直接输出自由文本计划，结果模型在第三级子任务就开始和前面的目标对不上，有时候甚至自己发明新目标。改成固定Schema之后，结构错误率降了大约六成，排查日志也轻松很多。如果你抄这个方案，我强烈建议连depends_on都让规划器填，而不是让调度器自己推断——因为模型在判断"谁先谁后"这件事上，比规则引擎更灵活，尤其遇到多数据源交叉依赖的时候。

2.2 记忆层：工作记忆与长期记忆不能混着用

很多人做Agent记忆，就是把所有对话历史一股脑塞到上下文里，然后抱怨"上下文窗口不够用"。这是方向错了。Agent-Reach把记忆分成两层：

工作记忆只放当前子任务相关的信息。比如sub_02正在做数据聚合，那工作记忆里就是聚合结果摘要、数据源路径、异常字段清单，最多几千字。前面sub_01读过的完整文件内容通常不在里面。

长期记忆放的是跨任务沉淀的经验：比如"用户的周报文件通常以日期命名""上次做这种任务时，某列字段存在空值"。我们用向量库（线上是Chroma）存这些片段，每次新任务启动时检索Top-3补充到系统提示里，而不是全量塞进去。

这里有个非常实在的经验：长期记忆如果每次检索超过5条，模型反而会被"旁征博引"带偏。我们测试过Top-3到Top-10的不同配置，对简单任务差别不大，但对复杂任务，Top-10的错误率反而比Top-3高了接近一成。原因是很多历史片段有冲突，模型试图"综合考虑"反而自乱阵脚。长期记忆的价值是提供线索，不是提供标准答案。

2.3 网关：工具调用的进出口守卫

网关是我觉得Agent-Reach里最被低估的模块。一个简单的经验：工具返回的原始数据，绝不能原封不动塞进上下文。

举个真实例子。我们接入了一个内部CRM系统的"查询订单"接口，单次返回的JSON有80多KB，包含几百个字段。如果直接把这段JSON抛给模型，接下来好几轮对话，模型都在复读其中几个无关紧要的字段，真正的关键信息反而丢失。我把这个现象称为"上下文毒化"——模型的注意力被海量低价值token稀释了。

网关做的事情有三个：

1. 参数校验：入参先按工具注册表里的JSON Schema做校验，不合法直接返回参数错误，不给模型"发挥"的机会；
2. 超时与重试：统一设定30秒超时和最多1次重试，避免个别慢接口拖垮整个任务流；
3. 返回归一化：大JSON在进入上下文前先做字段级摘要，只保留Top-5数值字段、汇总统计和标记异常的字段，其余全部丢弃。

举个例子，网关把一段80KB的原始订单JSON压缩成三行：

订单总数: 1287，总金额: 562.4万，未发货: 83单，退回: 12单。 热门商品Top5: SKU-441(142单), SKU-208(96单), SKU-107(71单)... 异常: 地址缺失3单，金额为负1单。

模型看到这种东西，比看到几百个字段的JSON清晰得多。做过客服类Agent的人都知道，很多"幻觉"不是模型乱编，而是输入里有大量互相矛盾的杂质数据，模型根本提炼不出有效信息。网关就是挡住杂质的那道滤网。

3. 快速搭建一个可用的Agent-Reach工作流

3.1 技术选型与目录结构

Agent-Reach不是那种需要你从零造轮子的系统。技术选型上，我们用的是Python 3.11 + FastAPI（负责HTTP接口暴露） + LangChain（只用来统一封装各家模型的调用差异）+ Chroma（长期记忆向量库）。底层LLM我们线上接的是长文本模型，你可以根据自己的实际情况换成别的，不影响整体架构。

推荐目录结构如下：

agent_reach/ core/ __init__.py planner.py # 任务规划器 memory.py # 工作记忆与长期记忆 gateway.py # 工具调用网关 config/ reach.yaml # 核心配置 tools/ file_reader.py # 文件读取工具 table_aggregator.py notifier.py # 消息推送工具 main.py # FastAPI入口

这个结构不复杂，但每个模块职责非常清楚。我见过很多Agent项目死掉，就是死在"所有逻辑堆在一个几万行的service文件里"——一旦子任务超过5个，代码根本没法排查。

3.2 配置文件的逐行说明

下面是reach.yaml的一个实际可用版本，我逐项说明为什么这么配：

planner: model: "qwen-long" # 规划用长上下文模型，负责拆解任务和校验依赖 max_subtasks: 12 # 单任务最多拆12个子任务，超过则要求合并 schema_version: "1.4" # 规划Schema版本，便于升级时兼容旧任务记录 memory: long_term_store: "chroma" # 长期记忆存储 top_k: 3 # 每次检索记忆条数 dedup_window: 3600 # 1小时内相似记忆自动去重 gateway: timeout_seconds: 30 # 单次工具调用超时 max_return_tokens: 2000 # 工具返回值摘要后最多保留token数 retry_on_timeout: true # 超时后自动重试一次 max_retries: 1 scheduler: max_parallel: 3 # 无依赖子任务的最大并行数 strict_dependency: true # 有depends_on的子任务必须严格串行

几个容易踩坑的参数：

max_subtasks设太大没有意义。我试过放开到50，模型规划的跨度会急剧变大，子任务之间经常互相矛盾，中后期错误率飙升。实测8到12是性价比最高的区间，如果超过12个，说明用户的目标描述不够清晰，应该先追问再干活，而不是硬拆。

max_return_tokens这个参数很关键。一开始我设成8000，网关压缩力度不够，上下文还是会被大JSON撑着。后来设成2000，模型回答质量反而显著提升，因为上下文里都是精华信息。你可以按自己模型的上下文窗口微调，但原则是"越短越好，够用就行"。

3.3 三个核心组件的最小实现

planner.py里最核心的一点，是让模型输出带验收标准的任务图。我用一段精简代码说明实现思路：

from pydantic import BaseModel class Subtask(BaseModel): id: str intent: str tool_hint: str acceptance_criteria: str depends_on: list[str] class TaskPlan(BaseModel): goal: str subtasks: list[Subtask] checkpoints: list[str] def generate_plan(user_goal: str, context: list[dict]) -> TaskPlan: prompt = f""" 请把用户目标拆成可验证的子任务图。 用户目标: {user_goal} 已知上下文: {context} 要求: 1. 每个子任务必须有可机械判断的acceptance_criteria； 2. depends_on字段必须明确前置子任务； 3. 不要遗漏任何关键步骤，但也不要拆出无验证意义的步骤。 """ raw = llm_call(prompt, schema=TaskPlan) return validate_plan(raw)

gateway.py里最核心的是工具统一调用与返回压缩：

def call_tool_with_summary(tool_name: str, args: dict) -> str: tool = tool_registry.get(tool_name) if tool.schema and not validate_args(args, tool.schema): return f"参数错误: {tool.schema.error_messages()}" raw_result = run_with_timeout(tool, args, timeout=cfg.timeout_seconds) if isinstance(raw_result, dict) or isinstance(raw_result, list): return summarize_to_tokens(raw_result, max_tokens=cfg.max_return_tokens) return truncate_str(str(raw_result), 2000)

3.4 端到端跑通一个例子

我拿"读取本地CSV，统计各省份销售额，生成汇总Markdown，写入result.md"这个最简单的任务来走一遍流程。

第一步，Reach Planner输出的任务图：

sub_01: 读取 data/ 目录下所有CSV —— criteria: 输出文件列表和字段名 sub_02: 按省份聚合销售额 —— criteria: 输出省份-销售额映射表 sub_03: 生成Markdown并写文件 —— criteria: 生成result.md且包含省份表格

第二步，网关收到sub_01的工具调用，file_reader正常返回三个CSV的路径与字段列表，约400 token。

第三步，sub_02执行聚合，返回的原始DataFrame有几千行，网关压缩成"省份Top10 + 合计 + 空值异常数"。

第四步，sub_03生成Markdown，网关返回写入成功状态。

整个过程非常顺滑。你可能觉得这也没什么特别的，但你对比一下普通Agent的做法就知道差距了——很多普通Agent在sub_01返回之后，会把几百行原始数据一直留到对话结束，然后越往后越混乱。而在Agent-Reach里，工作记忆在sub_02开始时已经丢弃了sub_01的原始内容，只保留了"路径和字段名"这个摘要信息。这不是省token的问题，而是让模型始终盯着当前该盯的东西。

4. 实测一周后的边界发现与踩坑记录

4.1 任务粒度太粗导致的"假循环"

上线第一周我就遇到一个鬼打墙现象：日志显示Agent在同一个工具上连续调用了六次，每次返回都一样，但它就是不进入下一个子任务。

一开始我怀疑是模型上下文太长导致"忘了前面的计划"。但打开日志发现，每次调用后，规划器的progress字段根本没有变化，始终停在那句"分析数据中"。问题出在规划器把"分析数据"当成一个整体子任务，没有定义"分析完"的标准。模型确实在做分析，但它做完一轮后，自己也不知道是不是"分析完成"了，于是又调用一次同样的工具。

排查链路大概是这样的：

1. 拉日志，看每轮subtask_id和acceptance_criteria；
2. 发现连续三轮subtask_id相同，且progress描述完全一样；
3. 对比规划器的原始输出，发现该子任务的acceptance_criteria写的是"完成分析"——这是自由文本，模型无法机械判断；
4. 用新的Schema模板让规划器重新生成，要求任何acceptance_criteria必须是可量化的输出，比如"输出包含至少2个维度分组统计的汇总表"。

修复之后，同样的任务只跑了四轮工具调用就正常结束。这个坑的通用性很高：凡是Agent在某个环节反复兜圈子，十有八九是那个子任务缺少可验证的完成标准。解决问题不在模型，在任务定义。

4.2 工具返回值"毒化"上下文的典型案例

另一个让我印象深刻的坑，是接入第三方舆情接口时发生的。该接口一次返回2000多个微博评论，每一条都有十几二十个字段。网关当时还没上线returns_formatter，直接把这堆JSON塞给了模型。结果下一轮模型生成的内容里，反复提到其中一条打车的广告评论，完全忽略了真正的热点话题分析。

我用了一个很土的方法才定位到问题：把同样的输入分别用"全量JSON"和"压缩摘要"喂给模型，对比两者输出。结果压缩摘要模式下，模型能正确总结舆情焦点；全量JSON模式下，模型输出一团浆糊。

网关里加的returns_formatter逻辑是分层摘要：默认只保留每条文本的前80个字符、情绪标签、点赞数和转发数；整体再汇总总量、Top3高热内容、异常标签分布。对于那些平时用不到的字段，直接丢弃。那次之后，我立了一个规矩：任何新工具接入Agent-Reach，必须先过网关的返回压缩测试，过不了不许上线。

4.3 并行子任务的状态隔离问题

并行能提速，但状态隔离做不好，错误率会以指数速度上升。我们遇到过一个问题：两个子任务都依赖同一个本地缓存文件，其中一个子任务写入新版本，另一个读到的却是旧版本，导致最终汇总数据不一致。

排查时我一度怀疑是文件系统缓存问题，折腾好久才发现是逻辑层的问题。修复方式很简单：在depends_on为空的任务里，如果它们共享写路径，就自动加一个隐式锁依赖，让写任务和读任务串行。strict_dependency配置就是这个用途。

现在的经验是：并行只对"纯读操作"放开，比如同时读取多个独立文件；一旦涉及写共享状态，哪怕看起来没依赖，也建议保守串行。并行省下的那几秒钟，跟排查一次数据不一致的代价相比，根本不值。

5. 进阶调优：再上一个台阶的实操经验

5.1 教Agent学会"拒绝"

你可能想不到，一个Agent最重要的能力之一是"拒绝"。我们刚开始做客服场景时，用户问"帮我查一下某客户的银行流水"，我们的Agent没有这个权限，但它会编造一个看起来很像样的流水表。这种幻觉比直接说"做不到"要危险得多。

Agent-Reach里加了一个"可达性判断"机制：每个工具在网关注册时声明数据源、权限级别和适用场景；规划器生成子任务时，会先检查tool_hint对应的工具是否可达，不可达就直接在计划里标记为"blocked"，并要求模型生成为用户解释的替代方案。

同时给模型加了一个置信度阈值：如果用户的目标里包含未注册的系统能力，模型必须在回复中明确说"这个我目前做不了"，而不是继续编排。实测下来，用户满意度并没有下降，反而因为不再收到假数据而更信任系统。这个经验放到通用Agent项目里也适用：Agent的边界感越早建立，后面的调试成本越低。

5.2 冷启动知识注入

新部署的Agent-Reach集群，前几次任务的成功率通常不高。原因很简单：长期记忆是空的，没有历史经验可以参考。我在项目里做了个冷启动方案：把人工整理好的"典型任务执行范例"转成向量存进长期记忆库，每个范例包含：任务目标、任务图、网关摘要、最终结果。说白了就是给Agent一本"标准作业指导书"。

在实际运行中，我还会定期把执行成功的plan样本补充进去。半个月后，长期记忆库里有大约200条优质范例时，同类任务的初始规划错误率下降非常明显。这里给个提示：范例质量比数量重要得多。一条错误的范例被检索出来，会带偏整个后续流程，所以入库前必须人工审核。

5.3 推荐配置与实测数据

我把不同参数下的实测数据放一张表，供参考。测试任务是"多数据源汇总并生成报告"，样本100个，评估指标是"任务一次通过率"和"平均完成时长"：

结论很直观：任务粒度适中、记忆适度、强返回压缩，这三件事同时满足时效果最好。其中一个值得注意的点：max_subtasks从12升到20，通过率反而下降，说明过度拆解会让模型在子任务间互相矛盾。

最后再分享一个排查小技巧：看日志的时候，一定要把每轮子任务的acceptance_criteria一起打出来。很多问题一眼就能看出来——要么标准定得模糊，要么执行根本没达到标准却在硬走下一步。把这个字段纳入日志输出后，我调试Agent的速度至少快了一倍。Agent-Reach这套东西做出来之后我最大的体会是：别急着换更强的模型，先把任务规划、状态记忆、工具闸口这三层做实，复杂度上去了，稳定性照样能扛得住。