企业官网建设流程全解析

我一度觉得，把Agent做聪明是最难的。后来做大了半年Agent工程才发现，真正难的是让Agent够得着东西。去年我在公司内部搭一个数据分析Agent，模型侧推理能力没问题，你问它“这个月净新增用户多少”，它能说得头头是道，但最后只会回你一句“建议你查询内部数据库哦”——因为除了Prompt里那几张文字描述，它什么实际工具都摸不到。我管这个问题叫触达难题。为了把它解决，我在项目组里从零设计实现了一套叫Agent-Reach的触达层，覆盖能力注册、语义路由、结果压缩、权限治理这几块。这篇文章就做一个实践向的拆解：Agent-Reach到底解决了什么问题、核心机制怎么设计、最小可跑通的代码长什么样，以及真实接入时我踩过的几个坑。适合正在做Agent工具调用、Function Calling、MCP接入的工程师看。

1. Agent-Reach要解决的触达难题：Agent有脑没手的真相

1.1 “能力很强”不等于“触得到”

很多人有个误解：模型够聪明，自然就会用工具。但大模型本质上是知识型大脑，它不会主动发起外部调用，除非你在系统里给它准备了可执行的能力接口。你让它写一首诗、改一段代码、算一道微积分，它都能干；可你让它去查订单库、调内部风控接口、刷新一个状态位，它就只能靠猜，因为那些数据和服务根本不在它的世界模型里。

我第一版方案没什么花样，就是在System Prompt里塞了十几个OpenAPI的JSON Schema，然后依赖模型的Function Calling机制去选。刚开始demo很惊艳，可工具一多就崩了：Token账单先爆掉，Prompt被一堆Schema灌晕，模型开始“张冠李戴”——明明该调用订单查询接口，它偏偏选了用户画像接口。那种感觉就像给一个人发了一本厚电话簿，让他找出正确号码，结果是每次翻到的都不是想找的那个。

退一步想，问题不在模型，而在缺一层“触达设计”。人干活时，手和脑是分开但又协同的：脑子决定要什么，手负责够到。Agent也一样，你需要的不是把所有接口一股脑塞进脑子里，而是给它配上一条能按需取用的手臂。这条手臂，就是我后来做的Agent-Reach。

1.2 触达问题可以拆成三层

做Agent-Reach之前，我把“触达”拆成了三个层次，这样后续设计才不糊涂：

• 认知触达：解决“知道不知道”。比如模型能不能理解某个业务的含义、数据口径、字段命名规则，这部分主要靠上下文和知识注入。
• 接口触达：解决“能不能执行”。API、数据库、消息队列、文件系统，这些都是实际的手脚，构成Agent与外部世界的物理连接。
• 治理触达：解决“允不允许”。谁有权限调什么、调用会不会超预算、写操作要不要审批、出了问题能不能审计回溯。

大多数Agent框架只解决了接口触达，比如你给Agent配了MySQL连接器或HTTP插件，能跑通了就完事。但认知触达和治理触达往往会反过来咬你一口：上下文膨胀导致模型变傻，权限失控导致误操作。Agent-Reach这个名字里的Reach，我想强调的就是“触达范围”要可控、可管、可量。所以它的定位介于接口和治理之间，同时顺手帮认知层做瘦身。

1.3 为什么不是再做一套MCP

聊到这里肯定有人问：现在不是有MCP（Model Context Protocol）吗？用它不就行了？MCP确实解决了很大问题，它标准化了工具描述和调用的协议，让Agent可以统一连接外部服务。但MCP没有回答另外三个问题：该调哪个工具、能不能调这个工具、调完的结果怎么进上下文。就好比MCP把电话线铺到了Agent脚下，但路由器、接线员、账单系统还得你自己搭。

Agent-Reach在设计上并不排斥MCP，反而可以把MCP定义的能力作为底层数据源纳入进来。它是在MCP之上再加一层调度与治理逻辑，负责把几十个、上百个能力按需、有序、安全地递给模型。这一层是很多项目做到后期才意识到缺的，等你想加的时候，往往已经踩过一轮坑了。

2. 核心骨架三件套：能力注册、语义路由、结果压缩

2.1 能力注册：让每个工具先“签合同”再上岗

Agent-Reach的第一步不是一个接口一个接口地写调用代码，而是先定义“能力契约”。我用的是一份带元信息的能力注册表，每个能力除了基本的调用地址之外，还必须声明这些东西：

@dataclass class Capability: name: str # 唯一工具名，比如 order_query description: str # 面向语义路由的描述，越具体越好 input_schema: dict # 入参JSON Schema output_schema: dict # 出参JSON Schema timeout_ms: int = 10000 # 最大容忍耗时 permission: str = "read" # read / write / approval idempotent: bool = False # 是否幂等，决定能否安全重试 cost_budget: str = "low" # low / medium / high，供路由和预算控制

这块看起来很基础，但它是整个触达层的地基。比如没有idempotent标记，你就无法安全地做重试——某次Agent调用扣费接口超时了，你盲目重试，结果用户被扣了两次钱。这个坑我确实踩过，后来所有非幂等操作一律走审批流，重试逻辑也严格区分“可安全重试”和“只能报错等待人工”。没有permission标记，后面做权限继承和降级就完全没有抓手。

我建议能力注册不要由开发一个人手工维护，要让业务方和模型共同参与：开发填调用细节，业务方补触发场景描述，最后把描述回灌给模型做一轮校验。这样注册出来的工具描述才不是“死文档”，而是能真的被Driving模型理解的东西。

2.2 语义路由：不要让模型在500个工具里大海捞针

第一版我把所有工具的Schema全塞进上下文，结果模型选不准。后来我意识到，工具选择本质上是一个检索问题，不应该让模型来硬扛。Agent-Reach在模型前面加了一个语义路由层：用户意图进来之后，先用Embedding把意图文本和所有能力描述做相似度计算，召回Top-K个候选，再把这个小列表交给模型做最终决策。

这个设计有两个直接好处。第一，上下文开销断崖式下降。原来500个工具的Schema得几万Token，现在只需要5个候选的描述，几百Token，干净利落。第二，准确率上来了。模型不用在无关工具里硬选，只需要在“已经很像的5个”里挑一个，这个决策压力小很多。

再补充一点调参经验：能力描述的质量比向量模型的选择更关键。我试过好几个Embedding模型，最终发现差异不大，真正拉开差距的是描述写法。我后来定了一个规矩：描述必须以动词开头，并且包含典型触发场景，比如“查询指定日期范围内的订单列表，用于数据分析、报表导出、运营看板”。这种描述比秃秃的“订单查询接口”好用得多，语义召回的准确率能差十个点以上。

2.3 结果瘦身：返回100万行Token，模型再强也扛不住

触达之后，还有一道隐形的大山：结果怎么回到上下文。一次SQL查询可能返回10万行数据，你让模型全读完，先不说能不能读，光Token费用就能让项目黄掉。Agent-Reach在结果侧做了强制瘦身，核心策略有三条：

• 字段白名单：每个能力注册时写明哪些字段是模型真正需要的，多余的一律不返回。
• Top N + 摘要：默认只返回前50条明细，并附带聚合摘要（比如总行数、总额、均值），把模型当成产品用户来对待——先给概要，需要细节再下钻。
• 按需二次触达：模型如果觉得信息不够，可以主动发起“下一页”或“看某条详情”的调用，而不是一次性把所有数据都拽回来。

我把这个原则总结成一句话：上下文是算力，也是成本。你塞回上下文的每一个Token，最终都由模型推理和你的账单来买单。所以结果压缩不是优化项，而是必选项。

3. 跑通最小Demo：三十行代码让Agent查询数据库

3.1 用数据类定义能力契约

前面讲的注册表，落地其实不难。我把最小可跑通的核心逻辑抽成一个类，这里用Python示意。首先定义能力契约，一个数据类就够了：

@dataclass class Capability: name: str description: str input_schema: dict timeout_ms: int = 10000 permission: str = "read" idempotent: bool = True

然后注册一个数据库查询能力。我把它包在一个handler函数里，内部走SQLAlchemy连接池查询，返回一个带摘要的字典：

def query_orders_handler(store_id: str, date_from: str, date_to: str) -> dict: rows = db_service.query( "select order_id, amount, status from orders " "where store_id=:sid and created_at between :d1 and :d2 limit 50", {"sid": store_id, "d1": date_from, "d2": date_to} ) return { "total_rows": len(rows), "total_amount": sum(r["amount"] for r in rows), "sample_rows": rows[:50], }

注意这里handler本身已经在做结果瘦身了：只取三个字段、只取前50行、带一个汇总金额。这比把SQL原始结果直接怼回Prompt要理性得多。

3.2 一个最小可用的Reach内核

接下来的核心类做四件事：注册、路由筛选、白名单校验、调用调度。我简化出一个最小版本：

class AgentReach: def __init__(self, embedder): self.capabilities = {} self.handlers = {} self.embedder = embedder def register(self, cap: Capability, handler): self.capabilities[cap.name] = cap self.handlers[cap.name] = handler def route(self, user_intent: str, top_k: int = 5) -> list[Capability]: # 对意图向量化，与所有能力描述计算相似度 scores = [] intent_vec = self.embedder.embed(user_intent) for cap in self.capabilities.values(): cap_vec = self.embedder.embed(cap.description) scores.append((self._cosine(intent_vec, cap_vec), cap)) scores.sort(reverse=True) return [cap for _, cap in scores[:top_k]] def invoke(self, name: str, args: dict) -> dict: # 严格白名单校验：名字不在注册表里直接拒绝 cap = self.capabilities.get(name) if cap is None: raise CapabilityNotFoundError(f"{name} is not registered") # 权限校验与超时控制省略，生产环境必须完整实现 return self.handlers[name](**args)

这个类的逻辑不复杂，但它是整个Agent-Reach的地基。route把几百个能力缩小到5个候选，invoke在入口处挡住了那些模型“编造”出来的工具名，避免幻觉直接穿透到执行层。生产版本我还在invoke里加了超时熔断、调用审计、信号量限流，但这几个扩展点先按下不表，后面的坑里详细说。

3.3 接入LLM后的完整调用循环

有了这个内核，接入LLM就是一层薄薄的胶水。整个循环长这样：

def agent_run(user_intent: str): # 1. 语义路由召回候选 candidates = reach.route(user_intent, top_k=5) # 2. 把候选能力描述发给LLM，让它选择并生成参数 prompt = build_selection_prompt(user_intent, candidates) decision = llm.complete(prompt) # 输出 {"capability": "order_query", "args": {...}} # 3. 白名单校验后调用 result = reach.invoke(decision["capability"], decision["args"]) # 4. 结果压缩后回填上下文 final_answer = llm.complete(build_answer_prompt(user_intent, result)) return final_answer

每一步都在做职责分离：路由层只负责缩小范围，LLM只负责做最终决策，执行层只负责安全调用和瘦身，最后再用一轮LLM把结果组织成自然语言回复。这个循环看起来简单，但它是所有扩展的基点——后面加可观测性、加权限降级、加审批流，都是在invoke这一层挂钩子。

4. 真实接入中的四个坑：超时、连接池、幻觉调用、权限放大

4.1 超时预算：30秒的报表服务，10秒的Agent，怎么办

第一个真实接入的坑来自一个BI报表服务。这个服务平均响应3秒，但P95能到30秒，偶尔还要更离谱。Agent-Reach默认超时是10秒，结果Agent频繁报“工具调用失败”，用户反馈“这Agent怎么这么笨”。

问题根因不是模型笨，而是我没有给每个能力单独设超时预算。不同服务的耗时特征完全不同，你不能用一个全局默认值去要求所有工具。后来我在能力契约里加了timeout_ms字段，给这个报表服务单独设成35秒，同时把超时后的行为从“直接失败”改成“把超时信息作为上下文回传给模型”，让模型自己判断是重试、换策略还是如实告诉用户等待。

这里有个很容易忽略的点：超时不只是技术指标，它还是Agent决策链路上的一个信号。你截断一次调用之后，模型必须知道这次发生了什么，否则它会在失真的信息上继续推理，最后给出一个错得离谱的结论。所以超时处理一定不能静默吞掉异常，要把它结构化地放回上下文中。

4.2 连接池耗尽：Agent一多，数据库先受不了

第二个坑是并发问题。单机demo一切正常，一旦把Agent服务上线，同时跑十几个并发任务，数据库连接池立刻见底，满屏都是TimeoutError: can't connect to MySQL server。

排查链路是这样的：先看日志，发现是连接获取超时；再看监控，数据库最大连接数被顶满；最后定位到罪魁祸首——每个Agent任务在循环里会连续调多次数据库工具，每次调用都新建连接，连接还没归还下一个请求又来了。传统API网关那套连接管理根本适应不了Agent的高频率调用模式。

我做了两件事。第一件，底层连接池配置调大，并允许少量溢出连接：pool_size=20, max_overflow=10。第二件，也是更关键的，在Agent-Reach里加了一层信号量限流，把同一个Agent的并发数据库调用数限制在3以内。这样即使任务再多，数据库侧的负载也是平的，请求最多排队，不会直接被打挂。这个经验后来被我固化成原则：Agent层的限流闸门不是可选项，只要你的Agent会高频触达外部服务，就必须想象一下“五十个Agent同时在喊我”的场景。

4.3 幻觉调用：模型“创造”了不存在的工具名

第三个坑很有意思。某天日志里出现一条错误：

[2025-06-01 14:23:11] agent=billing-agent call=get_user_credit args={"user_id":"u_1024"} -> CapabilityNotFoundError

我一看就懵了，get_user_credit这个工具根本不存在。后来排查发现，是因为某个历史工具改名了，但它的描述没有同步更新。语义路由在向量空间里把用户意图“查用户信用额度”和这个旧工具的Embedding匹配上了，候选列表里有它；模型在生成决策时又不知道这个工具的准确名字，于是按照“想象中的调用方式”编了一个get_user_credit出来。

这个坑的教训有两个。一是语义路由召回的是“相似”，不是“正确”，它只能帮你缩小范围，不能替代白名单校验；二是模型在参数生成阶段依然会幻觉，所以invoke入口的严格校验必须存在，而且校验失败信息要回写上下文，让模型有机会重新选一个真实存在的工具。我后来加了校验失败自动重规划的逻辑：第一轮尝试被拒，系统会自动把错误原因拼进Prompt，让LLM重新决策，而不是直接把异常抛给用户。

4.4 权限放大：只读Agent的一次写操作事故

第四个坑最疼。我们有一个巡检Agent，负责定时检查线上数据一致性，按理说它只需要只读权限。但当时实现偷懒，主Agent把自己的全部权限原样继承给了子任务，等于一个巡检员同时拿着刘海的钥匙。某天它因为数据判断错误，调用了一个“清理临时表”的写接口，把某张本不该动的业务临时表清掉了一半。

自那以后，我在Agent-Reach里定了几条死规矩：

• 任务级权限降级：创建子Agent时，权限只允许从读降到读，任何写权限都必须在任务创建时显式声明并审批。
• 二次确认机制：所有非幂等写操作，即使调用方声称自己有权限，也要进入审批队列，由配置的策略决定是自动放行还是等人工确认。
• 触达审计：每一次触达都落日志，记下Agent身份、工具名、参数摘要、执行结果、耗时、费用估算。

下表是我现在统一的权限分级模式，所有Agent接入时必须先选档：

权限模型不复杂，但你必须在一开始就把它做进触达层的骨架里，而不是事后补。事后补就等于裸奔过一段时间，你永远不知道那段时间里发生过什么。

5. 从单Agent到Multi-Agent：把Reach升级成触达协作层

5.1 共享能力池：按角色分配触达级别

单Agent跑通之后，自然要往Multi-Agent方向走。你会发现很多能力是多个Agent共享的，比如订单查询、用户信息查询、库存状态查询。如果每个Agent各写一套连接，一年后就是一堆不可维护的意大利面。

Agent-Reach到这一步升级成了共享能力池：所有能力在中心注册，各Agent通过角色来申请使用权限。比如数据分析Agent只能read-only调订单接口，运营Agent在任务审批通过后可以read-write调配置接口，风控Agent则必须走approval-required。升级之后，新Agent接入成本从“研发一周”降到“配置半小时”，权限变更是改角色配置而不是改代码。

5.2 触达链路可观测：一次失败能回放到具体哪一步

Multi-Agent最怕的是“事故无法定位”。两个Agent协作完成一个任务，中途某个触达失败了，你根本不知道是谁调的、调了什么、为什么失败。Agent-Reach从一开始就统一打了触达日志，每个调用一串trace_id，记录了agent_id、tool、args_hash、status、latency_ms、cost。出了问题时，按trace_id一查，一次触达从进入到返回的完整链路就摆在那里。

有一回线上积分数据异常，我靠一笔积分发放事故的trace回放，发现是某个子Agent在权限继承阶段错误地获得了写权限，执行了一笔本不该执行的发放操作。20分钟就定位到根因，而如果还是在裸调用开放口、连日志都没有，这种事故大概率要排查一整天。

5.3 下一步：能力市场、触达SLO、保持薄层

再往后，Agent-Reach已经可以往更多方向扩展。我目前在尝试的包括：把能力描述做成一个“能力市场”，让业务方自助注册并订阅；给高频触达能力定义SLO，比如订单查询接口P95必须小于300毫秒，不达标自动告警；把成本预算细化到每一次触达，让每个Agent的运营成本一目了然。

不过要提醒自己别过度设计。Agent-Reach的价值在于它是一层“薄薄的血管”，把Agent和外部世界安全地连起来，而不是变成一个大而全的中台。一旦你开始往里塞业务逻辑，它就会从触达层退化成一个业务网关，那才是灾难的开始。

我对Agent-Reach的整体看法是：它不是某个特别前沿的模型技术，而是给Agent工程补上的一层基础设施。Reach这个词很有意思——触达。真正有用的Agent，不取决于它能记住多少知识，而在于它在需要的那一刻，能不能恰好够得到那个应该调的服务。能触达一次不算本事，能稳定、合规、可审计地触达一万次，才算把Agent真正落地了。

最后给一个小建议：如果你也想搭类似的东西，别急着把几十个工具一次性接完。先选两三个最有代表性的业务接口，把注册、路由、压缩、审计这四件事完整跑通，再慢慢往外扩建。触达层这种地基类系统，最忌讳一上来就铺大摊子，小而稳才能走得远。