AI Agent 的工程架构从能力分层到运行闭环你可能写过一个很快能跑起来的 Agent Demo系统提示词、几个函数 schema、一次模型调用模型返回 tool call程序执行函数再把结果塞回模型。这个 Demo 很有价值它能说明模型确实可以选择工具。但只要放进真实环境问题很快就会出现用户可能从 Webhook、Slack、微信、定时任务进来工具可能写文件、跑命令、调用外部服务任务还要跨会话保存状态、失败后恢复、事后能追踪。这时Agent 就不再是“LLM 几个函数”的问题而是一个运行时系统的问题。问题入口最小 Agent Demo 的主路径很直接准备 prompt暴露工具等待模型返回工具调用执行再把结果交回模型。问题不在于 Demo 简陋。Demo 的目标是验证机制不是承载长期协作。生产级 Agent 的分界线不在工具数量而在系统能否在真实环境中长期、安全、可恢复地运行。维度Demo Agent生产级 Agent状态管理进程内上下文会话、任务、记忆、知识、审计可持久化工具执行直接函数调用schema、权限、审批、超时、trace、replay guard失败处理抛异常或返回错误retry、fallback、降级、明确停止条件可观测性看最终回答看模型调用、工具调用、审批分支和投递路径会调用工具只说明有行动接口能否成为可用 Agent要看工具调用是否进入闭环、是否受权限约束、是否能被追踪和复盘。所以本篇不讲“怎么多接几个工具”而是讲 Agent 架构为什么必须分层以及分层之后如何组成运行闭环。能力分层如果把所有逻辑都写进一个AgentLoop短期看代码最少长期看每个变化都会牵动主流程换模型要改主循环新增通道要改主循环调整审批策略要改主循环接入 MCP 也要改主循环。真正的分层不是为了画图好看而是为了控制变化的位置。为了不停留在抽象层面下面以 echo-agent 的实现为例。书稿中把它拆成配置与启动、事件、状态、推理、行动、安全、认知、协作、接入和观测等层。层数看起来多但每一层都在吸收一种真实变化。层主要职责不分层会怎样通道层把 CLI、Webhook、Gateway、Cron 转成内部事件核心逻辑被平台 SDK 污染事件层队列、订阅、并发、背压输入一多就变成异步脚本堆积状态层会话、任务、记忆、审计持久化重启后丢上下文长期协作中断推理层上下文构建、模型路由、工具循环、压缩LLM 调用和系统状态混在一起行动层工具注册、参数校验、执行器、结果回写工具越多副作用越不可控安全层风险分级、路径策略、网络策略、审批只靠模型“自觉”避免危险动作观测层trace、span、日志、health、评估只能看最终回答无法复盘过程这些层的共同目标只有一个让变化在局部发生。平台变了改通道模型变了改 provider 和 router工具变了改 registry 和 executor风险策略变了改安全层。Agent LoopAgent 的核心不是“模型在中间”而是“反馈闭环”。如果系统只是把用户输入交给模型再把模型输出返回用户它仍然是增强版问答系统。只有当模型输出能引发行动行动结果又能回到下一轮推理时Agent 才真正形成闭环。书稿中echo-agent 的主路径集中在 PipelineContextStage负责模型应该看到什么InferenceStage负责模型如何决定和行动ResponseStage负责这次处理如何收尾并影响未来。它不是线性管道而是带内部循环的闭环。这个结构可以压缩成一段伪代码async def process_event(event): session await sessions.get_or_create(event.session_key) ctx await ContextStage.build(event, session) ​ while not ctx.done: decision await InferenceStage.call_model(ctx) if decision.final: return await ResponseStage.finalize(ctx, decision) ​ approval await ApprovalGate.check(decision.tool_call, ctx) result await ToolRegistry.execute(decision.tool_call, ctx) \ if approval.allowed else approval.to_model_feedback() ctx.add_tool_result(result)这段伪代码的重点不在语法而在控制权的分配模型提出行动意图系统负责校验、审批、执行、记录再把结果交还给模型。LLM 是推理引擎Agent 是运行时系统。模型负责开放推理系统负责把推理放进可治理环境。如果用户说“帮我检查这个项目最近的测试失败原因”闭环不是一句“可能是依赖问题”。它至少要接收事件、构造上下文、运行测试工具、读取日志、把工具结果交回模型最后保存会话并投递回答。三面结构只按“感知、推理、行动”看 Agent容易把它误解成三个函数。真实系统里更有用的拆法是控制面、数据面和认知面。控制面负责策略和治理配置、安全 profile、工具暴露、审批规则、模型路由、任务调度。它回答“系统允许什么”。数据面负责实际流动InboundEvent、OutboundEvent、会话消息、工具参数、工具结果、模型请求和模型响应。它回答“信息如何流动”。认知面负责模型可见世界系统提示词、历史、记忆快照、知识引用、技能摘要、工具定义、计划注入和压缩摘要。它回答“模型基于什么判断”。这三面不能混在一起。控制面错误会导致越权行动数据面错误会导致消息丢失或错投认知面错误会导致模型基于错误上下文推理。会话会影响认知但不是权限控制ApprovalGate属于控制面但审批结果也要作为反馈进入认知面。失败路径闭环系统的优点是自适应缺点是错误也可能被放大。一次错误记忆如果被保存未来可能反复进入上下文一次错误工具结果如果没有结构化标记模型可能继续沿着错误事实执行一次危险工具如果被自动放行调度器可能在未来重复触发。因此生产级 Agent 必须把失败路径设计为一等公民。失败位置需要的工程机制模型失败provider retry、fallback、兜底响应、健康状态工具失败结构化错误、超时、circuit breaker、重复调用阻断审批失败拒绝、超时、取消都反馈给模型和用户存储失败自动重连、降级或明确错误通道失败避免单个平台拖垮整个 bus这不是悲观设计而是生产系统的基本现实。Agent 越自主越需要知道“做不成时怎么停下来”。架构成熟度往往不体现在 happy path 多漂亮而体现在失败路径是否可控。生产可用性判断一个 Agent 是否接近生产可用不要只看它能不能演示复杂任务。更硬的标准是看它的行为是否可检查。工程项可检查问题Tool call trace工具参数、结果、错误、耗时和依据是否可追踪风险分级是否区分只读、低风险写、高风险写和外部可见动作审批节点高风险动作是否能暂停并等待用户确认权限边界工具是否受路径、网络、凭证和 allowlist 约束状态持久化会话、任务进度、记忆、调度任务是否能跨重启恢复失败恢复是否有重试、降级、回滚或明确停止条件评估回归关键任务是否有评估集和回归测试行动解释系统能否说明每一步为什么发生、哪些结果已验证这些机制会增加复杂度但它们不是装饰。没有 trace问题无法复盘没有权限边界工具越多风险越大。生产级 Agent 的目标不是让模型拥有无限自由而是让模型在明确边界内发挥推理能力。echo-agent 的架构可以概括为一句话用工程系统约束模型用模型能力驱动行动。小结本篇只讲一个点Agent 的工程架构本质上是在开放世界里管理不确定性。能力分层让变化局部化运行闭环让行动基于反馈推进控制面、数据面和认知面让治理、流动和模型可见世界各自有边界。echo-agent 在这里不是定义 Agent 的依据而是工程案例它用 MessageBus、SessionManager、Pipeline、ToolRegistry、ApprovalGate、MemoryStore、KnowledgeIndex 和 Observability把 Agent Loop 落到可运行系统里。不是所有 AI 应用都应该做成 Agent。路径稳定、输入结构化、风险很高的任务Workflow 往往更合适主要从资料里找答案的任务RAG 可能已经足够。Agent 的价值是在风险边界内推进开放式、多步骤、不确定的任务。理解这一层后面再看启动流程、配置装配、工具系统、记忆系统和多 Agent 协作就不会把它们误解成零散模块。它们共同服务的是同一件事让语言模型进入可控制、可恢复、可审计的运行闭环。全篇完本文为 echo-agent 设计笔记系列第 02 篇。项目源码已开源至 GitHub。如果你对工业级 Agent 的工程落地感兴趣欢迎加入技术交流群参与日常讨论。下一篇我们将探讨 《Agent 系统的启动流程从配置到运行时》敬请期待。