1. 从能聊到能干活Agent 架构到底在解决什么问题大多数人第一次接触 Agent 这个概念都是从让大模型自己调用工具开始的。写个函数、注册个 schema、模型返回一个 JSON 说我要调用天气查询然后你把结果塞回去模型再总结一句今天适合出门。这个 demo 跑通的那一刻确实很爽但只要你把它往真实业务里推一步问题就全冒出来了模型忘了上一步查过什么、工具调用失败之后它开始胡编、同一个任务跑三次给出三种完全不同的路径、上下文越堆越长最后直接超窗。这些问题的根源不在于模型不够聪明而在于你只给了它一个大脑却没给它一套完整的身体。Agent 架构要解决的就是把一个会说话的语言模型变成一个能稳定完成任务的执行体。这中间差的不是提示词技巧而是一整套工程结构。我先把结论摆在这里一个能在企业环境里跑起来的 Agent本质上由五个组件构成——模型、工具、记忆、规划、执行循环。这五个东西缺一个你的 Agent 就只能在 demo 阶段打转。而所谓企业级 Agent OS就是把这五个组件做成可复用、可管控、可审计的底座让业务方不用每次都从零搭一遍。这篇文章适合三类人看一是正在做 Agent 应用但总觉得哪里不对劲的开发者二是需要向团队或客户解释 Agent 到底怎么落地的人三是想搞清楚 ReAct 循环、记忆机制这些概念背后真实工程含义的技术负责人。我会尽量把每个组件拆到能直接抄作业的程度同时把那些文档里不会写的坑一并交代清楚。需要提前说明的是下面涉及的架构设计、参数取值、组件划分一部分来自公开的技术资料和常见实践另一部分是我在实际搭建过程中总结的经验判断。凡是属于常见做法而非唯一标准的地方我都会明确标出来你可以根据自己的场景调整。2. 五组件拆解每个组件到底在扛什么责任2.1 模型层不是选最强的而是选最合适的很多人一上来就纠结用哪个模型其实这个问题问错了。正确的问法是这个任务需要多强的推理能力能容忍多高的延迟和成本。模型层在 Agent 里承担的是决策职责——它要根据当前状态决定下一步做什么。注意是决策不是执行。执行是工具的事。所以模型层最核心的能力不是知识量而是指令遵循和结构化输出。一个知识渊博但总是不按格式返回 JSON 的模型在 Agent 场景里是灾难。我在实际项目里通常会做分层主决策模型用推理能力强的负责规划和复杂判断一些简单的分类、抽取、格式化任务用轻量模型顶上。这样整体成本和延迟能压下来一大截。具体怎么分可以看下面这个对照任务类型推荐模型档位理由任务规划、多步推理高推理能力档需要理解复杂目标并拆解工具参数生成中等档位结构化输出稳定即可结果摘要、格式转换轻量档位成本敏感逻辑简单意图分类、路由轻量档位高频调用要求低延迟这里有个容易被忽略的点模型层的输出必须是可解析的。我见过太多项目因为模型偶尔返回一段好的我来帮你查询这种自然语言导致整个解析流程崩掉。解决办法不是反复调提示词而是在架构层面做兜底——解析失败时要么重试要么降级到规则路径绝不能让它直接把异常抛给用户。2.2 工具层Agent 的手脚也是最容易出事的地方工具就是 Agent 能调用的外部能力查数据库、调 API、读文件、发消息、执行计算。听起来简单但工具层是整个 Agent 里故障率最高的部分因为它是唯一和外部世界真实交互的地方。工具设计有几个铁律我踩过坑之后总结出来的第一工具粒度要适中。太细模型要调十几次才能完成一件事上下文爆炸太粗一个工具干太多事参数复杂到模型填不对。我的经验是一个工具对应一个业务动作比如查询订单状态是一个工具修改订单地址是另一个而不是搞一个订单管理大工具。第二每个工具必须有清晰的失败语义。工具调用失败时返回给模型的不应该是一句出错了而应该是结构化的错误信息是参数错了、权限不够、还是目标不存在。模型拿到具体错误才能决定是重试、换参数还是放弃。这一点直接决定了 Agent 的鲁棒性。第三危险操作必须有人工确认或权限校验。删除数据、发送消息、转账这类操作绝对不能只靠模型判断。企业级场景里工具层要内置权限检查模型说我要删这条记录工具层要先问这个 Agent 有没有删除权限没有就直接拒绝。# 工具定义的结构化示例伪代码 tool_schema { name: query_order_status, description: 根据订单号查询订单当前状态, parameters: { order_id: {type: string, required: True} }, permission: order:read, # 权限标识 timeout: 5, # 超时秒数 retry: 2, # 可重试次数 dangerous: False # 是否危险操作 }把权限、超时、重试、危险标记都写进工具定义里这样执行层就能统一处理不用每个工具各写一套。2.3 记忆层让 Agent 记住刚才发生了什么记忆是区分玩具 Agent和可用 Agent的分水岭。没有记忆的 Agent每一轮对话都是失忆状态用户说把刚才那个订单取消掉它一脸茫然。记忆分两类一定要分清楚短期记忆是当前任务的上下文包括对话历史、已经调用过的工具、拿到的中间结果。它决定了 Agent 在当前任务里能不能连贯思考。短期记忆的核心矛盾是装不下——上下文窗口有限任务一长就爆。长期记忆是跨任务、跨会话的知识比如用户偏好、历史操作、领域知识。它决定了 Agent 能不能越用越懂你。短期记忆的处理常见做法是滑动窗口加摘要。窗口保留最近 N 轮完整对话更早的内容压缩成摘要。这里有个参数经验窗口大小不要设得太满留出至少 30% 的余量给工具返回结果因为工具返回往往比对话长得多。我见过有人把窗口塞到 90%结果第一次工具调用就超窗了。长期记忆一般用向量检索实现把历史信息转成向量存起来需要时按相似度召回。但要注意不是所有信息都值得存。我的做法是只存三类用户明确表达的偏好、任务的关键结论、可复用的领域知识。流水账式的对话记录存进去只会污染检索结果。提示记忆层最容易犯的错是什么都记。记忆越多检索越慢噪声越大。宁可少记也要记准。2.4 规划层把我要做X变成第一步做A第二步做B规划层是 Agent 的大脑前额叶负责把模糊的目标拆成可执行的步骤。这是最考验模型能力、也最容易翻车的地方。规划有两种模式。一种是先规划后执行模型一次性把整个任务拆成步骤列表然后逐步执行。好处是全局清晰坏处是如果第一步就错了后面全错。另一种是边执行边规划每执行一步根据结果决定下一步。好处是灵活坏处是容易走一步看一步迷失方向。实际项目里我一般用混合模式先出一个粗粒度的计划3 到 5 步执行过程中允许动态调整。这样既有全局方向又保留了应对意外的灵活性。规划层还有个关键设计是任务分解的粒度。拆得太粗单步太复杂模型搞不定拆得太细步骤太多容易在中途丢失目标。经验值是每个子任务对应 1 到 3 次工具调用比较合适。2.5 执行循环把上面四个组件串起来的引擎执行循环是 Agent 的心跳它负责拿当前状态 → 让模型决策 → 执行工具 → 更新记忆 → 判断是否完成 → 循环或结束。这个循环看起来简单但要跑稳必须处理好几件事最大循环次数防止死循环、超时控制防止卡死、异常中断工具连续失败要能优雅退出、状态持久化长任务要能断点续跑。最大循环次数这个参数我一般设 15 到 25 之间。设太小复杂任务做不完设太大一旦模型陷入循环就是烧钱。配合连续两次相同工具调用就强制中断的规则基本能兜住大部分死循环。3. ReAct 循环为什么边想边做比想好再做更靠谱3.1 ReAct 的本质把推理和执行交织起来ReAct 这个名字来自 Reasoning 和 Acting 的组合核心思想是让模型在每一步都先想一下Reasoning再做一下Acting然后根据做的结果继续想。这个循环听起来朴素但它解决了纯规划模式的一个致命问题模型对世界的认知是滞后的。纯规划模式下模型在没有任何实际信息的情况下就把整个计划定死了。但真实任务里第一步的结果往往会影响第二步该怎么做。比如你让 Agent帮我订一张明天去某地的票它得先查有没有票才知道要不要改时间、换车次。如果它一开始就把订上午十点那班写死查出来没票就傻眼了。ReAct 的价值就在于它把观察这个动作放进了循环里。每一步的决策都基于最新的观察结果而不是基于一开始的假设。3.2 一个完整的 ReAct 循环长什么样我用一个具体任务来演示用户说帮我看看上周的销售数据如果比前一周下降超过 10%就发个提醒。第一轮模型思考我需要先拿到上周和前一周的销售数据。然后行动调用查询工具参数是上周日期范围。观察拿到上周数据。第二轮模型思考现在需要前一周的数据做对比。行动调用查询工具参数是前一周日期范围。观察拿到前一周数据。第三轮模型思考两周数据都有了我来算一下变化率。行动调用计算工具。观察下降 15%。第四轮模型思考下降超过 10%需要发提醒。行动调用消息发送工具。观察发送成功。第五轮模型思考任务完成。输出最终结果。这个循环里每一轮的思考都基于上一轮的观察这就是 ReAct 的精髓。你可以看到如果第三轮算出来只下降 3%第四轮就不会发提醒直接结束。这种动态性正是纯规划做不到的。3.3 ReAct 的常见变体和取舍标准 ReAct 之外实践中还有几种变体各有适用场景Reflexion反思在任务失败后让模型回顾失败原因把教训写进记忆下次避免。适合需要长期优化的场景但会增加额外调用成本。Plan-and-Execute规划后执行先出完整计划再执行适合步骤明确、不易变化的流程化任务。Tree of Thoughts思维树同时探索多条推理路径选最优的。适合需要深度推理的问题但成本高一般不用在实时交互场景。我的建议是大多数企业场景用标准 ReAct 就够了别一上来就上复杂变体。等你发现标准 ReAct 在某个具体环节反复出问题再针对性地引入变体。3.4 ReAct 循环里最容易踩的三个坑第一个坑是思考过程被截断。模型在思考阶段输出太长还没到行动就超了 token 限制。解决办法是在提示里明确限制思考长度或者用支持更长输出的模型。第二个坑是观察结果污染上下文。工具返回一大坨原始数据直接塞进上下文几轮下来就爆了。正确做法是在工具层做预处理只返回模型需要的关键字段。第三个坑是循环终止条件不清晰。模型不知道该什么时候停要么提前结束要么无限循环。必须在提示里明确定义什么算完成并在执行层设置硬性上限。4. 企业级 Agent OS为什么单机 Agent 撑不起真实业务4.1 从一个 Agent到一群 Agent的管理难题当你的业务里只有一个 Agent怎么折腾都行。但企业场景下你很快会面临客服 Agent、数据分析 Agent、运维 Agent、审批 Agent 同时存在它们要共享工具、共享记忆、共享权限体系。这时候如果没有一个统一底座每个 Agent 各搭一套维护成本会指数级上升。Agent OS 要解决的就是这个问题把 Agent 的公共能力抽出来做成平台。业务方只需要定义我的 Agent 要做什么、能用哪些工具、有什么权限剩下的模型调度、记忆管理、执行循环、监控审计全部由底座提供。这跟操作系统的思路是一样的应用程序不用自己管内存、管磁盘、管进程调度操作系统统一提供。Agent OS 就是 Agent 世界的操作系统。4.2 私有可控底座数据不出域是硬要求企业级场景和消费级最大的区别是数据敏感性。很多业务的数据根本不能出内网更别说发给外部模型服务。所以私有可控底座不是加分项而是准入门槛。私有可控包含几层含义模型可控能用私有部署的模型或者至少保证数据在传输和处理过程中不落外部。这决定了模型层的选型必须支持本地化。数据可控记忆、日志、中间结果全部存在自己的存储里有明确的留存和销毁策略。权限可控每个 Agent、每个工具、每次调用都有权限校验谁在什么时间调用了什么全程可追溯。行为可控能限制 Agent 的行为边界比如禁止访问某些工具、禁止在特定时间段执行、危险操作必须审批。我见过一些团队一开始图省事直接用公有服务搭 Agent等到要接入核心业务数据时才发现根本过不了合规只能推倒重来。所以如果你做的是企业项目从第一天就要按私有可控来设计哪怕初期部署简单一点。4.3 底座需要提供哪些核心能力一个能用的 Agent OS 底座至少要提供这几块能力能力模块具体职责缺失后果模型网关统一模型调用、路由、限流、降级每个 Agent 各调各的无法统一管控工具注册中心工具注册、版本管理、权限绑定工具散落各处无法复用和审计记忆服务短期/长期记忆的存储与检索每个 Agent 自己实现重复造轮子执行引擎运行 ReAct 循环、超时控制、重试循环逻辑各写各的质量参差监控审计全链路日志、调用追踪、成本统计出问题无法定位成本失控权限中心身份认证、工具授权、操作审批安全无保障危险操作无人拦这六块里监控审计和权限中心是最容易被忽略、但出事时最要命的。很多团队把精力全花在让 Agent 更聪明上结果上线后既不知道它花了多少钱也不知道它到底干了什么一旦出问题就是黑盒。4.4 多 Agent 协作底座之上的进阶玩法当底座搭好之后多 Agent 协作就变得可行了。常见模式有几种主管-下属模式一个主管 Agent 负责拆解任务分给多个专业 Agent 执行最后汇总。适合任务边界清晰的场景。流水线模式多个 Agent 按顺序处理前一个的输出是后一个的输入。适合流程化任务。辩论模式多个 Agent 对同一问题给出方案互相评审选最优。适合需要高质量决策的场景但成本高。这里要提醒一句多 Agent 不是越多越好。每多一个 Agent就多一层通信开销和出错概率。我见过有人为了看起来高级把一个简单任务拆成五个 Agent 协作结果延迟翻了三倍效果还不如单个 Agent。判断标准很简单如果单个 Agent 加几个工具就能搞定就别上多 Agent。5. 落地实操从零搭一个最小可用的 Agent 底座5.1 环境准备与目录结构假设你要搭一个最小可用的 Agent 底座我建议的目录结构是这样的agent_os/ ├── core/ │ ├── loop.py # ReAct 执行循环 │ ├── planner.py # 规划层 │ └── state.py # 状态管理 ├── models/ │ └── gateway.py # 模型网关 ├── tools/ │ ├── registry.py # 工具注册中心 │ └── builtin/ # 内置工具 ├── memory/ │ ├── short_term.py # 短期记忆 │ └── long_term.py # 长期记忆 ├── security/ │ ├── auth.py # 权限校验 │ └── audit.py # 审计日志 └── config/ └── settings.yaml # 全局配置这个结构的好处是职责清晰每个模块可以独立测试和替换。比如你后面想换模型只动 models 目录想加工具只动 tools 目录。5.2 执行循环的核心代码骨架执行循环是整个底座的心脏下面是一个简化但可运行的骨架class AgentLoop: def __init__(self, model, tools, memory, max_steps20): self.model model self.tools tools self.memory memory self.max_steps max_steps def run(self, task): self.memory.add(user, task) for step in range(self.max_steps): # 1. 让模型基于当前上下文决策 decision self.model.decide(self.memory.get_context()) # 2. 如果模型认为任务完成退出 if decision.type finish: return decision.answer # 3. 执行工具调用 tool self.tools.get(decision.tool_name) if not tool: self.memory.add(system, f工具 {decision.tool_name} 不存在) continue # 4. 权限校验 if not self.check_permission(tool, decision.params): self.memory.add(system, 权限不足操作被拒绝) continue # 5. 执行并记录结果 try: result tool.execute(decision.params) self.memory.add(tool, result) except Exception as e: self.memory.add(system, f工具执行失败: {e}) return 达到最大步数限制任务未完成这段代码看着简单但每一行背后都有讲究。比如第 4 步的权限校验一定要放在工具执行之前而不是之后。再比如异常处理捕获之后要把错误信息写回记忆让模型知道发生了什么而不是静默失败。5.3 工具注册与权限绑定的实现工具注册中心要解决的是工具怎么被找到、怎么被授权的问题。一个实用的实现是这样的class ToolRegistry: def __init__(self): self.tools {} def register(self, name, func, schema, permissionNone): self.tools[name] { func: func, schema: schema, permission: permission } def get(self, name): return self.tools.get(name) def list_available(self, agent_permissions): 只返回该 Agent 有权限使用的工具 return [ name for name, t in self.tools.items() if t[permission] is None or t[permission] in agent_permissions ]注意list_available这个方法。它的作用是只把有权限的工具暴露给模型。这样模型根本看不到它不能用的工具从源头上避免了模型想调但没权限的尴尬。这比事后拒绝要优雅得多。5.4 记忆管理的落地细节短期记忆的实现我推荐用消息列表 自动摘要的方式class ShortTermMemory: def __init__(self, max_tokens8000, keep_recent6): self.messages [] self.max_tokens max_tokens self.keep_recent keep_recent def add(self, role, content): self.messages.append({role: role, content: content}) self._compress_if_needed() def _compress_if_needed(self): if self._count_tokens() self.max_tokens: return # 保留最近 N 条更早的压缩成摘要 recent self.messages[-self.keep_recent:] old self.messages[:-self.keep_recent] summary self._summarize(old) self.messages [{role: system, content: summary}] recent这里keep_recent设成 6 是个经验值大概对应 3 轮完整的思考-行动循环。设太小模型记不住刚才干了什么设太大压缩频率低但每次压缩成本高。你可以根据自己的任务复杂度调整。5.5 监控审计别等出事才想起来审计日志要记录的东西比大多数人想的多。至少包括每次模型调用的输入输出、每次工具调用的参数和结果、每次权限校验的结果、整个任务的耗时和步数、消耗的 token 和成本。def audit_log(event_type, agent_id, detail): log_entry { timestamp: now(), event: event_type, agent: agent_id, detail: detail } # 写入持久化存储注意脱敏 storage.write(log_entry)这里有个关键点日志要脱敏。工具参数里可能包含用户隐私、密钥、内部标识写日志之前必须过滤。我见过因为日志没脱敏导致敏感信息泄露的案例这个坑一定要提前防。6. 那些文档不会告诉你的实战经验6.1 关于模型选型的反直觉结论很多人以为 Agent 效果不好是因为模型不够强于是不断换更大的模型。但我的实际经验是在 Agent 场景里提示词结构和工具设计的质量对最终效果的影响往往比模型档位更大。我做过对比同一个任务用中等模型配精心设计的工具和提示效果明显好于用顶级模型配粗糙的工具。原因很简单Agent 的瓶颈通常不在模型会不会想而在模型能不能准确知道现在有什么、该用什么、结果是什么。这些是工程问题不是模型能力问题。所以我的建议是先把工具和提示打磨到位再考虑升级模型。顺序反了钱花了效果还不好。6.2 上下文管理的三个实用技巧第一工具返回结果要精简。数据库查出来 50 个字段模型可能只需要 3 个。在工具层就过滤好别把原始数据全塞进去。第二中间结果及时归档。长任务里早期的中间结果如果不再需要就压缩成一句话结论别一直占着上下文。第三给上下文加锚点。在上下文里明确标出当前目标是什么已经完成了哪些步骤让模型随时能对齐方向不至于跑偏。6.3 处理工具调用失败的完整策略工具失败是常态不是异常。完整的处理策略应该是分层的失败类型处理策略是否重试网络超时自动重试 2 次是参数错误把错误返回给模型让它修正否让模型决定权限不足直接拒绝记录审计否目标不存在返回给模型让它换策略否服务不可用降级到备用方案或终止视情况关键原则是能自动恢复的自动恢复不能的要把决策权交回给模型而不是直接崩溃。6.4 成本控制的几个狠招Agent 烧钱是出了名的因为一次任务可能触发十几次模型调用。控制成本我有几个实用招数缓存高频决策相同状态下的相同决策直接复用结果不用每次都问模型。分级调用简单判断用轻量模型复杂推理才用大模型。提前终止任务目标达成后立即结束别让模型再想想有没有遗漏。限制循环硬性设置最大步数配合连续重复调用检测。我实测下来这几招组合使用成本能压到原来的三分之一左右效果基本不受影响。6.5 上线前必须检查的清单最后给一份上线前的检查清单都是血泪教训换来的最大循环次数是否设置超时是否设置危险操作是否有人工确认或权限拦截工具失败是否有兜底会不会直接把异常抛给用户日志是否脱敏是否记录了完整的调用链路上下文是否会超窗超窗后怎么处理成本是否有上限告警超了会不会自动熔断模型返回格式异常时解析是否会崩长任务中断后能否从断点恢复这份清单看着琐碎但每一条背后都是真实踩过的坑。Agent 这东西demo 阶段和上线阶段完全是两回事能跑通不代表能跑稳能跑稳不代表能跑得起。把上面这些想清楚你的 Agent 才算真正从玩具变成了工具。