Agent架构拆解：五组件、ReAct循环与私有可控底座实践

写在前面：这行标题背后有多重含义

前阵子团队要把一个客服业务升级成真正的“智能体”项目，我整理了不少方案，最后落地时几乎所有人的注意力都集中在了一个问题：“Agent 架构到底怎么拆，拆完之后企业怎么用得安心？”这正好对应了最近一直在讨论的那个概念——“Agent 架构拆解与企业级 Agent OS：五组件、ReAct 循环与私有可控底座”。标题里的每个词其实都是在回答一个实际问题：如果你要做一个企业级的 Agent，你的系统里必须有哪几块东西，你的 Agent 脑子怎么思考，你的数据怎么不出边界。

这篇文章不是讲纯学术定义，而是站在我自己的实操视角，把“五组件”“ReAct 循环”“私有可控底座”这三件事拆开讲透，顺带把我在真实项目里踩过的坑、调过的参数、改过的 Prompt 都放出来。无论你是刚接触 Agent 的开发者，还是已经在做企业内部智能应用的架构师，应该都能从中找到对得上号的细节。

需要说明的是，这个领域各家表述不完全一致，我讲的是我在项目里验证过、能跑通的划分方式。你可以把它当做一个参考模板，再在自己的场景里做裁剪。

1. 先拆整体：为什么我们要把 Agent 当成一个“操作系统”来看

1.1 从“一个模型”到“一堆组件”

很多人一开始做 Agent 就是“把 API 接到模型里”，比如调用一个模型接口，让它写小作文、做翻译、总结文本。这种水平用一个函数调用就够了，不需要 Agent，也不需要架构。但一旦进入企业场景，需求会变成这样：让一个助手自己判断用户要查订单还是要退款，自己调订单接口，自己查是否满足条件，再决定是否需要人工介入。这时候你发现，仅仅有模型是不够的，模型只是“大脑”，但大脑需要身体、需要手、需要记忆，还需要一个专门给它当“骨架”的宿主环境。

我习惯把这种“宿主环境”理解成专为 Agent 设计的操作系统，也就是 Agent OS。类比一下我们熟悉的电脑操作系统：CPU 负责处理数据（对应模型推理），内存负责短期暂时数据（对应会话上下文），硬盘负责持久化（对应长期记忆和知识库），应用程序通过系统调用访问硬件（对应工具调用），权限管理确保进程越权（对应企业权限管控和审计）。如果只造单独一个 Agent 程序，不造这个底座，那每个 Agent 都会出现同样的循环、记忆、权限问题，重复造轮子且无人维护。企业级 Agent OS 想解决的就是这个公共问题。

1.2 “五组件”到底是什么？一个可落地的划分

标题里说的五组件，现在业内比较通用的分法虽然细节略有差异，但核心逻辑趋同。我在项目里实际落地时用的是以下五个：

模型组件：负责理解、生成、推理，是整个 Agent 的“大脑”。在私有化环境里，它可能是本地部署的开源模型，也可能是某公司私有网关后面的大模型服务。

规划组件：负责把一个复杂任务拆成可执行的步骤，决定下一步做什么。对应 ReAct 循环里的“思考/推理”部分。

记忆组件：负责保存“这个用户上次说过什么”，保存“我们企业内部的业务规则是什么”，保存“这个任务进行到哪一步了”。分为短期会话记忆、长期业务记忆、静态知识库记忆三类。

工具组件：负责统一封装“Agent 能调用哪些外部能力”——查订单、发邮件、算价格、调数据库。工具组件把外部系统的 API 抽象成模型能理解的格式。

执行与反馈组件：负责真正去调用这些工具，接收返回结果，把结果转化为模型可以继续推理的信息，并判断循环要不要结束。

这类分法最大的好处是：每个组件都有独立的职责边界，可以分别开发、分别测试，也可以单独替换升级。比如模型组件换了更强的新模型，其他四块不用跟着改；工具组件加了新接口，模型组件原有的逻辑也不受影响。

1.3 一次请求从进入到返回的完整链路

不用流程图，我用文字描述一次真实的调用过程，你就知道这五个组件怎么协作。

用户在对话框里输入“帮我看一下这笔订单 O20241001 退款到哪一步了”。这条消息先进到 Agent OS 的网关，网关做了身份认证、权限判断、上下文装载（从记忆组件里拉取该用户历史会话和订单状态）。然后模型组件拿到问题后进入 ReAct 循环：

第一步，模型组件生成 Thought：“用户想知道订单退款状态，我需要调用订单查询工具，参数是订单号 O20241001”。

第二步，规划组件把这个想法转成一个结构化工具调用指令，交给工具组件。

第三步，工具组件校验权限、调用外部订单系统的 Query 接口，拿到 JSON 结果。

第四步，执行与反馈组件把这个 JSON 结果塞回给模型：「我来不了，JSON 里说退款状态是 1，退款中。」

第五步，模型组件基于“退款中”这个观察生成最终回答：“这笔订单退款正在处理中，预计两到三个工作日到账。”

整个链路里，模型组件工作多次，其他组件穿插配合，整个过程就是一个循环。把这个循环做到稳定、可控、可审计，就是企业级 Agent 工程化的核心。

2. 五组件逐个拆开看：每个组件的职责、选型和参数

2.1 模型组件：大脑不是越强越好，而是要匹配场景

模型组件是整个 Agent 的精神内核。在选型时，我担心的是相对不那么受关注的“企业私有部署”问题。如果这个 Agent 面向企业内部，数据会涉及订单信息、客户资料、合同内容，直接调公网模型接口是不太现实的。所以第一步要想清楚：这个模型要不要内网部署，还是通过专线调用私有化网关模型。

实操中，模型组件的配置重点有几个：

第一是系统提示词。我通常会在系统提示词里先做“定位”，让模型知道自己是一个客服助手，要遵循什么话术风格，哪些不能承诺，哪些必须要转人工。企业场景里，系统提示词不是用来炫技的，而是用来约束行为边界的。

第二是模型推理参数。温度通常控制在 0.1 到 0.3。Agent 在执行函数调用时如果温度太高，容易出现工具名幻觉、参数编造。做工具调用的时候，我有一条不太会变的原则：需要确定性场景下温度尽量低，甚至可以用 0.1；需要写文案、生成话术时再放开到 0.7 以上。同一个模型，参数不同，表现差异极大，这点很多人容易忽略。

第三是上下文长度管理。模型输入有上限，但一个长会话不可能无限增长。我一般会做一个“滑动窗口”：最新的对话原文保留，更早的内容先总结成摘要存入记忆组件，再作为轻量上下文注入。这能让长会话体验稳定不少。

2.2 规划组件：任务拆解靠的是“任务切片”而不是凭空想

规划组件的主要工作是把目标问题拆解成子任务。在企业里，用户问题通常不是“今天天气怎么样”这种单轮任务，而是“帮我汇总上个月所有退款异常订单，并且给每类原因写一段分析”这种复合型任务。这时候模型需要自己规划：先拉订单列表，再按退款原因分组，再逐类生成分析，最后汇总。

做规划组件的落地时，我强烈建议一个方法：给规划器提供“任务模板”和“少样本示例”，而不是让它完全自由发挥。完全自由发挥的规划器理想状态很漂亮，但实际产出不稳定，有时候会拆出五步，有时候会拆成两步。少样本示例相当于给模型一张存在过的地图：“这种任务过去是这么拆的”。比如在系统提示词里写：

“当用户要求生成退货原因分析报告时： Step1: 调用 list_refund_orders 获取近三十天退款单 Step2: 对退款单按 reason 字段分组统计 Step3: 对每组生成简短分析 Step4: 汇总输出 Markdown 报告”

有了这种示例后，规划质量肉眼可见提升。但要注意，规划模板不要写太死，否则遇到新场景时规划器反而会因为找不到完全匹配的模板而卡住。我一般会放三到五个高频模板，再留一个开放规划能力，两道并行。

2.3 记忆组件：三个层次必须分开管

我见过不少 Agent 项目把记忆全部堆在 context 里，结果上下文越堆越长，模型越来越“健忘”，不是因为模型差，而是因为该记的没记、不该记的全都塞住了。记忆组件在企业场景可以拆成三层：

短期对话记忆：当前会话里最近几轮的提问、回答、工具调用记录。这个相对简单，用滑动窗口管理就行。长期业务记忆：用户身份信息、历史偏好、历史订单记录等，通常写入向量数据库或普通业务数据库。静态知识记忆：企业知识库、业务规则、产品文档。这块一般通过 RAG（检索增强生成）实现，在企业底座里往往是最耗成本的部分。

实操中我用过的一个搭配是：短期记忆用 Redis 保存会话状态，长期记忆用 MySQL 存结构化记录，知识库检索用向量库（比如开源的向量数据库）。每次用户进入会话，先把长期记忆和检索结果“组装”成一段背景信息，再注入到模型输入里。核心经验是：记忆组件不能等 Agent 运行中去临时查，要在会话最开始完成预装载；中途加载新知识容易导致模型在当前轮做出不一致的判断。

2.4 工具组件：注册、Schema、鉴权，一个都不能少

工具组件是 Agent 能“动手”的关键。在工程实现上，工具组件首先得有一个“注册表”，每个工具都要有唯一名字、功能描述、参数 Schema、权限要求、超时时间、失败时的返回格式。

我在代码里经常用类似这样的结构来定义工具（以订单查询工具为例）：

{ "name": "get_order_status", "description": "根据订单ID查询订单当前状态", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，例如 O20241001" } }, "required": ["order_id"] }, "required_auth": "order:read", "timeout_ms": 3000 }

工具描述非常关键，很多问题是“模型不知道这个工具是干嘛的”。描述写清楚，模型才能选对工具。另外一点容易被忽略：工具返回的错误要让模型能看到，并且能理解。比如接口超时，你不应该只给模型一个空字符串，而应该返回结构化错误信息：

{ "error": "timeout", "message": "订单系统响应超时，请稍后重试" }

这样模型才知道下一步是“告知用户系统繁忙”还是“换个方式重查”。

2.5 执行与反馈组件：循环的出口要设计得足够明确

执行与反馈组件负责真正发起 HTTP 调用、数据库查询、执行脚本，并把结果整理成模型容易理解和判断的文本片段。这个组件往往写得最像“工程代码”，也是最能体现细节差异的地方。

比较典型的处理包括：对工具返回的长 JSON 做摘要，只保留当前决策需要的字段；对多个并行工具调用的结果做合并；对执行失败做重试判断（比如幂等接口可以重试，非幂等接口绝不能无脑重试）；对结果做格式清洗，防止模型看到乱码。

我踩过一个印象很深的坑：某次工具返回的 JSON 字段值是amount: 10.0，模型误读成了 10 元，但实际业务含义是 10 万元。后来我们要求工具组件在数据返回后统一做“数值语义增强处理”，把单位、精度、字段业务含义附加上，模型生成的答案才恢复正常。执行与反馈组件不是简单的传包递件，它实际上承担了一部分“信息翻译”的职责，相当于给模型装了副透视镜。

3. ReAct 循环：从论文概念到代码里真正可控的循环

3.1 为什么选 ReAct，而不是纯 Chain-of-Thought

ReAct（Reason + Act）的核心思想是让模型在“推理”和“行动”之间交替进行：先想一步，再做一件事，看到结果后继续想下一步。和纯 Chain-of-Thought（只让模型一路思考）不同的是，ReAct 的每一步推理都绑定了一个可以验证的外部结果，模型想错了，下一步行动就会暴露错误，然后可以被纠正。

在我们做企业 Agent 的项目里，选 ReAct 的直接原因就是可观测性和可纠正性。你不需要盲目信任模型推理链，因为过程中的每个 Action 都会留下记录；出现问题就能立刻定位是哪一步想歪了。相比之下，纯 CoT 如果推理过程错了，最后结论可能错得毫无破绽，排查成本极高。

实际操作时，我会在系统提示词里明确要求模型每轮输出遵循固定格式，一般是下面这个结构：

Thought: 思考当前情况，说明下一步该做什么 Action: 调用哪个工具，传入什么参数 Observation: 等待工具返回结果

在最后一轮，模型输出：

Thought: 我已经拿到了所有需要的信息 Final Answer: 用户问题的最终答案

企业落地时，我对输出格式要求得很严格，甚至会让模型输出 JSON 格式的半结构化内容，方便代码解析，避免靠肉眼去拆文本。

3.2 循环的工程化落地：max steps、超时与终止条件

ReAct 循环光有 Prompt 不够，工程上你需要给循环本身设定护栏。我在实现时重点管四个参数：

最大迭代次数：一般从 3 到 10 次不等，视任务复杂度而定。客服查询类设置 5 次足够；涉及多表查询、复杂分析的，可以放宽到 10 次。一旦超过，直接中止并转人工。单步超时：给每个工具调用单独设置超时，比如查询类 3 秒，非核心操作 5 秒，超时就按失败处理走重试逻辑。终止条件：只有出现Final Answer，或者达到最大轮数，或者触发安全拦截才退出循环。异常熔断：连续三次工具调用报同一类错误，直接不再让模型重试，转而把异常信息呈报给用户或转人工。

这些参数直接决定了 Agent 是“快速交差”还是“死循环拖死”。我记得最早一次原型里，因为没设最大迭代次数，Agent 在查一个不存在的订单号时反复循环了二十多轮，用户看到的就是一直“正在输入”。从那以后，我把最大迭代次数和超时当作上线硬性指标，宁可漏答一点，也不能无限空转。

3.3 让循环“说人话”：半结构化输出与中间过程透明

很多 Agent 体验差，是因为用户只看到最终结果，一旦结果不对就完全黑盒。ReAct 带来的一个额外好处就是：中间过程可以透明化。你可以把 Thought 直接展示为“正在查询订单状态…”，把 Action 展示为“正在调用查询工具”，这样用户能感知到 Agent 在做正事，而不是卡住。

我在生产环境里还会做一个“思考痕迹脱敏”环节。给用户看的 Thought 不能直接展示模型原文，因为模型可能在一段内部推理里提到“这个用户很生气”这类不合适的内部判断。正确做法是：从 Thought 中提取关键动作和状态，组合成前端可展示的状态文案。比如：

用户看到: “正在查询退款进度，请稍候” 实际 Thought: “用户订单号是 O20241001，查询工具参数是 order_id”

这种“半透明”的设计兼顾了体验和合规，也是产品上线时运营方比较认可的方案。

3.4 ReAct 在企业场景里的几个变形用法

ReAct 最基础的应用是让模型自己决定“查什么用什么工具”，但企业场景里有几个衍生模式也很实用。

一种是“固定流程模式”：某些业务不允许模型自由决策，比如退款审批流程是固定的，必须先查订单、再验资格、再走审批，不能乱序。我会把这类流程写进规划模板里，模型只能按模板推进。还有一种是“人工确认模式”：模型推理得到结果后先不执行，而是把候选方案提交给人确认，确认后再调用高影响工具。尤其涉及发短信、退款、改配置这类不可逆操作，一定要插一道人工确认环节。这个环节加在 ReAct 循环的 Action 之后、真正执行之前，不算复杂，但能挡住大量事故。

4. “私有可控底座”不等于自建机房：企业级 Agent OS 的三层关键设计

4.1 “私有可控”到底控制的是什么

“私有可控底座”这个说法听起来像要自建超算中心，其实拆开看主要是三个层面：模型私有化（数据不出域，推理发生在企业可控环境）、数据隔离（不同部门、不同用户只能访问权限范围内的记忆和知识）、行为可审计（每次推理、每个工具调用都有痕迹可查）。这三层合在一起，才是企业敢让 Agent 去干活的前提。

我在和运维团队配合时，最常强调的一句话是：私有化不是把模型搬进内网就行，而是要让“所有数据流动路径”都在审计范围内。模型推理在哪发生、Prompt 里拼接了什么内容、工具调用了哪个接口、带上了谁的身份凭证，这些都要能被追踪。所以私有可控底座一半是技术，一半是制度。

4.2 模型底座选型：开源部署还是私有化网关

企业做私有可控模型服务时，主流是两条路：一是把开源模型（如各类开放权重的语言模型）部署在企业内网 GPU 服务器上；二是通过私有的模型网关对接更大规模的模型服务，数据走专线且不做留存。两条路线没有绝对好坏，核心看你的场景对模型智商和数据敏感度的平衡。

我做过一个相对务实的选型标准：日常查询、结构化提取、简单推理类任务，用部署在本地、参数量较小的开源模型就够，成本低且延迟低；高难度任务（比如长文生成、复杂逻辑判断）按需转发到私有化网关上的强模型。这样做的好处是大部分流量在内网消化，成本可控，同时我们还会加一道“路由规则”：按输入内容类型（是否含业务敏感词）决定命中哪个模型。如果有敏感字段，强制走内网模型，这是硬性约束。

这里要提一下推理部署的参数细节。本地部署时，量化级别要谨慎选。4-bit 量化显存占用低很多，但对复杂工具调用的指令遵循能力影响不小。我的经验是：如果模型要频繁做函数调用，建议至少用 8-bit 量化，不要为了省显存把 Agent 的“工具调用能力”打折；那点成本差距，远低于线上工具选错带来的负面体验。

4.3 记忆与知识库的权限隔离

企业级 Agent OS 里，最容易被忽略的是记忆组件的权限隔离。我们把用户、部门、知识域三层权限绑进检索逻辑，而不是只靠 Prompt 里写一句“不要越权”。比如有销售数据、财务数据、客服话术三类知识库。一个客服机器人，系统就直接让它只能检索客服话术知识库，连财务知识库的 embedding 检索都不放行。这样即使模型被恶意诱导，它也没有能力“看”到不该看的内容，因为它根本没有检索入口，而不仅是靠提示词约束。

具体实现上，我在向量检索前加了一道“知识域过滤器”，根据用户的身份和会话场景生成知识库白名单列表，再拼接成检索条件。哪怕用户问财务数据，白名单里没有这个库，结果就是检索为空，模型自然不能编出靠谱的数字。权限控制这种事后难补的东西，一开始就要放进架构里，后面再改代价很大。

4.4 内容安全与行为审计：Agent OS 的最后一层兜底

内容安全在 Agent 场景里比普通搜索重要得多，因为 Agent 有行动能力，答错了、乱调用了，影响是实打实的。我在生产环境里至少做三层兜底：输入侧做敏感信息识别，拦截不合规的输入；输出侧做内容规范校验，防止模型输出不合规的结论；行为侧监控工具调用序列，比如某个用户在短时间内频繁让 Agent 调用批量查询接口，系统能自动触发风控。

审计日志是我们后端的一个基础表。每条日志至少记录：会话 ID、用户 ID、模型版本、Prompt 版本、工具调用记录、Token 消耗、耗时、是否转人工、最终结论的指纹值。做好这层之后，出了问题就能快速回放“当时 Agent 是怎么一步步做出这个决定的”，这也是企业级和 Demo 最大的区别。

5. 常见问题与排查技巧实录：上线前一定要对照检查

5.1 高频问题的速查表

我把在项目里最常遇到、也最容易被忽视的问题整理成一张速查表，方便你对照干活：

5.2 几个实操里容易忽略的深坑

除了速查表，还有几个细节我印象深刻，单独拿出来说。

第一个是模型版本和 Prompt 版本必须锁定。企业内部 Agent 出了诡异行为后，第一件事往往不是调 Prompt，而是查是不是模型网关悄悄切换了版本。你有段时间可能会碰上“同一个 Prompt 昨天还好好的，今天突然不对劲”，排查一圈发现是上游服务悄悄更新了模型。所以我把“模型版本、Prompt 版本、工具版本”三要素固化成了上线表单，每次变更都要绑定记录，能省掉无数排查时间。

第二个是工具调用的幂等性必须提前定义。有些工具天然非幂等，比如“发送退款通知”“创建一个工单”。如果网络超时导致客户端重试，就有可能出现重复创建。我们的处理方案是给这类工具增加“幂等键”（每个会话内生成的唯一标识），工具接收端幂等去重。这看起来像是后端设计，但没做好，Agent 会很容易把事情搞乱，而且看起来像是“模型疯了”。

第三个是让 Agent 承认“做不到”比逼它做到更重要。我们原来给客服 Agent 立的一个 KPI 是问题解决率，于是产品上不断要求它处理各种边缘情况，结果导致模型开始编造不存在的权限。后来我们反而在系统提示词里主动加了一句：“如果你经过一次工具调用确认确实无法处理，请直接告知用户需要人工协助，不要重复尝试。”效果立竿见影：用户满意度反而提升，因为等待时间变少了。企业级 Agent 不必无所不能，它的核心价值之一是快速判断并把人连接到正确的处理通道。

5.3 优化 ReAct 循环的一个小技巧：把“思考痕迹”做成可回放数据

最后分享一个对我们团队帮助极大的技巧。生产环境的 ReAct 循环，每一轮都会产出一条轨迹数据，我把它们设计成 JSON Lines 格式落盘：

{"session_id": "S10001", "step": 1, "thought": "用户想查订单", "action": "get_order_status", "action_input": "{\"order_id\": \"O20241001\"}", "observation": "status=refunding"}

这些轨迹数据有三个用途：一是线上排障，鼠标点开就能看“Agent 是从哪一步开始跑偏的”；二是离线评测，把真实会话轨迹收集后变成回归测试集，模型升级或者 Prompt 改动之后，先用历史轨迹跑一遍评测再上线；三是生成运营报告，统计哪类问题 Agent 经常处理失败，反哺知识库和工具建设。

我个人实操中体会最深的一句话是：ReAct 不是魔法，它只是一个让模型的每一步都能被观察、被控制、被修正的循环框架。Agent 能不能在企业里跑得稳，九成不在模型多聪明，而在循环之外的那些工程设计——底座隔离、权限管控、日志审计、兜底策略——这些细节做扎实了，Agent 才能真正从“演示品”变成“生产力工具”。如果你正在做类似的企业级 Agent，别急着堆功能，先把这套底座画清楚，再往里面填模型和工具，后面会顺畅得多。