企业官网建设流程全解析

Agent-Reach：把 AI 助手的触角真正伸出去

去年年底我在做一个内部工具的时候，被一个问题卡了很久：大模型本身的能力边界其实很清楚，能聊天、能推理、能写代码，但一旦涉及到"动手做事"——查数据库、调接口、操作文件、跨系统传数据——它立刻就变成了一个只会动嘴的顾问。你问它它知道，你让它做它就抓瞎。当时市面上已经有不少 agent 框架，但用下来总觉得差点意思：要么工具接入太死板，要么多 agent 之间的配合基本靠硬编码，要么上下文一长就开始丢信息。后来我干脆自己动手做了一个轻量级方案，代号就叫 Agent-Reach。

这个项目的核心就一句话：把 agent 的能力边界从"会说话"扩展到"能触达"。它不是一个重型的框架，而是一套打通"模型—工具—系统—多智能体协作"的中间层设计。适合谁看？如果你正在做 AI 应用开发、想给自己的 agent 接上真实业务能力，或者被多 agent 协作的编排问题折磨过，这篇文章应该能给你一些可以直接抄走的思路。下面我把项目从设计到落地的完整过程拆开讲，包括踩过的坑和最后沉淀下来的经验。

1. 为什么"触达能力"才是 agent 落地的真正瓶颈

1.1 模型越来越聪明，但手脚还是短的

先聊一个基本判断。2023 年到现在，大模型的推理能力提升得非常快，尤其在代码生成、逻辑推理这些纯文本任务上，进步几乎是肉眼可见的。但如果你把一个 agent 丢到一个真实的业务场景里——比如让它帮你对账、发周报、同步客户信息——它大概率会卡在第一步：不知道数据在哪、不知道接口怎么调、不知道调完接口之后该做什么。

这不是模型不行，而是agent 的"手"太短。模型的"大脑"再强，如果没有工具去触达外部世界，它就只能在输入输出的闭环里打转。我见过很多团队把精力全花在 prompt 优化上，结果发现 prompt 写得再花哨，agent 也变不出它没有的工具。所以 Agent-Reach 的第一性原则是：先把触角伸出去，再谈聪明不聪明。

1.2 工具调用的价值远不止"加几个 function"

很多人以为给 agent 接工具就是注册几个 function、让模型输出个 JSON 就算完了。实际上，工具接入的深度直接决定了 agent 能处理的任务复杂度。举个我项目里的例子：一开始我只给 agent 接了一个"查询订单"的工具，它工作得很好；但当我加上"修改订单状态"和"发送通知"之后，问题就来了——模型经常在工具之间乱跳，或者在一个工具调用失败后不知道怎么办。

这里有个很关键的设计点：工具之间不是孤立的，它们需要被 agent 理解成一个"能力网络"。Agent-Reach 在处理这个问题时，不只是简单声明"有哪些工具"，而是为每个工具额外注入三样东西：前置条件、执行影响、失败后的回退选项。这样一来，agent 在调用工具的时候不是在盲猜，而是在"知道全局"的情况下做选择。听起来简单，但实操中很多框架都没做这一步。

1.3 从单 agent 到多 agent，核心难题是"谁听谁的"

做到一半我又加了一个需求：让多个 agent 协作，一个负责分析数据，一个负责写文案，一个负责最终审核。结果发现，多 agent 的难点根本不在"让每个 agent 变聪明"，而在它们之间的通信和决策机制。谁先跑、谁后跑、A 的结果怎么送给 B、B 觉得 A 的结果不行怎么反馈……这些问题的复杂度，远大于单个 agent 本身的逻辑。

Agent-Reach 在多 agent 部分的取舍是：不追求完全自治，而是采用"编排者-执行者"的分层结构。编排者负责拆任务、分派、回收结果；执行者只负责干活并返回结构化结果。这个模式我用下来非常稳，也推荐给刚开始做多 agent 的团队——先别急着上自治协商那一套，分层结构能解决 90% 的实际需求。

2. Agent-Reach 的整体设计与核心机制拆解

2.1 架构总览：四层各司其职

先说清楚 Agent-Reach 的整体架构。整个系统分成四层，从下往上分别是：

• 接入层：负责统一封装所有外部能力，无论是 REST API、数据库查询还是本地脚本，都被包装成统一的"工具"接口。
• 调度层：核心的编排逻辑所在，负责工具选择、调用顺序管理、错误重试与回退策略。
• 认知层：管理 agent 的上下文、记忆和工具理解，确保模型在决策时有足够且准确的信息。
• 协作层：处理多 agent 之间的通信和任务流转，包括结果传递、状态同步和冲突仲裁。

这四层听起来很"架构"，但实际实现的时候每一层我都在做减法。比如接入层只定义了一个标准接口，调度层核心就是一个基于状态机的执行循环，协作层更是简化成了"编排者管全局、执行者管局部"。做项目最怕一开始就想得太宏大，Agent-Reach 的原则是每个层只解决一个核心问题。

2.2 工具注册：一个 Schema 解决"模型怎么知道怎么用"

给模型暴露工具，本质上是在做一道翻译题：把程序世界的函数签名，翻译成模型能理解的自然语言描述。Agent-Reach 的做法是设计了一套工具描述 Schema，每个工具注册时除了函数本体，还要附带以下信息：

tool_schema = { "name": "query_order", "description": "根据订单ID查询订单详情，包含商品、金额、状态等信息", "parameters": { "type": "object", "properties": { "order_id": {"type": "string", "description": "订单ID，例如 ORD-2024-0001"} }, "required": ["order_id"] }, "preconditions": "调用前不需要前置查询，但建议先确认订单ID格式正确", "effects": "只读操作，不会修改任何数据", "fallback": "查询失败时，可以尝试调用 list_orders 接口确认订单是否存在" }

注意最后三个字段，这是我自己加的，一般的 function calling 工具描述都不会有。preconditions告诉模型什么时候该用这个工具，effects告诉模型用了之后会有什么后果，fallback给模型一条失败后的退路。加了这三个字段之后，agent 在多个工具之间做选择的准确率提升非常明显，尤其是面对"先用 A 还是先用 B"这类排序问题时，模型不再是猜，而是基于因果关系做推断。

2.3 状态机驱动的执行循环：稳定比花哨重要

很多 agent 框架的执行循环都是"模型无限调工具，调到满意为止"。听起来很灵活，实际用起来很容易失控——模型可能陷入同一个工具的循环调用，或者在一个错误的工具上反复重试。Agent-Reach 用的是一套显式状态机：

IDLE → TASK_RECEIVED → TOOL_SELECTING → TOOL_EXECUTING → RESULT_EVALUATING → OUTPUT / RETRY / FAILED

每一步都是显式控制的，模型只负责两件事：根据当前状态选择工具，以及根据工具结果产出一段思考。至于"工具调用失败要不要重试""重试几次""失败之后要不要换工具"，这些策略都在调度层硬编码好了，不让模型自由发挥。**经验之谈：把重试策略交给代码，而不是交给模型。**模型在连续失败之后容易胡编乱造，而代码层面的重试策略是确定性的，两者结合产出最稳。

2.4 上下文管理：别让 agent 的记忆变成一团浆糊

做 agent 的人一定都遇到过上下文爆炸的问题。工具调用一多，光是把历史调用记录塞给模型就占了几千 token，更不要说模型还得在这些历史里找到有效信息。Agent-Reach 的做法是基于"工作记忆"和"长期记忆"两层来管理上下文。

工作记忆只保留当前任务相关的最近交互，最多 20 轮；长期记忆则是把已完成工具调用的"结果摘要"沉淀下来，每轮结束后自动生成一段简洁的记录。这个设计的核心是一个我自己写的总结函数：

def summarize_step(step_info): return f"[{step_info['tool_name']}] {step_info['input_summary']} → {step_info['result_summary']}"

每步操作完成之后，原始的大段结果会被压缩成一行摘要，存入长期记忆；原始数据如果需要复查，则落盘存到本地，用摘要里的索引去取。这样一来，模型的输入上下文始终是"摘要+当前任务相关详情"，而不是一坨无法消化的大杂烩。实测下来 token 消耗降低了接近 60%，处理复杂任务的成功率反而提升了，因为模型不再被无关信息干扰。

3. 实操过程：从零搭建一套能跑的 Agent-Reach

3.1 环境准备与基础选型

Agent-Reach 我是用 Python 写的，核心依赖其实很少——一个支持 function calling 的大模型接口（我用的是 OpenAI 兼容接口），一个 JSON Schema 校验库，加上我自己写的执行引擎。整套系统加起来核心代码不到 2000 行，这让我后期维护非常轻松。选 Python 的原因很简单：AI 生态最成熟，无论你后面想接什么工具库，都有现成的轮子。

项目的目录结构大概长这样：

agent-reach/ ├── core/ │ ├── engine.py # 状态机执行引擎 │ ├── tool_registry.py # 工具注册与发现 │ ├── memory.py # 工作记忆与长期记忆管理 │ └── orchestrator.py # 多 agent 编排器 ├── tools/ │ ├── database.py # 数据库查询工具 │ ├── http_api.py # HTTP 接口调用工具 │ └── file_ops.py # 本地文件操作工具 ├── agents/ │ ├── worker.py # 执行者 agent │ └── supervisor.py # 编排者 agent └── config.yaml # 模型、工具、策略配置

我这个结构不复杂，但每个模块的职责非常明确。如果你要复刻，建议也按这个思路来——不要急着上微服务，先把单进程的模块化做好，够用到你业务量真正上来再拆。

3.2 核心代码：手写一个简易执行引擎

整个 Agent-Reach 最核心的部分就是执行引擎。我把它拆解成下面这个循环，逻辑很直观：

class AgentReachEngine: def __init__(self, model, tool_registry): self.model = model self.tools = tool_registry self.memory = MemoryManager() self.max_retries = 3 def run(self, task): state = "TASK_RECEIVED" self.memory.add_work_memory("task", task) for round_num in range(10): # 最多 10 轮交互 if state == "TASK_RECEIVED": state = "TOOL_SELECTING" continue if state == "TOOL_SELECTING": # 让模型基于当前上下文选择工具或直接输出 response = self.model.complete( messages=self.memory.get_context(), tools=self.tools.schemas() ) if response.tool_call: state = "TOOL_EXECUTING" self.current_call = response.tool_call else: return response.content elif state == "TOOL_EXECUTING": try: result = self.tools.execute( self.current_call.name, self.current_call.arguments ) self.memory.add_work_memory( "tool_result", self.summarize_tool_result(self.current_call, result) ) state = "RESULT_EVALUATING" except Exception as e: # 失败重试与回退策略 state = self.handle_tool_error(self.current_call, e) elif state == "RESULT_EVALUATING": # 让模型判断当前结果是否满足任务要求 judgment = self.model.complete( messages=self.memory.get_context() + [ {"role": "user", "content": "根据上述工具执行结果，判断任务是否完成？回答 COMPLETE 或 CONTINUE"} ] ) if "COMPLETE" in judgment: return self.finalize_output() else: state = "TOOL_SELECTING" return self.finalize_output()

这里有个细节值得展开讲。在RESULT_EVALUATING状态，我没有直接让模型进入下一轮工具调用，而是强制它先做一次"完成度判断"。这一步看着多消耗了一次模型调用，但这个代价换来的收益非常大：模型不再会无脑连调工具，而是每执行完一步就反思一下当前进度是否符合任务预期。这个反思机制很大程度上避免了 agent 在错误方向上越走越远。

3.3 多 Agent 编排：让"负责人"和"执行者"分工

多 agent 部分我采用了 supervisor-worker 模式。supervisor 负责把任务拆解成可执行的子任务，worker 负责执行；worker 返回结果后，supervisor 决定是继续拆分、还是进入下一步、或者把结果打回重做。

class Supervisor: def run(self, task): plan = self.decompose(task) # 让 supervisor 模型拆解为子任务列表 results = [] for subtask in plan: worker = self.pick_worker(subtask) # 按子任务类型选择 worker result = worker.execute(subtask) if self.needs_revision(result): result = worker.draft_new_version( subtask, feedback=self.generate_feedback(result) ) results.append(result) return self.assemble(results) # 汇总成最终结果

这个模式的好处是：每个 worker 只需要专注自己的领域，上下文不会互相污染；supervisor 只需要做任务拆解和结果验收，不需要执行具体操作，模型压力也小。**如果你做多 agent 总感觉"乱"，先检查你的编排者是不是也在干执行的活。**职责不清是协作混乱的头号原因。

3.4 配置化管理：把策略从代码里拆出来

最后一块是配置文件。Agent-Reach 把模型选型、温度参数、重试次数、最大轮数、工具开关等信息全部放进config.yaml，代码里不硬编码任何策略值：

model: provider: openai_compatible name: gpt-4o-mini temperature: 0.2 engine: max_rounds: 10 max_retries: 3 enable_reflection: true memory: work_memory_size: 20 compress_threshold: 1500 agents: supervisor_model: gpt-4o worker_model: gpt-4o-mini

为什么这么设计？因为我调试过程中发现，同一个代码逻辑，配上不同的温度和模型，表现差异可以大到完全不像同一个 agent。把策略外置之后，我可以快速跑实验组对比，不用改一行代码就能调出最佳配置组合。这个习惯强烈推荐，极大省去了后期调参的重复劳动。

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

4.1 典型问题速查表

我把 Agent-Reach 开发过程中遇到的典型问题整理成了一张速查表，方便你对照排查：

4.2 排查实录一：工具选择准确率突然下降

有一次我给系统加了一个新的"导出报表"工具之后，发现 agent 在查询数据和导出报表之间的选择变混乱了，经常在只需要查询的场景下就去导报表。排查过程是这样的：先把新工具的 Schema 打印出来仔细看，发现它的 description 里写了"获取数据"，和已有查询工具的"查询数据"语义高度重复；模型无法区分两者的场景边界。

解决方法是重新梳理两个工具的描述，把"查询"定义为"获取原始数据详情，用于展示和核对"，把"导出"定义为"生成文件，用于分发和存档"，同时在preconditions里明确写了"仅当用户明确要求导出文件时才使用"。改完之后准确率立刻恢复。经验：工具的语义边界比数量更重要，宁可少加工具，也不要让描述模糊。

4.3 排查实录二：多 agent 协作时 worker 反复返工

另一个棘手的问题是，文案类的 worker 在生成初稿后，supervisor 总觉得"不够好"，返工记录经常超过三轮。一开始我以为是模型能力问题，换了更强的模型之后有所改善，但返工率依然偏高。

后来把 supervisor 的反馈日志拉出来分析才发现，问题出在 supervisor 给 worker 的修改意见太模糊——"内容更生动一点"、"逻辑更清晰一些"，这些都是没法执行的建议。于是我在 supervisor 的 prompt 里加了一个约束：反馈意见必须包含具体的修改方向，比如"把第一段的结论前置"或者"增加一个数据对比表格"，否则不予通过。加了这条之后，返工率从 40% 降到了 15% 左右。这个案例给我的启发是：多 agent 的问题很多时候不是模型不够聪明，而是反馈通道不够具体。

4.4 独家避坑心得

最后分享几条压箱底的经验，都是拿踩坑换来的：

• 别让 agent 处理确定性逻辑。像日期计算、金额校验这类事，用代码硬算，别放给模型自由发挥。模型在这类任务上一旦出错，你是很难排查的，因为它错得"很有道理"。
• 所有工具调用必须留下结构化日志。不仅是记录调了哪个工具，还要记录当时的完整上下文快照。这样出了问题之后，你可以完整复现模型当时的决策依据，而不是对着报错猜半天。
• 模型选择要分角色。不要一个模型打天下。编排者用强模型保证拆解质量，执行者用快模型控制成本和延迟。实际算下来整体费用更低，效果反而更好。
• 上线前做"对抗测试"。故意给 agent 一些边界场景——比如空参数、极长输入、前后矛盾的需求——看它会不会崩。这些测试用例的价值远大于你写 100 条 happy path。

5. 从 Agent-Reach 延伸：下一个阶段还能怎么玩

Agent-Reach 现在在我这边已经稳定跑了几个月，承接了包括数据汇总、报告生成、定时巡检在内的好几类自动化任务。说实话，比起初期预想的"做一个通用 agent 框架"，我更愿意把它看作一个"触达层基础设施"——它不负责聪明，只负责让聪明真正落地。

我最近在考虑的一个方向是给每个工具接入"使用反馈闭环"：当一个工具的执行结果在后续任务中被证明有效或无效时，系统自动调整该工具的权重和描述优先级。简单说就是让 agent 对工具的经验能持续沉淀，而不是每次都从零开始选择。另外一个方向是把工具注册能力开放给非技术用户，让业务人员能通过配置界面自己接入简单的 API，而不需要写代码。

这个项目真正做到最后，最深的体会是：agent 的能力建设是一个系统工程，模型选型和 prompt 优化只是其中一环，工具层的设计、状态机的控制、上下文的治理、多 agent 的协作机制，每一块都是木桶上不可或缺的板。你不需要一开始就把所有板都做得特别长，但一定要保证短板不明显，否则整体体验随时可能崩盘。

如果你也在做类似的 agent 项目，欢迎拿这篇文章里的思路去做对照——尤其是那套工具 Schema 和状态机执行循环，直接抄过去改一改就能跑。踩过坑之后你会发现，agent 能不能"干事"，很多时候从你定义第一个工具的时候就注定了。