企业官网建设流程全解析

接到一个内部项目，名字叫 Agent-Reach。我第一反应是：这不就是我们现在做 AI Agent 落地时最痛的那个环节么。模型再聪明，token 推理得再快，如果它碰不到你的数据库、查不了你的业务系统、调不了你内部的接口，那它就只是个会聊天的玩具。Agent-Reach 这个名字相当直白——Agent 的 Reach，智能体的触达能力。这个项目要解决的，就是让大模型从“能说”变成“能干”，让它在真实系统里完成查询、调度、操作、反馈这一整套闭环。

这篇文章我会完整拆解 Agent-Reach 的设计思路、核心模块、落地实现和踩坑记录。全文不会只停留在概念层面，而是给出可以直接参考的架构方案和一段能跑通的最小闭环代码。你如果是正在做 Agent 应用、RAG 工具链、或者想给自己的大模型应用接外部能力的开发者，这篇文章应该能帮你省掉几天的试错时间。

1. Agent-Reach 是什么：我为什么要做一个“触达层”

1.1 大模型再聪明，也碰不到你的系统

先聊一个被很多人忽略的事实：大模型本质是一个“离线大脑”。它所有的知识、推理能力，都来自训练阶段见过的数据。你问它“今天上海天气怎么样”，它能告诉你上海的气候特征，但不知道当前实时气温；你让它“把运营报表发给老板”，它能写出一封漂亮的邮件草稿，但发不出去。

这个问题的根源在于模型没有触达能力。它没有手脚，没有权限，没有和外界交互的通道。过去一年大家都在聊 Agent，聊 Function Calling，本质上都是在给模型补上这层“手和脚”。但补手脚这件事，听起来简单，做起来极其琐碎。你要定义工具描述、管理调用参数、处理模型返回的结构化指令、执行实际函数、再把结果塞回上下文让模型继续推理。每一步都有细节，每一步都会出幺蛾子。

Agent-Reach 就是这个项目的代号。它不是一个某个企业特有的系统，而是一套我觉得在任何 Agent 场景里都适用的触达框架。它解决的核心问题就一句话：如何让大模型安全、稳定、可控地调用外部工具，并完成一个真实任务。

1.2 一个智能体要干活，得具备哪些“触达”能力

先说结论：Agent 要真正干活，至少要具备四种能力。

第一是感知触达。它要知道自己有哪些工具可以用，这些工具各自能做什么、参数怎么填。就像一个新人入职，得先看一遍部门职责表，才知道遇到问题该找谁。

第二是决策触达。接到用户请求后，模型需要在多个工具之间做选择。比如用户说“帮我查下这个订单的状态”，模型需要判断应该调订单查询接口，而不是去调用户画像接口。这一步看着简单，但在工具数量超过几十个之后，选择准确率会明显下降，这是后面要重点讲的问题。

第三是执行触达。选定工具后，要把自然语言里的信息抽取成结构化参数。比如用户说“查一下上个月华东区的销售额”，模型要把“上个月”换算成一个起止日期，“华东区”映射到区域编码，然后生成一个结构正确的函数调用。

第四是反馈触达。工具执行完，结果要返回给模型，模型需要基于结果继续推理，判断任务是否完成、是否还需要调用下一个工具、是否要把最终答案整理给用户。

Agent-Reach 的目标，就是把上面这四层能力做成一套可复用、可扩展、可观测的框架。我把它拆成了五个模块：意图解析、工具注册与发现、执行编排、上下文管理、安全审计。下面逐个展开讲。

2. 核心架构拆解：Agent-Reach 的五个关键模块

2.1 意图解析：把“帮我查下明天天气”变成结构化指令

意图解析是整个链路的第一步。它要做的事情，是把用户一句模糊的自然语言，转换成模型能理解、能执行的结构化任务。

很多人会有一个误区：意图解析是不是一定要单独训练一个意图分类模型？并不是。在大型模型具备较强指令理解能力的今天，这一步可以直接通过 prompt 设计来完成。比如我们会在系统提示词里写明：

<system_prompt> 你是一个任务规划助手。用户的需求可能涉及多个步骤，你需要把用户请求拆解为一系列可执行的工具调用计划。 当前可用的工具如下：天气查询、航班查询、酒店预订、日程提醒。 注意：如果用户请求无法被现有工具完整覆盖，你必须明确说明缺失的能力，不能假想工具存在。 </system_prompt>

这段 prompt 的价值在于两件事：一是告诉模型“你可以拆任务”，二是告诉模型“你不能编造工具”。第二点非常关键，我发现很多 Agent 在初版实现里，会出现模型自作主张调用一个不存在的工具的情况，结果执行层直接报错。后来我们在提示词里加了那句“不能假想工具存在”，这类问题才明显减少。

这里的底层逻辑，是让模型先做任务分解，再逐项匹配工具。拿“帮我查一下明天去北京的高铁”来说，模型应该先拆出两个子任务：查天气（可选）、查高铁班次。然后识别出“明天”这个时间表述需要换算成具体日期，再映射到高铁查询工具。这个分解-识别-映射的过程，就是意图解析的核心。

2.2 工具注册与发现：让模型知道“你有哪些能力”

工具注册层解决的是能力清单问题。我们需要把每一个可供模型调用的函数，用一种模型能读懂的格式登记下来。目前最通用的格式是 JSON Schema。

举个例子，我们接一个天气查询工具，注册表里会写成这样：

{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市在指定日期的天气情况，包括温度、降水概率、天气现象。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如北京、上海、广州" }, "date": { "type": "string", "description": "日期，格式 YYYY-MM-DD，默认今天" } }, "required": ["city"] } } }

这段 Schema 看起来简单，但里面有三个细节值得说。

第一个是 description 的写法。很多初写者会写“查询天气”，太笼统了。模型是靠 description 来决定什么时候调这个工具的，所以 description 必须包含触发条件和参数边界。说清楚“在用户想了解天气、温度、是否下雨、是否需要带伞时调用”，比只写“查询天气”要准确得多。我实测下来，描述写得越具体，工具选择准确率越高，这一点不需要质疑。

第二个是参数名和描述要尽可能语义化。参数 city 的 description 最好带上常见取值示例，模型在抽取城市名的时候会更容易命中。

第三个是 required 字段不能随便定。把它设计成只保留真正必填的参数，可选参数不要放进 required，否则模型拿不到值时容易硬填，造成后续校验失败。

工具注册是从零搭建 Agent 时最繁琐、最不能省的部分。工具数量一多，这个注册表的管理就成了一个问题。我们项目里后来写了一个自动扫描装饰器，用 Python 的装饰器直接把函数签名转成 JSON Schema，省掉了大量手写工作，这是后话，但建议你一上来就这么设计。

2.3 执行编排：多工具串成一整个任务

单工具调用其实不难，难的是多工具、多步骤的编排。

拿一个典型的任务来说：用户问“帮我选一家距离公司近、人均消费不超过 100 的川菜馆，并预订今晚 7 点的位子”。这个需求拆开看，要先定位公司坐标，再搜附近川菜馆，筛选人均价格，最后调用预订接口。这中间涉及地理编码、餐厅搜索、订单预订三个工具，且每个工具的入参依赖前一个工具的输出。

执行编排要做的事情，就是把这些有依赖关系的工具调用串成一个有向的任务流。模型不是一次性把三个工具的调用参数都生成出来，而是逐步推理：先定位，等结果返回后再搜索，再根据搜索结果决策要不要预订。这个逐步推进的过程，核心是“工具调用结果必须回流到模型中，作为下一次决策的依据”。

在我们的实现里，编排层维护了一个“待执行栈”或“最大迭代次数”来管理这个循环。你不可能让模型无限循环下去，所以每轮执行后都会检查三件事：当前任务是否已经完成、是否还需要调用更多工具、有没有超过最大迭代次数。这三者决定了循环是继续还是终止，逻辑像下面这样：

while iteration < MAX_ITERATIONS: response = llm.chat(messages, tools=tool_schemas) if response.tool_calls is None: break for tool_call in response.tool_calls: result = executor.execute(tool_call.function.name, tool_call.function.arguments) messages.append(format_tool_result(tool_call.id, result)) iteration += 1

这个循环看起来简单，但有大量的边界情况。比如模型连续调了三次同一个工具、参数完全相同，那基本就是陷入死循环了。再比如某个工具返回了错误信息，模型会把错误信息当成正常输入，然后又调一遍同样参数去“重试”。这些场景在第五节里我会单独展开。

2.4 上下文管理：别让记忆吃掉你的上下文窗口

上下文管理是 Agent 项目里最容易爆雷的模块，很多人在前期根本不重视。

直白地说，每一轮工具调用的结果都要写回 messages 列表，作为模型下一轮推理的依据。这带来的问题就是上下文长度飞速膨胀。一个复杂的任务，可能涉及五六次工具调用，每次返回的 JSON 都有几千字符，几轮下来，你的上下文窗口就被占满了。最后的结果是什么？模型开始“遗忘”最初的用户需求，回复变得漫无边际，甚至开始编造不存在的工具结果。

我们在这个项目里做了三件事来控制这个问题。

第一，工具结果截断。对于所有工具返回的大文本，我们只保留前 N 个字符（比如 2000 字符），防止冗长结果直接灌满上下文。对关键字段做摘要，比如返回 1000 行的订单列表，不直接把 1000 行全部塞给模型，而是转为统计摘要：“共 1000 条订单，总金额 20 万元，最近一笔发生在 2025年1月1日 14:03 用户ID 888”。

第二，消息压缩。当上下文达到一定阈值，比如超过上下文窗口 50% 时，触发一次摘要压缩，把历史轮次里的非关键信息浓缩成一段摘要，替换掉原始对话记录。这个阈值需要根据模型的上下文窗口动态调整。

第三，只保留与当前任务相关的历史工具结果。如果一个工具的结果在后续推理中不会再被用到，比如用户问了两次天气，第一天的结果已经无关紧要，就可以从上下文里移除。

2.5 安全审计：默认拒绝，显式放行

Agent 一旦接入真实系统，边界问题就变得非常敏感。一个模型如果拥有调用数据库、发送邮件、执行支付的权限，那它的每一次调用都是真实操作。我们给 Agent-Reach 定的原则是：默认拒绝，显式放行。

也就是说，不是“不能做的才禁止”，而是“明确允许的才能做”。所有工具按风险等级分类：只读类工具（查询）、写入类工具（修改数据）、高敏类工具（涉及支付、对外消息、删除操作）。高敏类工具在触发前必须引入二次确认机制，由人在某个确认界面点击通过，才会真正执行。

此外，所有工具调用都需要落审计日志。日志里要记录：什么时间、哪个会话、模型调用了什么工具、传入了什么参数、返回了什么结果、实际执行了多长时间。这听起来像是在给运维增加负担，但一旦线上出问题，这些日志是唯一能快速定位“到底是模型决策错了，还是工具本身报错了”的线索。我在这个项目上吃过亏，后面在排查问题那一章会细说。

3. 手把手实操：搭建一个能跑通的 Agent-Reach 最小闭环

3.1 环境准备：模型接口与依赖库

说再多理论不如直接看代码。这一章我带着你把 Agent-Reach 的最小闭环跑起来。我用的环境是 Python 3.11，模型接口走的是 OpenAI 兼容的 Chat Completions 格式，因为这已经是行业事实标准，换成任何国产大模型只需要改 base_url 和 api_key。

假设你已经配置好了环境变量 OPENAI_API_KEY 和 OPENAI_BASE_URL。接下来只需要一个简单的依赖：requests 或 openai SDK。我用的是 openai 库，版本 1.x，因为它的 chat.completions.create 接口支持 tools 参数，写起来最顺手。

整个最小闭环要做的事情是：用户问“北京今天天气怎么样，适合跑步吗？”，Agent 调用天气查询工具，拿回实时数据，再结合数据给出跑步建议。

3.2 定义工具：以天气查询为例

先定义一个天气查询工具。为了这一章能独立跑通，我用一个 mock 函数来模拟真实天气 API 调用。你在生产环境里把这个函数替换成真实的天气服务请求即可。

def get_weather(city: str, date: str = None) -> str: """模拟天气查询，实际使用时替换为真实天气 API 的请求。""" import datetime date = date or datetime.date.today().isoformat() mock_db = { ("北京", "2025-01-05"): {"temp": -2, "precip": 0, "desc": "晴"}, ("上海", "2025-01-05"): {"temp": 8, "precip": 30, "desc": "小雨"}, } data = mock_db.get((city, date)) if data is None: return f"Error: 未查询到 {city} 在 {date} 的天气数据" return f"{city} {date}：{data['desc']}，温度 {data['temp']}℃，降水概率 {data['precip']}%"

这个 mock 函数故意保留了一个 Error 返回分支。如果你让模型去查一个数据库里不存在的城市，它会返回一个错误文本。这个“错误文本”反而是一个很好的测试材料，因为后面你会看到，模型在拿到 Error 之后能不能做出正确判断，恰恰是判断执行编排是否合格的试金石。

然后把这个函数封装成 OpenAI 要求的工具 schema。这部分就是上一章说的工具注册，正式项目里应该用装饰器自动生成，这里为了方便演示手写一份：

tools = [ { "type": "function", "function": { "name": "get_weather", "description": ( "查询指定城市在指定日期的天气情况。" "当用户询问天气、气温、降水、是否适合户外活动时使用。" ), "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市中文名，如北京"}, "date": { "type": "string", "description": "日期，格式YYYY-MM-DD，不传则默认为今天" } }, "required": ["city"] } } } ]

这里再强调一次 description 的写法：我把“是否适合户外活动”也写进了触发条件里，这样当用户问“适合跑步吗”的时候，模型才能把这个问题关联到天气工具上。trigger 写不清楚，后面全白搭。

3.3 核心循环：模型决策与工具执行的交替

接下来是核心循环。这是 Agent-Reach 最关键的代码，我会写得完整一点。

from openai import OpenAI client = OpenAI() def run_agent(user_query: str, tools: list, max_iterations: int = 5): messages = [ {"role": "system", "content": ( "你是一个智能助理，可以通过工具获取实时信息并回答用户问题。" "每次工具调用后，等待工具结果返回再做下一步判断。" "当工具返回错误时，不要重复调用相同参数的同一个工具，" "应告知用户当前无法获取该信息。" )}, {"role": "user", "content": user_query} ] for step in range(max_iterations): print(f"\n----- Step {step + 1} -----") response = client.chat.completions.create( model=MODEL_NAME, messages=messages, tools=tools, temperature=0 ) message = response.choices[0].message # 模型没有发起工具调用，说明它已经准备好给出最终回答 if not message.tool_calls: print("模型最终回答：", message.content) return message.content # 将模型的工具调用消息追加到上下文中 messages.append(message) # 遍历工具调用并执行 for tool_call in message.tool_calls: fn_name = tool_call.function.name fn_args = tool_call.function.arguments print(f"调用工具: {fn_name}, 参数: {fn_args}") if fn_name == "get_weather": import json args = json.loads(fn_args) result = get_weather(args["city"], args.get("date")) else: result = f"Error: 未知工具 {fn_name}" # 把工具执行结果回填到消息列表中 messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": result }) print("达到最大迭代次数，任务可能未完成。") return messages[-1].content if messages else None

这段代码就是 Agent-Reach 执行编排的最小原型。我来说几个值得注意的细节。

第一，temperature 我设成了 0。工具调用场景里，我们不需要模型发挥创造力，只需要它尽量稳定精确地输出结构化参数。temperature 越高，参数抽错、工具选错的概率越大。这是实测下来的结论，不是理论推断。

第二，模型返回的 message 要原样 append 到 messages 里，很多新手容易漏这一步。如果你不把模型发起的 tool_calls 追加回上下文，模型下一轮就丢失了自己刚才要调用工具这件事，上下文会变得支离破碎。

第三，每个工具调用的结果要用 role 为 tool 的消息回填，并且必须带上 tool_call_id。这个 id 是 OpenAI 协议里用来关联工具调用和结果的锁扣。少了它，接口会直接报错。

3.4 测试结果：看一遍全链路日志

跑一下这个最小闭环，看看实际输出长什么样。

$ python agent_reach_demo.py

用户输入是“北京今天天气怎么样，适合跑步吗”。假设今天是 2025年1月5日，模型应当会发起一次 get_weather 调用，参数是 city=北京，date=2025-01-05。

日志里看到的流程应该是：

----- Step 1 ----- 调用工具: get_weather, 参数: {"city": "北京", "date": "2025-01-05"} ----- Step 2 ----- 模型最终回答：北京今天晴，温度 -2℃，降水概率 0%。温度较低，户外跑步需要做好保暖措施，建议穿防风外套和手套。

这一步跑通，意味着 Agent-Reach 最核心的“模型决策-工具执行-结果回填-再次推理”闭环已经建立了。从这个基础上，你可以继续加更多工具、加多步骤任务、加校验逻辑。

我建议你拿到这段代码后，先做一个自测：把城市换成“天津”（mock 数据里不存在）。看模型是会冷静地告诉你“抱歉，目前查不到天津的天气”，还是会陷入连续重试。我在初版实现里，模型会反复用相同参数调两次甚至三次，直到 max_iterations 耗尽。这个就是我们后面要重点解决的“工具调用失败后如何优雅处理”的问题。

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

4.1 模型总是不调用工具？先查这几处

这是 Agent 项目里出现频率最高的问题：提示词写好了，工具 schema 也传了，但模型就是不理你，直接用自己的常识回答。排查思路按优先级排序：

第一步，检查工具 schema 的 JSON 格式。用代码打印出你发给接口的 tools 参数，肉眼确认不是某个引号被转义成错的了。OpenAI 兼容接口对工具 schema 的解析非常严格，有任何格式瑕疵，它会静默忽略整个工具调用能力，而不是报错。

第二步，检查系统提示词里有没有自相矛盾。如果你在 system prompt 里写“你可以直接回答问题，无需调用工具”，那模型就真的不调了。这类提示词冲突是最隐蔽的坑，排查的时候逐字读一遍 system prompt。

第三步，检查 description 是否明确。前面一再强调的“触发条件要写清”，在这时候会真正体现出来。如果你的 description 只写了“查询天气”，当用户问“适合跑步吗”时，模型未必能联想到天气工具。把描述改成“查询天气以判断是否适合户外活动”，效果会立刻不一样。

4.2 多轮调用后上下文越来越长，怎么压缩

上下文爆炸的问题，我在 2.4 节里讲过，这里补充一套可以直接落地的阈值方案。

假设你的模型上下文窗口是 128k，那么可以设定：当 messages 的总字符数超过 60k 时触发压缩。压缩策略是：把最早的历史对话（除了 system prompt 和当前用户问题）交给一个轻量模型，生成一段不超过 1500 字的任务摘要，替换掉那部分原始消息。

这里有一个我踩过的坑：摘要模型容易把工具调用的细节丢掉，导致后面模型无法理解“这个数据是怎么来的”。解决办法是：在摘要时专门保留以下信息——调用了哪些工具、关键参数是什么、关键结果是什么。把这三类信息摘出来，别的都可以丢。

如果你用的模型支持更长上下文，也别掉以轻心。上下文长了不代表模型就能用得好，太长的上下文会让模型注意力分散，反而更早地“忘记”用户最初的意图。

4.3 Agent 陷入死循环怎么办

Agent 死循环是上线后最让人头疼的问题。症状是：模型反复调用同一个工具，参数不变，结果不变，但就是不给出最终答复。原因多半是模型从工具返回的错误中读到了某个它可以“修复”的东西，然后它决定再试一次。

治本的办法有三个。

一是 max_iterations 一定要设，且设得保守。内部工具场景，5 次以内足够覆盖绝大多数任务。像“查询-再查询-得出结论”这种流程，3 次就完成了。如果设成 20 次，等于给了模型充足的空间去钻牛角尖。

二是给工具结果里加状态标记。即使 mock 数据报错，也返回标准结构，比如 {"status": "error", "message": "no data"}。模型看到 status 字段就能快速判断这是不可恢复的错误。

三是给模型设定一个“失败阈值”。在系统提示词里明确写：“同一个工具调用参数完全相同、且上一次结果中包含错误信息时，禁止再次调用，应直接向用户说明失败原因。”这个规则先于我上面第二种方案解决了大部分死循环问题。

4.4 工具权限失控怎么办

当你的 Agent 接入了真实业务工具，权限失控就是最高优先级的隐患。我的原则是“最小权限 + 二次确认 + 全量审计”三条线并行。

最小权限指的是：系统给 Agent 配置的 API key 或服务账号，不该拥有它通常用不到的权限。比如只做查询的业务 Agent，就不要给它配写入数据库的权限。这项工作看着像运维活，但它是 Agent 安全的地基。

二次确认针对高敏操作。凡是工具名匹配到“删除”“发送”“支付”“转账”等关键词，一律进入待确认状态，由人工审核确认后才放行。这会给体验带来一点延迟，但这是必要的代价。没有任何一个认真做 Agent 落地的团队敢把支付权限裸放给模型。

全量审计我在 2.5 节里说过，这里补充一个实操细节：审计日志不要只记录工具名和参数，还要记录模型当时的完整消息体。因为一旦出现误操作，你需要回答的问题是“模型为什么决定调这个工具”。没有上下文快照，你永远无法复盘模型的决策路径。

最后说点我个人的体会

Agent-Reach 这个项目做下来，我最大的感受是：Agent 的难点根本不在“大模型”，而在那些细碎的工程问题。工具描述怎么写、参数怎么约束、错误怎么回流、上下文怎么控制、权限怎么收敛，每一项单独看都不难，但它们叠加在一起，就是决定一个 Agent 项目能否从 demo 走向生产的分水岭。

回到这个标题上，Agent 的 reach 本质上是一种工程能力。模型推理能力是底座，但让模型真正触达业务、产生价值，靠的是这一层层踏踏实实的设计和实现。你现在看到的最小闭环，已经足够支撑起一个真实的业务场景了。在这个基础上，把一个一个工具接进来，把权限和日志做完善，你手里就是一个真正能落地的 Agent 框架。