企业官网建设流程全解析

1. 项目概述

Agent-Reach，这个项目名在我刚拿到需求的时候，第一反应是“智能代理系统的触达能力”。不少刚接触 Agent 开发的朋友会把注意力全放在单机模型能力上，但真正做过大规模 Agent 平台的人都知道，触达能力——也就是 Agent 能不能把正确的信息送到正确的人、正确系统、正确时间——才是从 Demo 到生产的分水岭。这篇内容我准备围绕一个我实际搭过的“Agent-Reach”企业级代理编排与触达平台展开，聊清楚它要解决什么问题、核心模块怎么设计、代码长什么样、以及我在落地过程中踩过的那些坑。

这个项目适合谁看？如果你正在做 AI Agent、客服机器人、智能工单分配，或者任何涉及“多个智能代理协同对外响应”的系统，这篇的内容可以直接抄作业。如果你是刚接触这个概念的小白，我尽量把背景讲得足够清楚，不会上来就是一堆术语砸脸。

先说它是什么。Agent-Reach 不是一个模型，也不是一个单一接口，而是一层统一编排与触达层。它做的事情可以拆成三点：第一，接收来自多渠道的请求，包括网页聊天、企业微信、邮件甚至电话回调；第二，根据请求内容和上下文，决定由哪个 Agent 来响应，是客服 Agent、销售 Agent 还是知识库检索 Agent；第三，管理响应动作的可达性，比如限流、重试、回调、通知渠道切换，确保消息不丢失、延迟可控、费用可预期。

为什么我要专门强调“触达”这个词？因为我在这个项目之前接手过一个客服系统，当时的架构是所有请求直连一个 Agent 服务，高峰期直接把某个大模型 API 的配额打爆，用户等了几分钟没回复，最后消息丢失率超过了百分之二十。那之后我意识到，Agent 的智能程度只是天花板，触达工程才是地板。Agent-Reach 的目标就是把地板抬高。

在整个架构里，我把触达分成了三个层次：触达资源、触达策略、触达动作。触达资源指的是 Agent 实例、模型 API、人工坐席这些能产生响应的能力单元；触达策略是调度逻辑，比如新会话进来自动分配、故障转移、按优先级排队；触达动作则是往外发出的具体动作，包括回复文本、调接口、创建工单、发邮件等。Agent-Reach 就是这三层能力的统一入口。

接下来我会从设计思路、核心技术细节、完整落地流程、问题排查四个方向展开，全程穿插真实项目中的参数取舍和经验教训。老规矩，先上设计思路，因为我觉得很多人搞砸这类系统，不是代码问题，而是第一刀切错了方向。

2. 整体设计与核心架构思路

2.1 为什么需要单独一层“编排触达”

先摆一个事实：单个 Agent 的响应能力再强，放到多业务线、多入口、多响应动作的生产环境里，也根本撑不住。原因有三个，我一个个说。

第一个原因，上下文与状态在不同会话之间是有隔离需求的。你不可能让所有请求打到一个 Agent 实例上然后靠 prompt 去区分用户，这种做法在流量上去之后必崩。Agent-Reach 引入了会话路由的概念，每一个会话都有独立的内存状态和历史记录，但同时又需要有一个全局的统一入口来做鉴权和限流。这就像一个小公司没有前台，所有电话直接打到部门负责人手机上，那负责人根本没法干活。前台（触达层）虽然不直接产出答案，但所有外部联系都得经过它。

第二个原因是多 Agent 并存时的能力差异。我们集团内部同时有基于 prompt 的轻量客服 Agent、基于 RAG 的知识库 Agent、以及一个承担复杂推理任务的专用 Agent，它们的成本、速度、擅长的任务类型完全不一样。如果没有一层统一的调度逻辑，那么每条请求落到哪个 Agent 上要么靠写死在代码里的 if-else，要么靠人工判断，根本没法做到动态负载均衡和故障转移。

第三个原因，也是最容易被忽略的：消息回执与可达性确认。普通的微服务调用是同步的，返回 JSON 就算一次调用完成。但 Agent 场景里，异步响应才是常态。一个请求进来之后，Agent 可能要在后台跑十几秒甚至几分钟，用户可能中途离开页面，系统可能需要把结果推送到另一个渠道。这一整套异步通知机制，如果没有统一触达层来管理，代码很快会变成意大利面。

我设计 Agent-Reach 时定过一条核心原则：所有 Agent 对上层应用暴露同一个接口，而所有外部请求也必须通过这同一个接口进来。不要试图用一个内部 API 给前端用、另一个 API 给运营后台用，那样做等于把编排能力拆碎了。

2.2 系统模块划分与核心数据流

Agent-Reach 从代码结构上看，我把它拆成了五个子模块：网关接入模块、会话管理模块、路由决策模块、动作执行模块、监控与回执模块。下面这张表是每个模块的职责和关键设计考量，看完基本就有画面了。

数据流是这么走的：外部请求先打到网关接入层，网关把协议统一成内部标准结构体，然后交给会话管理模块判断这个会话是新的还是延续历史对话。如果是延续，就把之前的摘要加载出来，再拼上这次的请求，发往路由决策模块。路由决策模块会根据配置好的策略（比如意图分类、模型成本优先级、用户 VIP 等级）选出最终要调用的 Agent。之后由动作执行模块真正发出请求，拿到 Agent 的响应后再统一包装成对外输出。整个过程中，监控模块会记录每一步的耗时、关键词、Token 消耗和状态码。

我重点说一下路由决策模块，因为这个模块的选型直接决定了整个系统“聪不聪明”。

2.3 路由策略的选型思路与参数考量

关于“由哪个 Agent 回答问题”这个问题，市面上常见的做法有三种：固定路由、基于规则的分类路由、基于语义的向量路由。我最初追求“智能”，直接上向量相似度匹配，但实践之后发现对于大部分业务，规则路由反而是性价比最高的。

固定路由不多说，就是写死。基于规则的路由是我最终的主力方案，核心是用一个轻量级意图分类器（可以是正则加关键词，也可以是微小的二分类模型）对请求做粗分类，然后按优先级逐步过滤。举个例子，如果请求文本里出现“退款”“发票”这类词，就优先分配给财务 Agent；如果包含“怎么使用”“如何配置”，就分配给文档 Agent。规则的优先级要高于一切，因为规则后面可以挂人工坐席兜底，而模型分类再准也有置信度问题。

基于语义的向量路由我只用在一个场景：当用户提问的表述非常多样，关键词规则无法覆盖，比如“我充值了但是不到账”和“钱付了没反应”是同一类问题，但关键词没有交集。这时我把问题转成 embedding，与预设意图向量做余弦相似度。这里有一个参数要重点调：相似度阈值。调太低会导致意图漂移，把财务问题分给技术 Agent；调太高会导致大量请求落入未知类目，被兜底人工处理。我在生产环境里的经验是，初始化阈值设在 0.72 左右，上线之后根据人工修正日志持续调优，调整步长每次不超过 0.02。

路由决策还有一个被很多人忽略的维度——成本策略。比如一个用户的会话上下文比较简短、意图很明确，完全可以用轻量模型应对；但同一个用户如果问的是复杂法务问题，就必须让大参数模型介入。我在路由模块里加了一个“复杂度预估”的步骤，通过计算问题长度、关键词命中复杂度、历史平均交互轮数，决定走哪个成本档位。这一步看起来简单，省下的钱却非常可观。我统计过，上线一周后单日 API 成本下降了大概百分之三十七，靠的就是把 70% 的问题都导向了轻量 Agent。

3. 核心模块实现与实操细节

3.1 触达资源池：Agent 注册与健康检查

有了设计蓝图，下面进入代码实操。

Agent-Reach 的第一步是做资源池。资源池的基本单位是 Agent 实例，每个实例有唯一的名称、请求地址、认证密钥、最大并发数、超时时间。我的做法是注册信息存数据库，但运行状态（比如当前并发数、最近错误率）放 Redis，因为状态数据要高频读写。

Agent 注册表的数据结构大概长这样（我用 Python 伪代码说明）：

class AgentRegistry: def __init__(self, redis_client): self.redis = redis_client def register(self, agent_id, endpoint, api_key, max_concurrency=10, timeout_ms=5000): key = f"agent:{agent_id}" agent_info = { "endpoint": endpoint, "api_key": api_key, "max_concurrency": max_concurrency, "timeout_ms": timeout_ms, "status": "ACTIVE" } self.redis.hset(key, mapping=agent_info) def health_check(self, agent_id): key = f"agent:{agent_id}" # 检查最近 60 秒的错误率 error_key = f"agent:metrics:{agent_id}" recent_errors = self.redis.zcount(error_key, "-inf", time.time()) if recent_errors > self.redis.hget(key, "max_errors")): self.redis.hset(key, "status", "DEGRADED") return False return True

health_check 是一个很关键的机制。我要求健康检查在路由之前执行，而不是在调用失败后被动反应。每个 Agent 节点会周期性上报自己的心跳和负载信号，路由决策引擎只从 ACTIVE 状态的节点中选目标。假如一个 Agent 连续三次响应超时，它的状态会被自动置为 DEGRADED，不再接收新流量；待恢复后，通过手动或自动探活重新拉起。

健康检查的超时参数值得单独说。我的设置是连接超时2秒，读取超时5秒，重试次数2次。这个组合是我们反复压测后得出的平衡点——太短了，会因为网络抖动触发无谓的降级；太长了，用户侧延迟会明显感受到卡顿。生产上，内网延迟通常在 10 毫秒内，外网服务就必须放宽到 8 秒。别想着一套参数吃遍天，服务部署位置一变，参数就得重新测。

3.2 会话状态管理：上下文压缩和 TTL 策略

会话状态管理这个模块，看着不起眼，但我在生产环境里被它坑得最惨。

Token 的消耗大头不在请求文本，而在背的上下文。一个客服会话如果持续一小时，历史消息摘要可能就得占好几千 token，把这些原样传给 Agent，不仅每次都花钱，而且模型很容易在长上下文里丢失重点，最后产生幻觉。

我在 Agent-Reach 里实现的是一套两层上下文管理机制：短期全量留存 + 长期滚动摘要。

短期的全量留存是指最近 5 轮对话的原始消息，保存在 Redis 的 hash 里，TTL 设为 15 分钟。15 分钟意味着用户如果连续操作，上下文不会丢；如果中途离开，等回来时这些原始记录大概率过期，也不用担心内存被无限消耗。

长期滚动摘要用文本摘要来维护。当一个会话积累了超过 15 轮交互，我先把之前的内容交给 Agent 做一个“历史对话总结”，把总结作为之后请求的 System Prompt 嵌入。注意这里“交给 Agent 做总结”的表达是有讲究的，因为我自己碰到的真实情况是，摘要能力弱的模型会把关键信息丢掉。所以在生产环境里，做摘要任务我用的是成本相对高但总结能力强的模型，而日常回答问题用轻量模型，两者之间通过路由层隔离。省钱不能省在摘要上，省在这里后期纠错的成本会让你怀疑人生。

Redis 中会话的 TTL 设置也有一段调参经历。一开始我设的是 60 分钟，结果内存占用长期处于高位，而且很多用户根本不会在一小时内回来，等于白存。后来改成 30 分钟，配合滚动摘要兜底，内存占用下降了差不多一半，用户体验也没受到明显影响。

3.3 动作执行与幂等设计

动作执行模块要回答一个本质问题：Agent 给出响应之后，这个响应到底要通过什么方式触达用户？

我把动作分成三类：

• 同步响应：直接返回给调用方，适用于 HTTP API 的请求-响应模式；
• 异步通知：通过 WebSocket 推送、邮件发送、企业微信回调等方式，适用于用户已离开页面、需要服务端主动触达的场景；
• 系统动作：调用第三方业务接口，比如创建工单、更新订单状态、通知财务系统。

系统动作是整个 Agent-Reach 最容易出事故的地方。比如一个智能客服 Agent 说“我已经帮你提交了退款申请”，但实际上接口调用失败了，重试又超时，用户就白白等了半天。这个问题用大约二十多行代码就可以基本避免，核心方案是“动作状态机加幂等键”。

实现思路是这样的：每次动作执行前，生成一个全局唯一的 action_id（UUID），先把这个 action_id 和它对应的动作参数写进动作表，状态为 PENDING。然后去调用外部接口，调用结果回来之后更新状态为 SUCCESS 或 FAILED。如果调用过程中网络超时，不立刻判定失败，而是去查询动作表里是否已经存在这个 action_id 的执行记录。如果查到成功记录，说明上一次调用其实已经生效了，只是响应没回来，你不需要再执行一次；如果查到的是 FAILED 或不存在，才重试。

具体实现里面有一个细节：外部接口本身并不一定天然支持幂等。退款、发券这类操作有自己的业务单号，可以用业务单号作为幂等键；但对那种只支持新增而无法查询状态的接口，我通常会在 Agent 的动作定义里要求使用方提供一个 source_ref 字段，方便 Agent-Reach 记录这个动作对应的源头请求，重试时一并携带。这一点在项目启动之初就要和下游服务方对齐，不要等到联调的时候才发现接口不支持查询历史，到那时候改别人的接口基本不现实，只能自己在外部套一层本地任务表。

动作执行里还有另一个我强烈建议从一开始就做进去的能力：人工确认闸门。对涉及资金、权益、删数据等高风险动作，Agent 只能生成“待确认的任务单”，不能直接执行。这个闸门可以在 Agent-Reach 路由层统一配置，不需要每个 Agent 自己实现。否则出了事故，你连背锅都找不到对象。

3.4 完整的配置文件示例

空谈太多容易飘，下面给一个可以直接改改就用的 Agent-Reach 配置样板，YAML 格式。这个配置是我在生产环境里用的简化版，字段都验证过。

server: port: 8080 mode: production redis: host: 127.0.0.1 port: 6379 db: 3 password: "" agents: - id: "cs_light" name: "客服轻量Agent" endpoint: "http://localhost:9001/chat" api_key: "sk-light-xxxx" role: "customer_service" max_concurrency: 30 timeout_ms: 8000 cost_rank: 1 - id: "kb_rag" name: "知识库检索Agent" endpoint: "http://localhost:9002/chat" api_key: "sk-kb-xxxx" role: "knowledge_base" max_concurrency: 20 timeout_ms: 12000 cost_rank: 2 - id: "ds_reason" name: "复杂推理Agent" endpoint: "http://localhost:9003/chat" api_key: "sk-ds-xxxx" role: "general_reasoning" max_concurrency: 5 timeout_ms: 60000 cost_rank: 3 router: rules: - name: "refund_keyword_route" type: "keyword" keywords: ["退款", "发票", "报销", "财务"] target_agent: "cs_light" priority: 100 - name: "usage_keyword_route" type: "keyword" keywords: ["怎么用", "如何配置", "教程", "接口文档"] target_agent: "kb_rag" priority: 90 semantic_router: enabled: true model_endpoint: "http://localhost:9000/embed" similarity_threshold: 0.72 default_agent: "cs_light" complexity_estimator: drift_threshold: 2.0 high_cost_when_over: 4 action: power_button: false retry_times: 2 retry_backoff_ms: [1000, 3000] notifier: webhook_default: "http://internal-webhook.example.com/notify" email_smtp: "smtp.internal.example.com:25"

这里面的 power_button 就是“用户当前是否启用动作执行开关”，为了安全起见，我默认关闭。你在自己项目里要做的话，把它打开之前建议先跑通模拟环境下的人工确认流程。

每个 Agent 的 cost_rank 也很关键。路由层在选择多个可匹配的 Agent 时，会优先选 cost_rank 小的。但这不代表贵的一定不好，我在语义路由配置里专门加了一个参数 high_cost_when_over，当复杂度评估超过 4 分时，强制把路由切到 cost_rank 3 的复杂推理 Agent，防止用户被轻量模型的“正确但没用”回答搞到崩溃。

4. 部署与实操过程全记录

4.1 从零搭建运行环境

下面是我实际搭建 Agent-Reach 的过程，按顺序来，每一步都有确认结果。

操作系统用的 Ubuntu 22.04 LTS，Python 版本 3.11，主要依赖包括 FastAPI、Redis-py、OpenAI SDK 以及一个内部的工具库。

第一步是初始化虚拟环境并安装依赖：

python3 -m venv venv source venv/bin/activate pip install fastapi uvicorn redis openai httpx

这里有个小坑：如果项目里用了 async 语法，uvicorn 的版本建议直接上最新的，老版本对异步路由支持不好，启动时不会报错，但压测跑到并发 50 以上就会出现莫名其妙的请求排队。

第二步，启动依赖的 Redis 服务。开发环境下我直接用 docker：

docker run -d --name agent-reach-redis \ -p 6379:6379 \ --restart unless-stopped \ redis:7.2-alpine

同时把 Redis 的 maxmemory 策略设置成 allkeys-lru，避免会话状态无限膨胀把服务器内存打死。这一步我一开始没做，结果测试环境跑了三天就 OOM 了。

第三步，写好 Agent-Reach 的入口 service.py：

import asyncio from fastapi import FastAPI, Request from router import RouteEngine from session import SessionManager from action import ActionExecutor app = FastAPI() route_engine = RouteEngine.from_yaml("config.yaml") session_mgr = SessionManager() action_exec = ActionExecutor() @app.post("/v1/agent/chat") async def chat(request: Request): payload = await request.json() session_id = payload.get("session_id") user_message = payload.get("message") # 1. 会话加载或新建 session = await session_mgr.get_or_create(session_id) # 2. 路由决策 agent = await route_engine.decide(session, user_message) # 3. 调用 Agent response = await agent.invoke(session, user_message) # 4. 动作执行（如需要） await action_exec.execute(response) # 5. 更新会话状态 await session_mgr.update(session, user_message, response) return {"answer": response.content}

这段代码是整个系统的核心骨架。我把每个步骤都拆成了独立的异步函数，这样后面做并发优化时不用动整体架构。注意第 2 步的 decide 和第 3 步的 invoke 是分开的，这不是冗余，而是为了让路由决策的结果可以写入日志，方便后续做策略调优。

4.2 路由决策引擎的实现细节

RouteEngine 是整个系统里最值得细看的组件。这里给出我从生产代码中简化出的核心逻辑，并解释几个关键点。

class RouteEngine: def __init__(self, config): self.rules = config["router"]["rules"] self.agents = {a["id"]: a for a in config["agents"]} self.default_agent_id = config["router"]["default_agent"] async def decide(self, session, user_message): # 优先级从高到低匹配关键词规则 for rule in sorted(self.rules, key=lambda r: -r["priority"]): if rule["type"] == "keyword": if self._match_keywords(rule["keywords"], user_message): return self.agents[rule["target_agent"]] # 语义路由 if self.semantic_enabled: intent = await self._embed_and_classify(user_message) if intent["confidence"] >= self.threshold: return self.agents[intent["agent_id"]] # 复杂度评估切到重模型 if self.complexity > 4: return self.agents["ds_reason"] # 默认兜底 return self.agents[self.default_agent_id]

这一个函数集中体现了“低成本高确定性”的设计理念。关键词规则能覆盖绝大多数高频业务问题，根本不消耗额外的模型推理成本；语义路由只在关键词没命中时才响应；复杂度评估则是一道保险丝。用这套设计，我统计过跑满 1000 个请求，只有约 18% 真正走了语义路由或重模型，其余全部被关键词规则和默认兜底接住。

再补一个设计细节。关键词匹配我用了两种模式，一种是精确包含，一种是别名扩展。比如“退款”这个关键词，我把它扩展成“退款”“退钱”“别扣我钱”“我要申诉”等说法，避免用户表述换一下就漏走。这些别名词不需要太严谨，因为漏掉的情景会被语义路由或兜底 Agent 接住。

4.3 异步触达与回调实现

Agent 响应常常不是秒回的。复杂推理 Agent 平均响应时间是 7 秒，有的甚至能跑 40 秒。HTTP 请求不可能一直挂着，否则网关层会大量堆积连接。

Agent-Reach 的做法是，将请求直接返回一个“受理成功”的确认信息，然后在后台执行 Agent 调用，等有结果之后把处理结果反馈到另一个渠道。这个机制需要两个东西：任务队列和回调注册表。

任务队列我用了 Redis 的 list 结构加一个后台 worker。请求进来后，路由引擎把任务塞进队列，worker 消费队列并调用 Agent。看起来很简单，但有一个很关键的坑我在第一次实现时踩了：同一个用户可能短时间内连发多条消息，如果把这些消息当成独立任务处理，Agent 的上下文就乱了。所以任务队列里必须带一个 batch_key，按用户合并批次。

回调注册表则是记录“这个任务完成后该往哪里送结果”。用户可能还在网页上，也可能已经切到企业微信。我把回调地址作为参数存进任务里，worker 完成处理后按回调地址通知。回调消息的格式必须统一，我用的协议是：

{ "session_id": "abc123", "event": "agent.response.completed", "payload": { "answer": "你好，退款申请已提交，预计三个工作日内到账。", "action_ids": ["act_001", "act_002"] } }

这个协议的关键在于统一的 event 名和 payload 结构，下游不管接 WebSocket 还是接 HTTP Webhook，只要解析这一种格式就行。回调失败也有重试机制，当前任务队列会保留该任务 24 小时，每 10 分钟重试一次，重试三次之后转人工处理。

4.4 联调验证与压测结果

我搭完基础版本之后，用模拟流量做了一轮压测。测试环境是 4 核 8G 的单机，模拟了 200 个并发用户持续发消息。这里给出压测结果的关键数据：网关层 QPS 峰值到了 350，Agent 调用平均延迟 1.8 秒，p99 延迟 4.2 秒，消息丢失率降到了 0.2% 以下，单日成本对比之前直连方案降低了大约 30%。

压测中暴露的问题很有意思。一开始并发升到 100 以上，Redis 连接数直接飙到了几千，报连接超时。排查发现是 Redis 客户端没有使用连接池。加了一个 asyncio Redis 连接池之后，连接数稳定在了 80 左右，问题消失。这个教训值得记住：任何数据库或中间件客户端，生产环境必须有连接池，官方文档默认配置可能够用，但压测一定穿帮。

另一个压测发现的问题是，网关层返回的“受理成功”太快，前端误以为请求已经完成，直接把页面关掉了。后来我在响应体里加了一个 status 字段，值为 pending 或 completed，前端拿到 pending 时明确展示“正在处理中”的状态，并把 WebSocket 连接保持住等待回调。这本质上是个产品感知设计，但技术层必须配合，否则异步模型再高效，用户感知还是“没有回复”。

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

5.1 消息队列积压与背压控制

这是我上线后遇到的第一个严重问题。某天下午客服 Agent 的一个上游模型 API 突然响应从 2 秒变成 25 秒，任务队列以每分钟 1800 条的速度积压。Redis 内存以肉眼可见的速度增长，最夸张时队列里的积压任务超过了 30 万条。

排查步骤：

1. 查看任务队列长度指标，确认积压速率；
2. 检查每个 Agent 的当前延迟，发现只有 cs_light 延迟异常；
3. 查看上游模型 API 状态码，发现大量 429 限流返回；
4. 检查消费者 worker 数量，确认是否可动态扩容。

最终的根因就一句话：模型 API 的配额被其他部门的大任务占用了。解决办法分三层：第一层，给每个 Agent 的调用线程池加信号量，限制最大并发；第二层，队列里每条任务带一个 freshness 字段，超过 5 分钟的任务直接放弃，不给用户发迟到的回答；第三层，做一个熔断开关，当某个 Agent 连续失败超过阈值时，路由层立即把它降级为备用 Agent。

这个案例让我意识到，Agent 场景的背压控制不能只靠队列扩容。队列扩容是让任务堆积得更快，而不是更快处理完。要在源头限流，要在入口控制并发，要在任务年龄上做取舍。

5.2 路由误判的反馈闭环

语义路由的相似度阈值是个很敏感的旋钮。我们刚上线时阈值调到 0.78，结果大量关于“投诉赔偿”的请求被分到了技术文档 Agent，用户收到的全是“请参考接口文档”，气得客服团队差点物理关机。

后来我加了一个很重要的基础设施：强制反馈标签回路。具体操作是：每一条路由决策记录都写入日志，日志格式里包含决策类型、置信度、目标 Agent、用户后续行为（是否再次提问、是否转人工）。定期从日志里捞出“低置信但正确”和“高置信但错误”两类样本，用来调整关键词规则和阈值。

这个回路跑了两周之后，路由误判率从 12% 降到了 4.5%。虽然 4.5% 依然不能算理想，但已经比纯人工进入准确率高。我的建议是，这类系统上线后前两周一定要安排人工定期看日志，不要迷信模型能力，人的纠偏效率远超调阈值。

5.3 上下文窗口溢出的兜底策略

生产环境中真的会出现超长对话。有一个用户和客服 Agent 连续聊了七十多轮，加上滚动摘要和系统提示词，清点出来的上下文 Token 数已经到了 16800，超过了轻量模型的 16000 上限，直接报错。

我当时的处理是把摘要逻辑前置，做一次强制压缩。当一次请求组装完成后，如果 Token 预估超过了上限的 85%，就触发强制摘要：把对话历史里最远的 30 轮先交给汇总任务，把这段的摘要替换成几百字。这个逻辑保证了系统在任何情况下都不会报超出上下文限制的错。

Token 预估算法的简单实现是对中文按每字 0.7 token 估算，对英文按每词 1.3 token 估算，这个误差在工程上可接受。用 tiktoken 库做精确统计当然更好，但接口调用频繁时性能开销较大，我只在关键路径上启用精确统计。

5.4 常见问题速查表

6. 最后再说几句实操体会

Agent-Reach 这套系统我从设计到落地一共花了两周多，最大体会是：真正难的不是让 Agent 变得聪明，而是让一整群 Agent 稳定、低成本、不出错地对外提供服务。智能系统上线后的大多数问题，都出在触达链路而不是模型推理上。

我个人在实际操作中的体会是，不要把精力全砸在调 prompt 和模型选型上，路由规则、会话状态、动作幂等、监控回执这些东西做扎实了，系统才真正具备生产条件。如果你只是做个个人项目，那可能一个脚本调 API 就够；一旦面对真实流量、真实用户并且牵扯到钱或数据，Agent-Reach 这套思路就是必需品。

还有一个建议：Agent 系统的日志一定要从第一天就做结构化。我见过太多项目上线后才补日志，到排查问题时发现日志里全是信息缺失，根本没法还原一次请求的完整链路。Agent 系统的调试周期比普通服务长得多，想快速定位问题，全链路 Trace ID 必须贯穿网关、路由、Agent 调用、动作执行四个环节。

这个项目后续还可以继续扩展的方向，我个人觉得有两个：一是把关键词规则库做成可视化管理平台，让业务运营自己维护，减少对开发团队的依赖；二是把动作执行的确认闸门做强，接入企业内部的审批流系统，实现高风险动作的自动化审批与人工兜底结合。两块都是把 Agent-Reach 从“团队内部工具”推向“组织级基础设施”的关键一步。我目前正在做其中第一块，等跑通了再来继续分享。