企业官网建设流程全解析

我最早做 Agent-Reach 这个项目，是因为被一个特别现实的问题逼到墙角：模型已经能写出非常像样的文案、能拆解复杂问题、能给出看起来头头是道的建议，但真要让它在实际业务里产生价值，它却什么都够不着。它没法帮你把一封客户投诉邮件转化成工单，没法帮你查一下今天订单有没有异常，更没法在 Slack 里直接拉一个群把相关人拽进来。所有大模型都像是只有大脑、没有手和脚的人，聪明，但动不了。

后来行业里给了这种能力一个名字，叫 Tool Use，或者 Function Calling，但我觉得真正贴切的词是“触达”，Reach。Agent 能不能在真实世界里做成事，核心不取决于模型多聪明，而是它能不能触达那些真正承载业务信息的系统。Agent-Reach 这个名字就是这么来的——它是一套帮 AI 智能体打通外部系统、把“想法”变成“操作”的触达层框架。

这篇文章我会把 Agent-Reach 从设计动机到架构拆解到落地代码，完整讲一遍。包括为什么触达层值得单独做成一个项目、工具协议应该怎么定、权限怎么控、上下文怎么省、遇到模型反复调用同一个工具时怎么排查。不管你是正在做 Agent 应用的工程师，还是准备在公司内部落地智能体的技术负责人，这篇文章应该能帮你少踩不少坑。

1. 项目定位与核心思路

1.1 为什么 Agent 的价值卡在“触达”上

先看一个典型场景。你让一个 Agent 帮忙处理售后：用户说“我上周买的耳机充电盒丢了，能补买一个吗”。模型很快就能理解用户意图，并生成一段回答：“根据您的订单记录，您于上周购买了 XX 耳机，配件充电盒可以单独购买，价格是 XX 元，建议您在官网配件页面下单。”

看起来没问题，但仔细想想，这段回答里没有任何一个动作是真实发生的。订单记录是模型自己编的还是查出来的？充电盒有没有库存？价格是不是过期的？甚至用户到底买没买过这个耳机？全都取决于模型是否真的去触达了订单系统和库存系统。如果没有触达，这就是一段看起来专业但可能是幻觉的废话。

这就是 Agent 与传统聊天机器人最本质的差别。聊天机器人负责“说”，Agent 负责“做”。而“做”的第一步，就是访问数据、调用接口、操作界面——也就是触达。触达能力决定了这个 Agent 是只能陪聊，还是真能干活。

我在做 Agent-Reach 之前，用过不少 Agent 框架。它们大多把精力放在编排和推理上，比如怎么拆解任务、怎么规划步骤、怎么让模型调用工具。这些当然重要，但真正难的是底层那层“连接”：每个系统的 API 风格不一样，鉴权不一样，数据结构不一样，有的要轮询，有的要回调，有的会限流，有的会时不时挂掉。如果把这些细节全塞给上层的规划逻辑，Agent 就被拖死了。

1.2 Agent-Reach 解决什么问题

Agent-Reach 不解决模型怎么思考的问题，它解决模型怎么行动的问题。说得直白一点，它是一个位于模型和外部系统之间的触达层，把零散的系统接口封装成 Agent 可以稳定、安全、可控使用的工具集。

这个触达层要干的活主要有四件：

第一，统一协议。不管背后接的是 REST API、GraphQL、数据库、命令行还是内部系统，都给 Agent 呈现一套统一的工具契约。模型不需要知道下单接口的参数名是 orderId 还是 order_id，也不需要关心鉴权是 JWT 还是 OAuth。它只需要知道，有个工具叫“查订单”，输入订单号，返回订单信息。

第二，权限边界。不是所有工具都该被 Agent 无限制调用。查订单可以，删订单绝对不行；读客户资料可以，导出全部客户列表不行。触达层是天然的权限闸门，可以在工具外侧做细粒度的授权控制，模型只管按用户指令发起调用，能不能调、调到什么程度，由触达层说了算。

第三，稳定性保证。外部系统是不可靠的，第三方 API 会限流、会超时、会返回奇怪的数据。触达层需要在模型和这些不稳定因素之间建立缓冲：重试、降级、熔断、幂等、日志，这些脏活累活不应该让模型编排逻辑去处理，否则 Agent 的推理会变得一团糟。

第四，可观测性。Agent 一旦开始调用真实系统，你必须有完整的调用审计。模型在什么时候调用了什么工具、传了什么参数、外部系统返回了什么、耗时多少、花费多少 token，这些都要在触达层统一记录。否则出事了只能对着空气排查。

如果你去看现在市面上的 Agent 框架，它们确实也提供了 Tool 抽象。但大多数场景限制在调用几个公开 API，真正到企业内部复杂系统时，工具数量一多、权限维度一多、稳定性要求一高，通用的那块就不够用了。Agent-Reach 的理念就是把这层独立出来，做成一个基础设施。

1.3 适合谁、解决谁的痛点

这个项目最适合三类人。

第一类是正在做 Agent 应用落地的工程师。你已经跑通了大模型对话，但遇到“怎么让 Agent 安全地操作企业系统”这个难题，需要一套可参考、可落地的触达层设计。

第二类是公司的技术负责人或者架构师。老板让你评估“我们能不能用 Agent 优化业务流程”，你需要的不是又一个大模型封装，而是搞清楚 Agent 与现有系统之间的边界怎么划、权限怎么管、出问题怎么追踪。Agent-Reach 的设计思路可以直接作为方案评审的框架。

第三类是独立开发者或者 AI 应用创业者。你自己手里有几个服务，想做一个能干活的小助手，但又不想把每个系统的对接逻辑到处复制粘贴。用 Agent-Reach 这类思路，可以一次性建立自己的工具注册表，后续加新能力就是加一个函数的事。

2. 整体架构与方案选型

2.1 触达层在整个 Agent 系统中的位置

要理解触达层的定位，得先把一个完整的 Agent 系统拆开看。从顶层往下大致是四层：

模型层是大脑，负责理解、推理和决策，它决定下一步要调用哪个工具、传给什么参数。编排层负责任务的拆解和执行循环，比如 ReAct 模式里“思考-行动-观察”的循环，就由这一层驱动。触达层就是我们说的 Agent-Reach，它接收编排层的指令，把抽象的工具调用翻译成具体的外部系统操作。系统层是最底层的真实业务系统，包括各种内部 API、数据库、第三方服务、消息平台等。

很多项目从模型层到编排层做得很完善，但触达层往往被随意处理，直接用一段代码调用 requests.post 就完事。短期看挺爽，一旦工具数量超过 20 个、接入系统超过 5 个、使用 Agent 的人超过 3 个，问题就会集中爆发：工具描述不一致导致模型经常调用错、权限控制散落在各处、出错日志无法关联、加一个新系统要改上一周的代码。

Agent-Reach 的核心思想，就是把“模型调用工具”这件事当作一个正式的接口契约来管理，而不是期待模型和外部系统能心有灵犀。

2.2 协议设计：为什么要先定义统一工具契约

Agent 调用工具的方式，本质上不是命令式编程，而是“模型根据描述做选择”。所以工具契约里最关键的不是参数定义，而是描述文本。模型能不能在合适的时机选对工具，很大程度上取决于工具的 name、description、参数说明写得是否清楚。

一个标准的 Agent-Reach 工具定义包括以下字段：

name 是工具名，要简短且动词开头，比如 get_order、create_ticket、send_message。description 说明这个工具做什么、什么时候用、什么时候不要用，这是模型判断的依据。parameters 是 JSON Schema 格式的参数定义，包括每个参数的名称、类型、是否必填、含义。permissions 声明这个工具需要的权限等级和适用范围，触达层据此做调用前检查。idempotent 和 rate_limit 字段标记工具是否幂等、限流策略，供调用层统一处理。timeout 给外部调用设置合理的超时时间，避免 Agent 长时间卡在等待上。

这里有个容易忽略的细节：工具名和参数名要站在模型的视角去设计。比如你内部系统里把客户叫作 client，但模型在理解用户说“顾客”、“客户”、“用户”的时候，哪个命中率最高？显然 customer 更通用。不要为了贴合内部系统命名而牺牲模型的识别准确率。触达层是翻译器，不是裸奔的内部接口。

另外，参数描述也容易被忽视。很多开发者写 JSON Schema，参数只给一个名称和类型就完事，模型全靠猜。实际上模型对自然语言的描述理解能力很强，你应该写清楚参数的取值范围、格式约束、默认值，甚至给一个示例值。比如订单号字段，写作“订单号，格式为 16 位数字，例如 2025070812345678”和只写“订单号”，模型调用成功率的差距是肉眼可见的。

2.3 注册表与权限模型

Agent-Reach 里有个核心组件叫工具注册表 Tool Registry，所有可被 Agent 调用的工具都集中注册在这里。注册表充当两个角色：一是给模型提供可用工具的清单，二是给运行时提供查找和鉴权的中枢。

每次模型发起调用时，流程是这样的：编排层拿到用户任务，从注册表拉取全部或者部分工具描述，连同系统提示词一起发给模型。模型在生成回复时，如果决定调用工具，会返回一个结构化的调用请求，包含工具名和参数。触达层收到请求后，先去注册表里校验这个工具是否存在、参数是否符合 JSON Schema，然后做权限检查，再执行对应的函数，最后把结果格式化后返回给编排层，由编排层把结果塞给模型继续推理。

这个流程看起来简单，但权限模型要想清楚。Agent-Reach 里的权限不是一把梭，而是区分不同维度。用户维度是指当前对话的发起人是谁，普通员工和运营管理员能用的工具肯定不一样。工具维度是指动作本身的危险程度，查询类工具默认开放，写操作工具需要额外的确认机制，删除类工具应该直接禁用或者双重审批。数据维度是指同一个工具在不同数据范围上的访问权。比如“查询订单”这个工具本身是中性的，但普通客服只能查自己客户的订单，主管才能查全部订单。

我建议在执行层用装饰器或者中间件的方式来实现这套权限，而不是在工具函数内部到处写 if-else。避免权限逻辑和业务逻辑耦合，后续审计和改规则都方便。

2.4 技术选型的取舍：语言、同步异步与事件驱动

Agent-Reach 的技术栈选择上，我最终选了 Python 为主，这是基于生态的权衡。目前几乎所有主流大模型的 SDK、Function Calling 支持、LangChain 之类的编排工具都优先支持 Python，周边设施最全。如果你的团队技术栈偏 Node，也不是不行，但需要自己多承担一些兼容工作。

触达层本身建议做成异步事件驱动。原因有两个：外部系统调用天然是 IO 密集操作，同步等待等于浪费 CPU；Agent 执行过程中经常需要同时拉取多个系统数据，比如既要查订单又要查库存又要查物流，并行比串行快好几倍。

不过我要提醒一点：异步虽好，但不要让 Agent 的编排层直接面向异步细节。编排层只负责“决策下一步做什么”，触达层负责“执行并返回结果”。把 IO 并发、超时、重试全封装在触达层内部，上层看到的始终是一个简单的 await tool_call 接口。

3. 核心细节解析与实操要点

3.1 工具描述怎么写，模型才不容易乱来

我见过太多人栽在工具描述上。直接拿着 API 文档往工具描述里抄，结果模型要么在无关的场景下误调，要么对参数含义理解偏差。

先说工具 description 的写法。好的描述应该包含三个部分：这个工具是干什么的；在什么场景下使用；在什么场景下不应该使用。最后一部分特别重要，它能防住很多误用。比如你做了一个 get_order 工具，description 里如果只写“查询订单”，模型在用户说“我要退款”时，可能就会先调 get_order 看订单信息。这不算错，但如果你的系统里其实有专门的退款申请入口，模型却不知道，它就会笨拙地先查单再硬编回复。所以更准确的描述是：“查询指定订单的详细信息。当用户询问订单状态、物流跟踪、购买明细时使用。当用户要求发起退款或售后申请时，不要使用此工具，改用 create_refund_request。”

再说参数定义。JSON Schema 有丰富的表达能力，类型、枚举、pattern、min/max，这些约束一定要用上。凡是参数有明确取值范围的，都要列清楚。这不仅能帮模型生成更准确的参数，还能在调用前拦住一部分非法参数。

最后提一个细节：工具的数量要控制。给模型的工具清单不是越大越好。模型在太多工具里做选择时，准确率会下降，而且工具描述的 token 也要计入上下文成本。我在 Agent-Reach 里引入了按需加载机制，根据用户当前的意图先粗筛一个工具子集，再把它发给模型。比如用户提到“订单”，就优先带出订单相关工具，而不是把所有 80 个工具全塞给模型。

3.2 参数校验与上下文压缩：别让模型被外部数据填满

Agent 调用工具之后，外部系统的返回值会作为“观察”结果，连同之前的对话历史一起再发给模型，进行下一轮推理。这里有个特别坑的地方：返回数据如果太大，上下文会迅速膨胀，导致多轮工具调用之后，token 成本爆炸，模型反而会“淹没”在海量数据里。

一个典型的失败案例：Agent 调用 get_order 拿到一份包含几十个字段、几百行物流轨迹的订单对象，然后全部返回给模型。下一轮模型需要从中提取用户问的那一个信息，不但浪费 token，还可能被无关字段干扰。

Agent-Reach 处理这个问题的思路，是在触达层截断和重塑返回数据。每个工具都要定义一个 result_shape，即返回给模型的最小必要字段。查询订单，只返回订单状态、商品名称、金额、预计送达时间，足够模型回答“我的货到哪了”。而不是把数据库里那条完整记录原样吐出来。内部需要完整数据，那就把完整数据放在独立存储里，需要时再调专门工具获取。

参数校验也是同步进行的。每收到一次工具调用请求，先用 JSON Schema 校验。校验失败直接返回结构化错误，比如“参数 order_id 缺失，应为 16 位数字字符串”，模型看到这种错误提示后通常能自行纠正参数，重新发起调用。这比它调用失败后自己闭着眼睛盲猜要靠谱得多。

3.3 重试、幂等与超时：触达层必须替模型扛住脏活

外部系统不稳定是常态，Agent 调用第三方 API 时，超时、5xx、限流都是家常便饭。这里有个决策要明确：这些异常，不应该让模型来学习怎么处理。模型擅长推理，但不擅长处理网络超时的重试退避策略。触达层应该把这些统一吞掉。

重试策略要区分错误类型。对于超时和 5xx，可以重试，但要配合指数退避和抖动，避免雪崩。前两次重试间隔通常设为 1 秒和 3 秒，超过三次仍失败就放弃，并返回给模型一个结构化的错误信息：“get_order 调用失败：上游系统超时，已重试 3 次。请告知用户稍后再试。”对于 4xx 错误，一般是参数或权限问题，重试没有意义，应该直接返回错误，让模型纠正参数或者换工具。

幂等这件事很多初做 Agent 的人会忽略，但它极其关键。模型如果第一次调用 create_ticket 后网络中断，它没收到结果，很可能再次发起同样的调用，导致工单被创建两次。解决办法是给每个工具调用请求生成一个调用链 ID，如果工具注册表里声明了这个工具是幂等的，触达层内部就会根据请求内容生成幂等键，落到存储里。发现重复的幂等键，就直接返回第一次调用的结果，而不是重复执行。对于 create_order、create_ticket、send_message 这类会产生副作用的写操作，幂等处理是必须的。

超时设置也不能一刀切。读操作比如查订单，3 到 5 秒就够了；写操作比如导出一个大报表，可能需要 30 秒甚至异步转成任务。触达层允许每个工具配置自己的超时策略，不能用一个全局 timeout 硬扛。

3.4 可观测性与审计：Agent 出问题时唯一的救命稻草

Agent 系统一旦接入真实业务，最怕的就是“黑盒”。模型在对话里声称自己已经发送了邮件，但用户没收到。这时候如果没有完整的调用审计日志，你根本不知道问题是出在模型误判，还是邮件服务故障，还是工具参数传错。

Agent-Reach 在触达层强制每个工具调用都记录标准的审计事件，至少包括以下内容：事件 ID 和调用链 ID，用于关联同一个 Agent 任务内的多次调用；时间戳、用户 ID、会话 ID，说明是谁在什么时间发起的；工具名和完整参数，注意这里记录的是原始参数，而不是脱敏后的，便于排查，但敏感字段在日志里要加密存储；外部系统返回的状态码、耗时和响应摘要；token 消耗情况，便于核算成本和定位异常消耗。

有了这套日志，排查 Agent 问题时就像看分布式调用链一样清晰。用户说“Agent 乱说话了”，你拉出调用链一看，模型在第二步错误地选择了 send_message 工具而没有选 create_ticket，问题一目了然。

4. 实操过程：让 Agent 自动完成一条业务闭环

4.1 场景设定：客服工单自动处理与通知

前面讲了不少设计思路，现在用一个完整场景把这些串起来。我选一个比较典型的落地案例：客户在电商平台申请退货，Agent 需要查询订单、校验退货条件、创建售后工单、给运营发通知。四个动作，涉及两个内部系统和一个消息平台，可以比较好地演示触达层的价值。

这个场景做闭环需要注册四个工具：get_order，查询订单详情和状态；check_return_policy，根据商品类目和购买时长判断是否支持退货以及退货条件；create_refund_ticket，在售后系统创建退货工单；send_message，向指定接收人发送一条站内通知或者 IM 消息。

4.2 注册工具：定义 JSON Schema 与处理器

工具定义我直接用 Pydantic 和装饰器风格来做，维护起来很直观。

from pydantic import BaseModel, Field from agent_reach import register_tool, ToolContext class GetOrderParams(BaseModel): order_id: str = Field( description="订单号，16位数字字符串，例如 2025070812345678", pattern=r"^\d{16}$" ) @register_tool( name="get_order", description="查询指定订单的详细信息。当用户询问订单状态、物流跟踪、购买明细时使用。当用户要求发起退款或售后申请时，不要使用此工具。", params_model=GetOrderParams, permissions=["order:read"], idempotent=True, timeout=5.0, ) async def get_order(params: GetOrderParams, ctx: ToolContext): order = await ctx.call_internal_api( "GET", f"/api/orders/{params.order_id}" ) return { # 只返回对模型必要的最小字段 "order_id": order["id"], "status": order["status"], "product": order["product_name"], "amount": order["amount"], "purchased_at": order["created_at"], "esd": order["estimated_delivery"], }

这里有几个细节要展开说。get_order 的 description 里我特意加了一句“不要使用此工具”的场景，目的是引导模型在用户表达退货意图时，优先选择 create_refund_ticket。这比单纯依赖模型的常识判断要稳得多。

result_shape 的控制是通过 return 内容实现的。我要强调的是，return 里不要带 status 为 raw 的完整对象，只返回字段子集。这是避免上下文膨胀最直接的手段。

再看创建工单的工具，写操作和幂等处理是关键。参数里有一个 client_request_id，这个字段是外部传入的请求标识，用作幂等键。用户第一次申请退货时，Agent 生成一个随机 ID；如果因为网络问题重试，同一个 ID 对应的请求触达层不会重复创建工单，而是直接复用结果。

class CreateRefundTicketParams(BaseModel): order_id: str = Field(...) reason: str = Field(description="退货原因，尽量从用户原话中提炼") client_request_id: str = Field( description="客户端生成的幂等标识，格式为UUID", ) @register_tool( name="create_refund_ticket", description="在售后系统中创建退货工单。当用户明确表示退货、退款、换货需求时使用。此操作会真实创建工单，需用户已确认发起申请。", params_model=CreateRefundTicketParams, permissions=["after_sale:write"], idempotent=True, timeout=8.0, ) async def create_refund_ticket(params, ctx): idempotent_key = f"create_refund_ticket:{params.client_request_id}" cached = await ctx.get_idempotent_result(idempotent_key) if cached: return cached result = await ctx.call_internal_api( "POST", "/api/after-sale/tickets", json={ "order_id": params.order_id, "reason": params.reason, } ) await ctx.save_idempotent_result(idempotent_key, result) return result

4.3 编排策略：一个 ReAct 循环的最小实现

工具注册好之后，需要一个简单的编排循环来驱动 Agent。我不打算引入重量级框架，直接用一个精简的循环就能讲清楚触达层和编排层如何协作。

async def run_agent(user_message: str): messages = [{"role": "system", "content": SYSTEM_PROMPT}] messages.append({"role": "user", "content": user_message}) for _ in range(MAX_STEPS): resp = await llm.chat(messages, tools=tools_schema) msg = resp.message if msg.tool_calls: messages.append(msg) for tool_call in msg.tool_calls: result = await tool_router.execute( tool_call.name, tool_call.arguments, user_id=current_user.id, ) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result), }) else: return msg.content return "任务步骤过多，已达上限"

tool_router.execute 就是触达层的入口。它在内部完成前面说的参数校验、权限检查、幂等、重试、超时和审计。编排层完全不需要关心工具具体怎么执行。

这里我自己总结过一个比较重要的经验：不要让编排循环无限制地调用工具。MAX_STEPS 一定要设上限，不然遇到模型陷入“调用工具-拿结果-再调用工具”的死循环时，token 消耗和外部副作用都控制不住。我的习惯是拆解型任务 8-15 步，简单查询型任务 3-5 步就够。

4.4 一次完整执行过程的现场复盘

用上面这套代码，跑一个真实流程看看效果。

用户发来消息：“我昨天买的蓝牙耳机充电仓丢了，想单独补一个，订单号是 2025070812345678。”

模型第一步识别到“查询订单”的需求，返回工具调用 get_order，参数 order_id 正确。触达层执行后返回订单状态、商品明细、购买时间。模型发现该订单已发货，且商品类目下有配件可买，于是第二步调用 check_return_policy 来确认配件补购入口。触达层返回该商品的配件补购政策：支持单独购买充电仓，价格 199 元，需发起补购工单由专员联系用户付款。

模型第三步调用 create_refund_ticket，参数 reason 是“充电仓丢失需单独补购”，并生成一个 client_request_id。触达层创建工单后返回工单编号。模型最后调用 send_message，给运营的售后群发了一条通知，附上订单号、工单号和用户需求。

整个过程中，模型的推理消耗了大约 5 轮对话，触达层记录了 4 条工具调用审计日志，外部系统没有出现重复工单。相比之前没有触达层时，这套流程从“知道该做什么”变成了“真的做完了”。

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

5.1 模型反复调用同一个工具，陷入死循环

这个现象太常见了。模型调用 get_order 拿到结果后，发现问题没解决，又用同样的参数再调一次，甚至多次。原因通常是模型没有从上次结果里提炼出有效信息，只能靠重复调用碰运气。

我的排查顺序是：先看审计日志里每次调用的返回内容，是不是结果字段太少，没覆盖模型下一步决策所需的关键信息？比如模型查了订单但没拿到商品类目，它就不知道该怎么判断退货资格，只能反复查询。再检查 description 里是否写清楚了“这个工具返回什么字段、拿到结果后应该做什么”。这一句往往能显著减少重复调用次数。

如果排除了以上两个原因还死循环，那就需要在编排层做兜底：同参数同工具的调用在短时间内只允许出现一次，第二次直接提醒模型“该工具最近已调用过，请勿重复，尝试根据已有信息回答或换其他工具”。

5.2 工具描述被模型误解，选错工具

模型把 get_order 当成了能处理所有订单问题的工具，用户说“我要退货”，它不去调 create_refund_ticket，反而一直调用 get_order。

这种问题的根源在工具描述。如果 get_order 的 description 里只写了“查询订单详情”，模型就倾向于把它当作万能订单工具。解决方案是把你积累的错误案例反哺到描述里。比如明确写：“此工具只读，不执行任何状态变更。退货、退款、修改地址等操作请调用相应工具。”收集 20 个误调用案例后，把典型场景写进负面提示，模型准确率会有肉眼可见的提升。

再狠一点的做法是在触达层做规则拦截。比如用户消息中同时包含“退货”、“退款”等关键词时，get_order 工具直接返回一个提示：“检测到您的意图可能是退货申请，建议使用 create_refund_ticket 工具。”规则先兜底，模型学得慢也没关系。

5.3 上下文被外部返回数据撑爆，token 成本失控

Agent 连续调用几个工具后，每一轮的完整对话上下文都在累积，第三四个工具时，请求的 token 已经比最初多了好几倍。

这是触达层设计不当的最直接信号。每次工具调用的返回结果都被完整送回模型，没做字段裁剪。解决方法是严格执行最小化返回策略：每个工具只返回模型决策必需的最小数据集，其他信息存内部存储，需要时再单独查询。

另外，可以在编排层引入摘要机制。早期工具调用的返回结果如果已经完成了使命，后续轮次可以压缩成一个简短小结，比如“订单信息已获取，商品为耳机，金额 399 元”，而不是一直带着原始 JSON 跑完全程。这一步对长流程 Agent 的成本控制效果明显。

5.4 权限过宽，Agent 做出了危险操作

模型根据用户的话“帮我查一下今年所有订单”调用了 get_all_orders，结果把全公司的订单数据拉出来返回到对话里。这不是模型的错，而是权限模型太宽。

Agent-Reach 的权限设计要坚持最小权限原则。不是每个工具所有用户都能调用，也不是所有数据对所有人都可见。get_all_orders 这种工具根本不应该向普通用户的 Agent 暴露，只有管理员会话才有权限。这个判断必须发生在触达层，不能指望模型自己拿捏分寸。

我的实现是在每个工具上声明 permissions 和 data_scope，然后在执行器里统一检查。当前会话用户是普通客服，data_scope 就是 own，工具只能查自己的客户；是主管，data_scope 就是 team。粒度可以细到这个程度，模型完全感知不到权限判断的存在。

5.5 第三方 API 限流，Agent 批量调用时被卡住

Agent 在循环中快速调用同一个第三方服务，比如给 30 个用户逐一发消息，结果第 10 个就触发了对方限流。

触达层要做的是统一的速率控制，而不是等模型自己慢下来。速率限制可以配置在工具级别，比如 send_message 每分钟最多 20 次。超出限制时，触达层不是直接抛错把模型打蒙，而是返回一个友好提示：“操作已排队，预计 3 秒后可继续。”同时内部自动做好等待和重试。

如果第三方有更细的分桶限流，比如每个接收人每分钟一条，触达层也按维度来做 key。这里的关键原则是：限流信息要结构化地返回给模型，让它知道系统正在推进，而不是卡死了。

5.6 调试技巧：每次调用都要能复现和回溯

最后分享一个调试心得。Agent 出问题时，最怕的就是本地复现不了。模型调用有随机性，第三方系统状态在变，用户输入千奇百怪，所以必须把每次运行的调用链快照保存下来。

我在 Agent-Reach 里实现了一个 Replay 模式：把一次 Agent 运行的完整调用链导出成 JSON，包含每一步的完整请求和响应。调试时直接导入这个快照，用固定的模型配置重放，就能定位问题出在哪一步。这个能力比任何日志框架都实用。

6. 扩展与未来的方向

6.1 从单 Agent 到多 Agent 的互相触达

Agent-Reach 当前的设计是 Agent 触达外部系统。但现实中，很多场景是多个 Agent 之间的协作：一个客服 Agent 需要请求一个售后 Agent 执行退款操作，售后 Agent 又需要通知一个物流 Agent 发起拦截。

这时候触达层的角色就变成了 Agent 与 Agent 之间的通信网关。每个 Agent 的能力也可以注册成工具，被其他 Agent 调用。原来工具执行器面对的是 HTTP API，现在面对的是另一个 Agent 的异步任务。协议上还是那套工具契约，但执行层增加了任务队列和结果回调机制。

6.2 从 API 走到界面操作

很多系统根本没有 API，只有网页界面。银行系统、老旧 ERP、供应商管理后台，全是人肉点击操作。现在解决这类系统的方案是浏览器自动化，比如 Playwright 或者浏览器插件方案。

Agent-Reach 同样可以把浏览器操作抽象成工具。注册一个 click_element、fill_form、read_page 这样的工具，模型就能通过描述操作界面。但这里的安全风险明显更高，界面元素的变化非常频繁，权限控制也更难。我的建议是这类工具只允许在隔离环境里运行，页面状态需要经过视觉检查确认后再执行下一步。这是高风险扩展方向，但也是 Agent 触达能力最值钱的增量市场。

6.3 把触达层的测试做扎实

工具注册多了之后，回归测试就成了一个大问题。你改了一个工具的描述，可能影响模型对另外几个工具的判断。所以 Agent-Reach 里专门有一套基于录制的回归测试：把线上收集的真实用户问题都整理成用例，每次改了工具或提示词，就跑一遍全量用例，对比生成结果和工具调用的准确率。不做这个测试，你根本不敢在线上加新工具。

6.4 我现在实践中的一些体会

Agent-Reach 做下来，我自己最大的感受是：Agent 落地的瓶颈，从来不是模型能力，而是触达层的工程化程度。模型是一个聪明但盲目的执行者，它能不能把聪明用在正地方，取决于你给它搭了多大的舞台、干了多扎实的护栏。

工具的注册表越规范、描述越清晰、权限越收敛，Agent 的表现就越稳定。反过来，如果你只在模型提示词上花功夫，系统接得乱七八糟，再强的模型也救不回来。希望这篇拆解能给你一些可直接落地的思路，少走几个我走过的弯路。