企业官网建设流程全解析

这两年 AI Agent 的风刮得有多大，不用我多说。从 LangChain 到 Dify 再到 CrewAI，框架一个接一个，热搜上 agent 相关的词几乎没断过。我也在这个方向折腾了大半年，从最初拿 LangChain 跑 demo，到后来动手写了一个内部代号叫 Agent-Reach 的项目，中间踩的坑足够写一本小册子。今天这篇就把整个项目从定位、架构、实现到排错的过程一次性讲清楚，尤其是一些文档里不会写的细节，希望能给正在学 agent 开发、或者准备在公司里落地 agent 项目的朋友省点时间。

Agent-Reach 说白了是一个多 Agent 编排与执行框架，同时也是一个可落地的最小实装案例。它能做三件事：把大模型变成能调工具、有记忆、能协作的 agent；把多个 agent 编排成一条可观测的任务流水线；以及用一套评测集持续验证 agent 有没有真的变强。适合谁看？刚入门 agent 开发、被框架选择困难症困扰的人，以及那些已经被线上 agent 的玄学问题折腾到失眠的工程师。

1. Agent-Reach 是什么：项目定位与整体设计

1.1 项目缘起：一个“够得着”的 Agent

名字里的 Reach 我取的是“触达”的意思。市面上的 agent 框架大多解决的是“让模型能调用工具”这件事，但我真正想要的，是让 agent 能够触达三类东西：触达内部系统（数据库、API、工单）、触达知识资产（文档、向量库、历史决策）、触达其他 agent（协作与分工）。这三层触达是 agent 从玩具走向生产力的分水岭。

最初我试过直接用 LangChain 快速搭原型，链式调用确实方便，但一旦业务复杂起来，链就变成了一团乱麻：状态散落在各个节点里，出错之后很难定位是哪一步出的问题，工具调用失败也没有统一的兜底策略。后来我又看了 Dify 这类低代码平台，演示确实漂亮，可视化编排对业务同学友好，但对一个需要深度定制的项目来说，黑盒部分太多，排起错来反而更痛苦。

所以 Agent-Reach 从一开始就定了三个原则：模型无关、工具即插即用、全流程可观测。模型无关意味着今天用 GPT，明天换国产开源模型，核心逻辑不用动；工具即插即用意味着每个工具都是一等公民，注册一个 decorator 就能被 agent 发现；可观测则是所有决策轨迹都留痕，评测与排错都有据可查。这三个原则后来被证明是这次项目里最正确的决定。

1.2 两个关键设计取舍

第一个取舍是“编排”到底放在代码里还是放在配置里。Agent-Reach 选的是混合方案：宏观流程用配置文件声明，微观的单步决策交给模型自己。这样既避免了纯代码编排改需求就要发版的尴尬，又避免了纯配置编排被模型随机性带偏。实际效果是，业务同学可以调整任务顺序，工程师仍然保住了对工具调用和异常兜底的控制权。

第二个取舍是同步执行还是异步事件驱动。最初版本我全写成同步调用，调试方便，但真实场景里一个任务可能要跑十几步，中间还要等模型推理，动辄几十秒，用户等不起，超时重试也特别难写。后来我引入了任务队列，把一步操作拆成一个事件，agent 的“思考”和“执行”解耦。这里想多说一句：agent 项目的复杂度天花板，往往不是模型能力，而是编排层的解耦能力。

注意：如果你的 agent 只是给内部小团队用，单机同步执行完全够，别一上来就搞消息队列。过度设计是 agent 项目最常见的死法。

1.3 框架选型对比：LangChain、Dify、CrewAI 与自研

这块几乎是每个来问我的朋友必聊的。我把 Agent-Reach 的选型结论整理成一个对比表，方便你直接抄作业：

CrewAI 其实我很喜欢它的角色概念，Agent-Reach 早期的多 agent 设计就受了它的启发，但后来我发现它更适合“固定角色固定任务”的场景，一旦任务动态路由，代码就开始别扭。LangChain 则相反，能力太强，强到每个版本都在变，我有两个下午全耗在修第三方依赖的破坏性更新上。

最终结论不是“自研就是好”，而是看你的团队有没有持续投入的意愿。Agent-Reach 选择自研，是因为我们需要把评测、沙箱、权限控制这些东西和编排深度耦合，第三方框架给不了这种自由度。如果你只是想快速验证想法，Dify 或 CrewAI 就够了，别学我一开始就头铁。

2. 核心细节拆解：编排、记忆、工具与安全

2.1 四种主流架构，Agent-Reach 选了哪条路

聊 agent 架构，绕不开四种主流流派：ReAct、Plan-and-Execute、Multi-Agent 协作、Reflection 反思。ReAct 就是“推理-行动-观察”的循环，模型一边想一边调工具，简单直接，适合大部分工具调用场景；Plan-and-Execute 是先让模型产出完整计划再逐步执行，适合步骤多、可预见的任务；Multi-Agent 是把一个大任务拆给多个角色分工；Reflection 则是让 agent 对自己的输出做一轮自我批评再改进。

Agent-Reach 的主干是 ReAct，因为它是这几种里容错空间最大的：每一步都基于上一步的真实观察结果做决策，不像 Plan-and-Execute 那样，计划阶段一旦出错，后面全白费。但纯 ReAct 有个毛病，遇到必须前置规划的任务会显得笨拙，比如“先调研竞品，再写报告”这种，模型可能会调研到一半就开始写。所以我给 Agent-Reach 加了planner模块做任务的路由优先级判断，把它当成 ReAct 循环的“入口过滤网”。

反映到代码上就是两层结构：外层是任务分发，内层是 ReAct 主循环。这比直接套一个复杂框架要清晰得多，出问题时你能很清楚地知道到底是“任务分错了”还是“模型转圈圈”。

2.2 记忆模块：短期、长期与工作记忆的分工

agent 没有记忆就是智障，这一点谁用谁知道。Agent-Reach 把记忆分成三层：会话内的短期记忆、跨会话的长期记忆、以及任务进行中的工作记忆。

短期记忆最朴素，就是对话历史的上下文窗口。难点在于 token 有上限，所以我实现了一个基于重要性的裁剪器：先让模型把每轮对话压缩成一句话摘要，超过阈值时，把最旧的完整消息替换成摘要。这个方案比无脑截断的效果好得多，因为模型能保留关键背景，而不是只剩最后几轮对话。

长期记忆走的是向量检索路线：每次任务结束后，把“用户目标、执行过程、最终结果、坑点”四条记录写入一个向量库，下次遇到相似问题时，先把相关记忆检索出来塞进 context。这块有个小细节：检索出来的老记忆必须明确标注是“历史记录”，不能让模型把它当成当前事实，否则会出现上次任务的遗留数据污染这次决策的情况，我在测试里吃了好几次亏。

工作记忆就是 ReAct 循环里的 observation 分区，不写进长期库，任务结束就清空。简单说，短期记忆负责“现在的对话”，工作记忆负责“当前任务的中间变数”，长期记忆负责“经验教训”。三层分工清晰了，token 效率和准确性都能兼顾。

2.3 Tools 与 Skills：让 Agent 长出“手”

工具是 agent 能力的边界。Agent-Reach 里每个工具都是一个纯函数加一份 JSON Schema 描述，模型通过 function calling 决定调哪个、传什么参。这里有个很多新手会忽略的点：工具描述要写“人话”，而不是写“说明书”。同一个查询接口，你写“queryUserInfo(userId)”模型经常不知道怎么用，写成“根据用户 ID 查询用户的姓名、手机号和会员等级，用于客服身份核验”模型立刻就会了。

Skills 在 Agent-Reach 里是更上一层的东西：一组工具的语义组合。比如“处理退款”这个 skill，实际包含查订单、查库存、校验退款资格、写入退款单四个工具。模型只需要决定“要不要用退款 skill”，具体调哪几个工具由 skill 内部的决策子循环完成。这极大降低了模型在复杂任务上的认知负担，也让我能对高频业务动作做单独的评测和优化。

工具注册代码大概长这样：

@tool.register( name="query_order", desc="根据订单号查询订单状态、金额和商品明细，用于售前咨询和售后处理", params={"order_id": {"type": "string", "required": True}} ) def query_order(order_id: str) -> dict: # 内部走 HTTP 请求或数据库查询 return order_service.get(order_id)

这里我强烈建议工具函数保持幂等，特别是查类型工具。你永远不知道 agent 会在什么情况下重复调用同一个工具，如果每次调用都产生副作用，线上迟早出事故。

2.4 安全护栏与沙箱：给 Agent 装刹车

agent 安全这四个字，很多人以为是后话，其实它应该是地基。Agent-Reach 有三层护栏：权限最小化、沙箱执行、人工审批闸门。

权限最小化指的是每个 agent 只能拿到完成自己任务的最小工具集。客服 agent 能查订单，但绝对不能有改价的工具；数据分析 agent 能跑 SQL，但只能连只读副本。这个用配置声明就好，能挡住大多数“模型突发奇想”的越权操作。沙箱执行针对的是代码生成类工具，凡是 agent 生成的代码或命令，一律丢进隔离容器跑，限制网络、限制文件系统、限制 CPU 时间。这个思路后来也用在一些社区的 agent 工具台上，方向是对的。

人工审批闸门则针对高风险操作，比如发送对外消息、删除数据、执行大额操作。Agent-Reach 实现了一个human_in_the_loop机制：agent 发起请求后进入 pending 状态，对应的审批人会收到通知，审批通过后任务才继续。说实话，这个机制牺牲了一点自动化程度，但它换来的安全边际在真实业务里非常值。安全这事，宁可慢，不能错。

3. 实操过程：从零搭一个 Agent-Reach 最小可用版本

3.1 环境准备与依赖清单

实操部分我按最小可用的标准来，你照着敲一遍就能跑起来。环境方面，Python 3.10+，一个 OpenAI 兼容的模型服务（任何厂家的都行，Agent-Reach 通过 OpenAI 协议对接），加上 Redis 可选（不做持久化可以先用内存）。依赖只需要几个：

pip install openai pydantic pyyaml faiss-cpu

我把项目结构压到最简：

agent-reach/ ├── core/ │ ├── agent.py # ReAct 主循环 │ ├── memory.py # 记忆管理 │ ├── tools.py # 工具注册器 │ └── planner.py # 任务路由 ├── tools/ │ └── order_tools.py # 示例工具集 ├── config/ │ └── agent.yaml # 角色与权限配置 └── eval/ └── test_cases.py # 评测用例

一个能用的 agent 系统，核心代码其实五百行内就能讲完。很多时候复杂度不是代码本身，而是你在代码外做的那些决策。

3.2 ReAct 主循环实现

这是整个项目的心脏，我用精简的伪代码风格展示关键逻辑：

class ReActAgent: def __init__(self, model, tool_registry, memory): self.model = model self.tools = tool_registry self.memory = memory def run(self, task: str, max_steps: int = 8) -> dict: messages = self.memory.build_context(task) for step in range(max_steps): response = self.model.chat(messages, tools=self.tools.schemas()) if response.tool_calls: for call in response.tool_calls: result = self.tools.execute(call.name, call.arguments) messages.append(self._as_observation(call, result)) else: return {"answer": response.content, "steps": step + 1} return {"answer": "达到最大步数，任务终止", "timeout": True}

核心逻辑不复杂：模型输出工具调用请求，框架执行工具，把结果作为 observation 塞回消息列表，让模型看到工具真实的返回再决定下一步。注意max_steps参数，我强烈建议任何 agent 循环都要有这一步，否则模型一旦钻牛角尖，你的 token 就会像流水一样哗哗地烧掉。

工具执行那块有一个容易被忽略的细节：工具返回结果要截断。有的接口能把几万行数据返回给模型，context 瞬间爆炸。我在_as_observation里做了摘要，只保留前 N 条记录加一个总数字段，模型真需要明细会自己去调更细的工具。这就是“工具返回人话化”的思路。

3.3 配置驱动的记忆策略

记忆部分我也给一份可跑的代码，注意这里我们把记忆策略做成配置驱动的，而不是硬编码：

# config/memory.yaml short_term: max_messages: 20 compress_threshold: 15 long_term: store: faiss top_k: 3 expire_days: 30

长期记忆的写入时机建议放在任务整体结束时，而不是每一步都写。我在早期版本里把每一步都灌进向量库，结果检索出来的全是噪声，因为中间步骤的上下文本身就残缺。后来改成“只存完成态”，准确率明显上升。这件事告诉我一个道理：记忆入库的时机，比记忆检索的算法更影响效果。

3.4 评测集构建：怎么证明 Agent 真的变强了

评测是 agent 开发里最容易被拖延、但最不该被拖延的环节。Agent-Reach 的评测集从三个维度来构建：任务完成度、工具调用正确率、过程合规性。

任务完成度看用户目标有没有达成；工具调用正确率看模型选工具和传参对不对，这是 agent 特有的指标；过程合规性则检查有没有越权调用、有没有绕开审批。三种维度合起来，才是一个完整的 agent 能力画像。一个典型的用例长这样：

# eval/test_cases.py { "id": "case_001", "task": "帮我查订单 20240815001 的物流状态，如果是已签收就发短信通知", "expect": { "tools": ["query_order", "query_logistics", "send_sms"], "compliance": ["send_sms 前必须经过审批闸门"], "answer_contains": ["已签收"] } }

评测时我用一个轻量的 runner 逐条跑，统计工具调用序列与期望序列的匹配率。有次优化 prompt 后，任务完成度从 68% 涨到了 82%，但合规指标却掉了，一查发现模型开始自作主张跳过审批直接调发送工具。这就是评测集的反馈价值：能力提升和风险上升往往是同步的，没有评测数据，你根本不知道一次优化到底动了哪块奶酪。

注意：构建评测集时要把“失败案例”也留档。每次线上出问题，都把当时的输入输出沉淀成一条评测新用例，防止同一个坑反复踩。这是我在这个项目里最划算的时间投资。

4. 实战排错手册：这半年我踩过的坑

4.1 连接类错误：一次把团队折腾到崩溃的 RPC 报错

先解释一下热词里反复出现的那个报错：agent rpc error (-1): empty sid and service name。这个错误看起来吓人，其实含义很直白：某个 RPC 调用返回了空的会话标识（sid）和服务名，通常是连接层拿不到有效的目标信息。在我项目里，它发生在 agent 工具层尝试连接内部数据库时，配置里的 service name 没填对，连接池直接把空值抛了出来。

排查思路按三层走：先看连接串本身，确认服务名和接口名有没有传空；再看网络层，确认目标服务是不是真的注册在册，有没有被负载均衡摘掉；最后看超时与重试逻辑，是不是 agent 在上一轮工具调用里把连接池打满了。这类问题的通用解法，是把连接初始化从工具内部剥离出来，做成独立的连接管理器，工具只负责拿连接，不负责建连接。

我还想多说一句：agent 项目里的连接错误，八成不是 agent 的问题，而是底层基础设施的问题。别一报错就怀疑模型和框架，先把错误信息从里到外拆一遍。

4.2 Token 与上下文爆炸

输入 token 突然飙升是 agent 项目的高频事故。原因基本是三类：工具返回没截断、历史消息没压缩、循环里塞入了重复的大段文本。我第一版就吃了这个亏，一次数据分析任务里，模型调了个返回全量数据的接口，单轮上下文直接超了限。

根治思路是分层防空：工具返回强制截断加摘要，历史消息按重要程度压缩，循环外加max_steps硬限制。另外，如果你用的模型支持 embedding，可以在上下文接近阈值时先把最老的消息向量化存起来，而不是直接丢掉。别小看上下文管理，它决定了你的 agent 能连续稳定工作多久。

4.3 Agent 死循环与工具调用失败

模型转圈圈是 ReAct 模式最经典的翻车现场。症状是：同一个工具被反复调用，参数微调一下又调一次，永远不收敛。我排查下来，最常见的诱因是工具返回里带了一个模型想“修正”的值，比如查询返回“暂无数据”，模型不信，反复用不同格式的查询条件重试。

应对手段有三个：第一，加步数上限并且设置“重复调用惩罚”，连续三次同工具同类型参数直接终止循环；第二，在系统提示里明确写“如果工具连续两次返回相同信息，说明当前方案不可行，请换思路或直接回答用户”；第三，工具返回里主动带上“建议下一步动作”字段，引导模型走出死胡同。第三个方法效果最好，因为它不等模型自己顿悟，而是主动给台阶。

4.4 稳定复现与部署避坑：让玄学变科学

最后这条经验非常重要：agent 项目要想从 demo 走向生产，必须解决“不可复现”的玄学问题。我总结了一套组合拳。推理侧把 temperature 调低并固定 seed，虽然不能完全消除随机性，但能显著提高回归测试的稳定度；编排侧每次运行记录 request id，所有工具调用都打日志，方便事后回放整个决策链路；版本侧把模型版本、prompt 版本、工具版本全部固化。三管齐下，线上问题从“出 bug 全靠猜”变成“看日志就能定位”。

这里直接给一份部署避坑清单：

• 生产环境千万不要在工具函数里写死测试环境的地址，我见过这种低级错误上线后把测试库写穿的
• agent 的日志要单独存储，别和业务日志混在一起，否则回放时根本捞不出来
• 定时任务型的 agent 要加幂等键，重复触发不能重复执行副作用操作
• 上线前务必跑一遍完整评测集，哪怕只是改了一个 prompt 单词

这些坑不大，但每一个都真实发生过，也都是可以提前用流程规避的。

5. 后续还能怎么玩：从内部工具到开放协作者

项目跑通之后，我一直在想 Agent-Reach 下一步往哪走，有几个方向我自己已经在试了，写出来给你当参考。

第一个方向是接入 A2A 协议，把 agent 暴露成 AgentCard 形式，让别的系统能发现我们、能发起协作。这其实就是热词里说的“把 agent 暴露出来”，本质是给 agent 定义一套公开接口，像网站给搜索引擎提供 sitemap 一样。我实测下来，两个能通过 A2A 互通的 agent，处理“跨部门工单流转”这种任务比硬编码接口优雅得多。

第二个方向是行业定制。比如电商场景的售前售后 agent，或者把 PDF、报表这类非结构化文档先转成 agent 能识别的结构化 schema，再交给专用 agent 处理。时间序列预测类的任务，用 agent 来管理“数据清洗、特征工程、模型选择、结果解释”这个流水线也很合适。

第三个方向是降低参与门槛。我在考虑把 Agent-Reach 的编排配置做成可视化页面，让不写代码的同事也能自己组装 skill。说白了，agent 这个技术要想真正普及，最后拼的不是模型有多强，而是工具链有多顺手。

我个人在操作中的体会有两条。第一，别迷信框架和模型，agent 项目能不能成，取决于你对业务场景的理解深度和对细节的掌控力；第二，这半年最值钱的产出不是代码，而是那套评测集和排错手册，它们让团队从“被模型行为震惊”进化到了“能预测模型行为”。如果你也在做类似的项目，建议早点开始沉淀自己的评测数据，你的 agent 会因此变得可靠得多。