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 Loop

Agent 的核心不是“模型在中间”，而是“反馈闭环”。如果系统只是把用户输入交给模型，再把模型输出返回用户，它仍然是增强版问答系统。

只有当模型输出能引发行动，行动结果又能回到下一轮推理时，Agent 才真正形成闭环。

书稿中，echo-agent 的主路径集中在 Pipeline：ContextStage 负责模型应该看到什么，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 系统的启动流程：从配置到运行时》，敬请期待。