企业官网建设流程全解析

当我第一次把大模型接入业务系统的时候，遇到的第一个问题不是模型不够聪明，而是它“够不着”任何东西。聊天能力再强，如果调不了数据库、发不了通知、改不了配置，那它本质上就是个漂亮的玩具。Agent-Reach 这个项目，就是为了解决这个“够不着”的问题而生的。

简单说，Agent-Reach 是一套让 AI Agent 具备“外联能力”的工具层方案。它把外部系统的能力封装成一个个可调用的工具，让模型在对话过程中自主判断什么时候调用、调用哪个、参数怎么填，再通过一条可靠的执行链路把动作真正落地。这个项目前后做了三个多月，期间踩了不少坑，也沉淀出一套可以复用的套路。如果你正在做 AI 应用开发、智能客服、自动化流程引擎，或者单纯想搞懂 Agent 底层机制但不想看一堆晦涩论文，这篇文章应该对你有用。

我尽量按实操顺序来写，从设计思路到核心实现，再到我实际遇到的问题和排查方法，最后聊聊后续还能往哪个方向扩。全程没有“高大上”的空话，全是能抄作业的细节。

1. 项目初衷：为什么做 Agent-Reach

1.1 大模型的核心短板：能说不能做

我相信很多人在第一次接入大模型 API 时都有过类似的体验：模型回答问题头头是道，但一问到“能不能帮我改一下订单备注”“能不能查一下这个工单的负责人”，它就卡住了。原因很简单，大模型本质是个“文本预测器”，它没有手也没有脚，所有输出都停留在文字层面。

我最早做的一个智能客服原型就是这个状态。用户问“我的订单 2233 发货了吗”，模型能解释什么是物流周转、能推测大概需要几天，但它不能真的去查订单系统。你要么把订单数据提前塞进上下文里，要么就得在代码里人为写一堆 if-else 判断来匹配用户意图。前者受限于 token 长度，后者逻辑一多就变成一坨永远维护不完的意大利面。

1.2 “够得着”才是 Agent 和 Chatbot 的分水岭

很多人以为 Agent 就是“更聪明的聊天机器人”，其实不是。真正的分水岭在于：它有没有能力触达外部系统，并且触达后能把结果带回来继续推理。

我把这种能力称为“Agent 的触达半径”（Reach）。一个只有聊天能力的模型，触达半径是零；一个能调用计算器、查天气 API 的模型，触达半径是几百公里；一个能跨系统查询订单、修改状态、触发审批流的 Agent，触达半径就是整个业务链路。半径越大，Agent 能独立完成的闭环任务就越多，这才是它从“玩具”变成“生产力工具”的关键。

1.3 Agent-Reach 的设计目标

做 Agent-Reach 之前我给自己定了三个硬指标。第一，新增一个工具不能超过半小时，最好只写一个函数加一段声明就能接入。第二，执行链路必须稳定可追溯，Agent 调用了什么工具、传了什么参数、拿到什么结果、最终怎么回答的，每一步都要能查得到。第三，不能让工具调用成为安全黑洞，权限边界、参数校验、操作审计一个都不能少。

这三个指标看上去简单，但真正落地的时候每一步都有坑。后面我逐个展开说。

2. 核心架构：让 Agent 真正“够得着”外部系统

2.1 工具声明层：把系统能力翻译成模型能懂的语法

Agent 要做工具调用，第一步不是写工具本身，而是把工具“翻译”给模型看。模型不懂你系统的函数签名，也不懂你的数据库结构，它只认结构化的描述。

我当时选的是 OpenAI 的 function calling 规范，也就是把每个工具描述成一份 JSON Schema。哪怕是接非 OpenAI 的模型，现在市面上主流模型也都兼容这套格式，qwen、glm、deepseek这些国产模型也都支持，通用性很强。

我现在写一份订单查询工具的描述，你可以直接感受一下：

{ "type": "function", "function": { "name": "query_order_status", "description": "根据订单号查询订单当前状态，适用于用户咨询物流进度、发货时间、签收情况等场景", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，通常为数字开头的一串编号，例如 2024001" } }, "required": ["order_id"] } } }

这里有个容易被忽略的细节：description一定要写得足够具体。不只是写“查询订单状态”，还要写清楚“什么时候用、参数是什么、常见的坑是什么”。因为模型是根据这段描述来决定调不调用的，描述含糊，它就会在无关场景乱调用，或者该调的时候不调。

2.2 决策执行层：模型出嘴，系统跑腿

工具声明好了，真正的调用链路由模型自主驱动。整个循环的核心逻辑其实不复杂，就是一个循环：把用户请求和已有的对话历史发给模型；如果模型返回了工具调用请求，就执行对应的工具函数，把结果以 tool 角色的消息追加回消息列表；然后再把更新的消息重新发给模型；直到模型返回纯文本回答为止。

我最初写的第一版循环长这样：

messages = [{"role": "user", "content": "帮我查一下订单 2233 的物流状态"}] while True: resp = client.chat.completions.create( model="your-model", messages=messages, tools=[tool.to_openai_schema() for tool in registry.all()] ) msg = resp.choices[0].message if msg.tool_calls: messages.append({ "role": "assistant", "content": msg.content, "tool_calls": msg.tool_calls }) for tc in msg.tool_calls: tool = registry.get(tc.function.name) args = json.loads(tc.function.arguments) observed = tool.func(**args) messages.append({ "role": "tool", "tool_call_id": tc.id, "content": json.dumps(observed, ensure_ascii=False) }) else: final_answer = msg.content break

这段代码在原型阶段跑得很顺，但放到生产环境之后问题就陆续冒出来了。比如模型偶尔会传入不存在的参数、工具执行结果太长把上下文塞爆、遇到多个工具之间依赖关系时顺序搞错。这些我在后面的踩坑章节里会详细说，这里先把主链路讲清楚。

2.3 结果反馈层：怎么让模型“看见”执行结果

执行完工具之后，把结果回传给模型这一步，我一开始是直接json.dumps整个返回值塞进去，觉得这事就算完了。后来发现，工具返回的数据结构和模型最终回答的质量之间，关系非常大。

如果工具返回一个乱七八糟的大 JSON，里面有嵌套多层、有很多模型根本用不上的字段，那模型在总结时就会犯迷糊，甚至开始胡编。我的做法是给每个工具定义一个“精简展示格式”，只保留模型回答用户问题时真正需要的信息。

比如查询订单，完整数据可能有一百多个字段，但展示给模型的只需要这几项：

{ "order_id": "2233", "status": "已发货", "tracking_company": "顺丰", "tracking_no": "SF1234567890", "estimated_arrival": "2024-09-30" }

这个“展示格式”的设计是我后期才想明白的。它不是简单的数据过滤，而是在帮模型降低“认知负载”。信息越精简，模型越容易给出准确、简洁的回答，同时还能省 token，一举两得。

3. 实操记录：从零搭建 Agent-Reach 的完整链路

3.1 环境与选型：我为什么这么搭

先交代一下我搭这套系统的基础环境，方便你对照。后端用的 Python 3.11 + FastAPI，LLM 用的是兼容 OpenAI 接口的模型网关，也就是我可以在不改代码的情况下随意切换底层模型。工具注册和调用用一个轻量的注册表类管理，没有引入重量级框架。

选 Python 不是因为别的，纯粹是生态好。pydantic做参数校验、httpx做异步请求、structlog做日志结构化，这些库都是现成的，而且社区遇到问题基本都能搜到答案。你如果用 Node.js 或者 Go 也可以，核心设计是一样的，只是实现语言不同。

3.2 最小可用链路：注册工具、模型决策、执行、回传

整个 Agent-Reach 的最小可用版本，其实就是一个注册表加一个主循环。注册表负责管理所有可用工具，主循环负责驱动模型决策。

我把工具注册的代码抽象成了这样一个类：

# tool_registry.py from pydantic import BaseModel, Field from typing import Callable, Any class Tool: def __init__(self, name: str, description: str, parameters: dict, func: Callable): self.name = name self.description = description self.parameters = parameters self.func = func def to_openai_schema(self) -> dict: return { "type": "function", "function": { "name": self.name, "description": self.description, "parameters": self.parameters } } class ToolRegistry: def __init__(self): self._tools = {} def register(self, tool: Tool): self._tools[tool.name] = tool def get(self, name: str) -> Tool: return self._tools.get(name) def all(self) -> list: return list(self._tools.values())

实际注册一个工具就非常轻量：

def query_order_status_impl(order_id: str) -> dict: # 这里是调用真实订单系统的地方，可能是查库，可能是调内部 API order = order_service.fetch(order_id) return { "order_id": order.id, "status": order.status, "tracking_company": order.tracking_company, "tracking_no": order.tracking_no, } registry.register( Tool( name="query_order_status", description="根据订单号查询订单当前状态，适用于用户咨询物流进度、发货时间、签收情况等场景", parameters={ "type": "object", "properties": { "order_id": {"type": "string", "description": "订单号"} }, "required": ["order_id"] }, func=query_order_status_impl ) )

主循环从用户提问开始，逐轮跟模型交互，直到拿到最终回答。就这样，一个能实际“干活”的 Agent 骨架就出来了。我当时跑通第一个真实工具调用的时候，还挺兴奋的，但那种兴奋没维持多久，因为紧接着就撞上了权限和安全的墙。

3.3 权限与安全：给 Agent 戴上缰绳

Agent 能主动调用工具之后，一个很现实的问题马上摆在面前：它会不会调用不该调的工具？比如用户说“帮我把所有订单状态改成已发货”，如果 Agent 刚好有update_order_status这个工具，他可能真的就去调了，这在真实业务里是事故级别的。

我的处理思路是三层隔离。第一层，工具级权限：每个工具标记一个敏感级别，只有经过身份授权且权限足够的会话才能调用。第二层，参数强校验：工具内部用pydantic对传入参数做二次校验，防止模型传了越界值。第三层，操作审计：所有敏感操作的调用记录落库，谁在什么时间通过哪个会话调了什么工具、传了什么参数，全部留痕。

这里我特别想说一下参数强校验。很多人都觉得模型已经通过 JSON Schema 生成参数了，应该不会出错。实际上模型的参数生成是有概率性的，偶尔会出现枚举值越界、字符串里混进特殊字符、数值超出合理范围等情况。你不能指望模型永远不出错，只能在执行层做兜底。我吃过一次亏，模型把一个金额直接传成了负数，要不是校验拦下来，那笔业务就要闹笑话了。

3.4 可观测性：没有日志的 Agent 是定时炸弹

Agent 系统跟传统接口最大的区别在于，它的行为是“非确定性”的。同一个问题，这次可能调一个工具，下次可能调三个工具，中间哪一步出问题，你很难靠猜去定位。所以可观测性从一开始就得设计进去，不是事后补。

我给每次会话生成一个trace_id，贯穿所有日志和工具调用记录。结构化日志里固定包含角色、工具名、参数摘要、耗时、状态码几个字段。后续又接了一个简单的指标面板，统计工具调用成功率、平均往返轮数、单次会话 token 消耗。

这些数据看着不起眼，但真到排查问题的时候价值巨大。有一次某个工具响应特别慢，用户反馈“回复跟卡住了一样”，我打开指标面板一看，那个接口的 P99 耗时已经飙到 8 秒了，问题一眼就定位到了，不用再像无头苍蝇一样乱撞。

4. 踩坑记录与排查技巧实录

4.1 模型“幻觉参数”怎么治

Agent 系统里最气人的问题之一，就是模型会凭空捏造参数。它明明没有查过订单，却可能在调用查询工具时传入一个根本不存在的订单号，还编得煞有介事。这类问题的根源不在执行层，而在于模型在“猜”。

我排查这种问题时，先看结构化日志里工具调用的参数来源。如果参数是用户上一句话里明确提到的，那属于正常的抽取；如果是模型自己补全的，就有风险。针对后者，我的处理办法是让工具函数对“查无此单”的情况返回明确的业务错误信息，再让模型根据错误信息向用户解释，而不是自己编。

另外一个非常有效的办法是：在工具的 description 里写明“如果你不确定参数值，请向用户询问，不要猜测”。别看这句话简单，它真的能降低模型瞎编参数的概率。经验是描述越明确，模型的“乱来”倾向越低。

4.2 上下文被塞爆：工具结果太长怎么办

工具返回的结果是要塞回上下文的，而上下文是有长度限制的。我第一次接入一个数据分析工具时，返回结果有几十万字符，一发回模型就报超限。后来我只能临时把消息砍掉，导致模型一条完整逻辑链都拼不完整，回答质量断崖式下降。

最终解决思路是两级压缩。第一级是工具输出侧的精简展示，就是我在 2.3 节里说的展示格式，只保留关键字段；第二级是结果摘要，对于确实需要返回大量明细的场景，先让摘要模型对数据做一次浓缩，再把摘要放进上下文，原始明细存到外部存储，用户需要时再按 ID 拉取。

还有个办法是给消息列表做“窗口化”处理，只保留最近 N 轮对话和最后一次工具调用结果，更早的历史压缩成一段摘要。这样既不会丢上下文，又能控制 token 消耗。

4.3 循环调用：Agent 卡在死循环里

Agent 有时候会陷入一种非常让人崩溃的状态：反复调用同一个工具，每次都得到相同的结果，然后还会再调一次，好像指望换个姿势能调出新花样。我遇到过一次极端情况，模型连续调了七次查询接口才放弃。

排查之后发现两个原因。一是工具结果里缺少“决定性信息”，模型拿到结果后不满意，就想再试一次；二是主循环没有设置调用次数上限，模型想调多少次就调多少次。

修起来也简单。第一，在主循环里加最大迭代次数限制，我设的是 6 轮，超过就中断并提示用户稍后再试；第二，在工具结果里附上一些明确的终结性描述，比如“订单状态已确认无变化，无需重复查询”。大多数模型看到这种描述就不会继续折腾了。

4.4 超时与并发：别让一个慢接口拖垮整个 Agent

Agent 的响应时间不是一次模型调用决定的，而是“模型调用 + 工具执行 + 再模型调用”的总和。如果哪个工具接口慢，整个对话就像卡住了一样。我第一次上生产就遇到这个问题，一个工具调了外部接口，那个接口偶尔要卡 20 多秒，用户直接等崩溃。

解决方式是给每个工具设置独立的超时阈值，同时把可能耗时的工具改成异步执行。模型先响应“正在查询，请稍候”，等工具执行完再返回结果，这样用户感知上会顺畅很多。另外一个坑是并发：多个用户同时触发同一个慢接口，容易把外部系统打挂。我在工具层加了一个简单的信号量控制，对每个外部依赖的并发数做限流。

4.5 故障速查表

我整理了这段时间遇到的主要问题和对应解法，做成一个速查表，你可以直接保存参考。

5. 项目复盘与后续扩展

5.1 我观察到的效果变化

Agent-Reach 上线跑了一个月之后，我的感受是它把“问答”真正变成了“办事”。以前客服系统只能告诉用户“你的订单查不了，请联系人工”，现在可以直接查订单、查物流、登记售后申请，整个闭环不需要人介入。从数据上看，一个高频场景的“一次解决率”从改造前的 30% 提到了将近 70%，平均会话轮数也从 4 轮降到了 2 轮以内。

我个人印象最深的不是这些数字，而是用户体验上的变化。用户发现这个机器人真的能“办成事”之后，说话方式都变了，从“帮我看看”变成了“那你直接帮我改了吧”。这说明 Agent 的触达半径一旦打开，用户的信任感和使用深度是会自然提升的。

5.2 后续可以怎么扩展

这个项目目前还处于“单兵作战”阶段，也就是一个 Agent 自己决策、自己执行。我接下来的方向是把它往“多 Agent 协作”推进。比如一个负责需求理解的首席 Agent，把任务拆解后分发给负责订单、物流、售后的专业 Agent，再由首席 Agent 汇总结果。

对于刚接触这类系统的朋友，我的建议是先不要一上来就整复杂架构，先把“单 Agent 单工具链”跑顺，再慢慢加工具、加场景。你把一条链路跑通、把日志和监控建好，后面不管换模型还是加功能，都会从容很多。

5.3 一个值得分享的小心得

最后分享一个我在这个项目里的体会：做 Agent 系统，最容易忽视的不是模型调优，而是“边界意识”。工具声明、权限控制、参数校验、可观测性，这些听起来一点都不酷，但真正决定 Agent 能不能从 Demo 走向生产的，恰恰是这些枯燥的工程细节。模型的能力会越来越强，但工程底座稳不稳，始终掌握在你自己手里。