目录一、从一次请求开始而不是从三个方块开始一一次任务请求的完整生命周期二Demo 架构与生产架构差的不是模型三参考系统的业务目标与硬约束二、七层全景架构一七层是怎么划出来的二控制平面与数据平面三、逐层展开一第一层接入层1、身份与租户2、配额与限流3、幂等与去重4、同步异步分派与对外契约二第二层会话与上下文层1、上下文装配是一次预算分配不是一次字符串拼接2、三类会话状态必须分开存3、上下文包应该是一个结构化对象三第三层编排层1、内部结构路由、计划、状态机、舱室2、编排层的四条纪律3、最容易出问题的四个地方四第四层模型访问层1、这一层做五件事2、抽象到什么程度算合适3、降级策略的四个层次五第五层工具与集成层1、一次工具调用要穿过六道关卡2、四类工具四套治理要求3、工具描述本身就是接口文档六第六层数据与状态层1、五类数据2、三条容易踩的线3、状态与上下文不是一件事4、多租户隔离的三个层次七第七层治理与观测层四、横切关注点与信任边界一三条横切关注点及其断点二信任边界与威胁落点三一次高风险任务的跨层时序五、契约、故障与可运维性一五个关键的层间契约二故障落点地图六、三种落地形态与演进一层是逻辑划分服务是物理划分二决策表与推荐流程三演进路线与退出成本七、架构评审检查清单八、结论与延伸一本文结论二与专栏其他文章的衔接参考资料干货分享感谢您的阅读生产级 Agent 的架构图不应该从「模型、工具、记忆」三个方块开始画我们建议应该从一次真实请求的生命周期开始推。这次我们以企业任务执行 Agent 为样本沿着一句自然语言到一份回执的完整路径推出接入、会话与上下文、编排、模型访问、工具与集成、数据与状态、治理与观测七层说明每层的责任、层间契约、故障落点与信任边界并给出单体、服务化、平台化三种落地形态的决策表与演进路线。本节作为读者你将获得什么一张可以直接拿去做架构评审的七层全景图以及每一层「为什么需要它」的推导过程而不是一份组件清单。五个写下来的层间契约运行上下文、上下文包、模型调用、工具调用、提议它们决定了这张图能不能用来分工和验收。三条横切关注点身份与租户、预算、可观测在每一层的落点以及它们最常见的断点位置。一张故障落点地图每层的典型故障、外在表现与兜底动作可以直接转成告警文案与 Runbook 第一步。单体分层、服务化分层、平台化三种形态的适用条件、不适用条件、七维对比与迁移退出成本。关于数据的说明本文的业务场景、占比与量级均为示例场景与示例值用于说明结构关系不是任何真实系统的实测结果。还有设计的代码入如果写的有问题的请您在评论区留言提醒感谢一、从一次请求开始而不是从三个方块开始一一次任务请求的完整生命周期大多数 Agent 架构图长得很像一个方块写「大模型」一个方块写「工具」一个方块写「记忆」中间几根箭头。这类图的问题不是画错了而是它回答不了任何一个工程问题——控制权在哪、状态存在哪、失败了谁兜底、出了事怎么查。换一个起点拿一句真实的请求把它从进入系统到产出回执的全过程摊开。请求是「帮我给新来的三位同事开通测试环境权限下周一之前生效」。摊开之后是七个阶段接入、理解、规划、取数、裁决、执行、交付。这条链路上一共发生了 4 次模型调用、9 次外部系统调用6 次只读、3 次写、2 次状态机持久化、1 次人工审批、1 次成本归账与 1 条完整轨迹。模型调用只占其中不到五分之一。架构要覆盖的是全部这十七件事而不只是那四次模型调用。更重要的是每个阶段都有它自己的失败方式接入阶段可能租户越界、配额耗尽、重复提交理解阶段可能意图误判、槽位缺失被静默填了默认值规划阶段可能子任务依赖排错、并发度过高把下游打爆取数阶段可能某一路超时、数据口径不一致裁决阶段可能提议越权、循环不收敛、预算触顶执行阶段可能重复写、部分成功、审批超时交付阶段可能回执与实际动作不一致、轨迹缺失。七个阶段二十一类故障没有一类的根因是「模型不准」。这就是为什么架构要从生命周期开始推每个环节都会逼出一个具体问题——谁来做、失败了怎么办、状态存在哪、出了事怎么查——这些问题的答案加起来才是架构。二Demo 架构与生产架构差的不是模型一个能演示的 Demo 大概是五个组件用户输入、提示词拼接、模型调用、工具执行、返回结果。一个进程一段脚本一下午能跑通。一个能上线的系统大概是二十二个组件其中与模型直接相关的只有三个。这不是在说 Demo 没有价值。Demo 回答的是一个真正不确定的问题「这件事模型到底能不能做」这个问题必须先回答而且应该用最便宜的方式回答。问题出在下一步——很多团队把 Demo 当成了架构的第一版然后在它上面往外长。结果是那五个组件成了系统的骨架而真正该做骨架的二十二个组件变成了补丁。那十七个多出来的组件不是凭空加的每一个都对应一条上线硬要求多租户 → 鉴权、配额、数据隔离有副作用 → 幂等、补偿、审批、审计长任务 → 状态机、持久化、恢复成本可控 → 预算闸门、归账、降级可运维 → 轨迹、告警、开关、回归。去掉任何一条要求对应的组件就可以不要。这也给出了架构设计的第一个动作不是画方块图而是把上线硬要求逐条列出来再从每条要求推出需要哪些组件。顺序反过来的后果是组件多了没人能说清为什么需要它组件少了要等到线上才发现而谁也无法判断这版架构是否够用。三参考系统的业务目标与硬约束本文以及本专栏后续文章统一使用同一个参考系统企业任务执行 Agent。员工用自然语言提任务系统跨多个业务系统把事办完。它要具备的能力理解任务并判断是否需要澄清检索企业知识库并提供可核验引用以只读方式查询业务数据库调用工单、权限、通知等业务接口生成结构化报告与文件对高风险操作发起人工审批支持长任务、异步执行、断点续跑与取消支持多租户、权限隔离、审计与成本统计。它的硬约束有五条本文后面的每一层都会被其中至少一条约束1. 所有写操作必须可审计到人且可回答「依据是什么」2. 跨租户数据绝对隔离检索与查询都不例外3. 单次任务的模型成本有上限触顶要有明确降级路径4. 高风险动作必须有人工确认环节5. 任一能力必须可以在不发版的情况下关闭。参考技术栈按 Python 3.12、FastAPI、Pydantic、PostgreSQL、Redis、消息队列、OpenTelemetry、Docker 来谈。但下面的架构讨论与具体技术栈无关换成 Java 或 Go 的同类组件结论不变。二、七层全景架构一七层是怎么划出来的划层的依据只有一条把「变化原因相同」的东西放在一起把「变化原因不同」的东西分开。接入层随对外协议变化会话与上下文层随交互形态变化编排层随业务流程变化模型访问层随供应商与模型版本变化工具与集成层随下游系统变化数据与状态层随数据模型与合规要求变化治理与观测层随运维与合规要求变化。七个变化源七层。这个划法的好处是当某一件事发生变化时能立刻知道该改哪一层以及需要通知谁。需要强调的是最后一层的位置。治理与观测层被画在最下面只是版面原因它实际上包在外面——它的每一项能力都要穿过全部六层才有意义。把它画成「最底下一层」是很多架构图失真的原因。还有一个观察值得先说出来七层里只有「模型访问层」与模型有关其余六层是任何一个严肃后端系统都需要的东西。这既是好消息也是坏消息。好消息是大部分工作在你熟悉的领域坏消息是不能因为「这是个 AI 项目」就跳过这些工作。二控制平面与数据平面在展开每一层之前先立一条贯穿全图的原则。控制平面决定做什么路由策略、计划与依赖、预算与配额、权限与策略、模型与提示词版本、开关与灰度。数据平面实际去做模型调用、工具调用、检索执行、状态读写、副作用提交、结果与轨迹上报。分开之后能做到四件事灰度只需改控制平面的分流比例不动数据平面代码回滚只需把版本号改回去历史任务仍按当时版本可复现审计有明确的规则快照而不是靠回忆权限判定集中在一处数据平面只执行已被批准的动作。不分开的典型形态是预算写在提示词里权限判定散落在各个工具实现里模型版本硬编码在调用处。后果是三件事同时做不了——无法在不发版的情况下调整策略无法回答「这次任务用的是哪个版本」无法在一个地方关掉某个能力。落地时不需要一上来就拆成两个服务。最小要求是三条1. 每次任务启动时生成一份「运行上下文」把版本、预算、权限、开关固化成快照2. 数据平面的所有组件只读这份快照不再自行读配置3. 快照随任务一起落库可按任务号取回。三、逐层展开一第一层接入层接入层不产生业务价值但它决定了系统能不能被安全地开放出去。它有四项责任。1、身份与租户解析调用方身份可能是人也可能是另一个系统确定租户与数据边界然后把身份放进运行上下文。关键纪律是后续所有层不再重新解析身份也不再从请求体里读取任何身份相关字段。身份一旦在这里确定它就是可信的在别处重新解析等于开了第二扇门。2、配额与限流按租户、用户、任务类型三级配额控制并发任务数与排队深度上限。超限时要明确拒绝并给出原因而不是排队——排队只是把问题推给下游并且让用户失去判断依据。3、幂等与去重客户端传入请求幂等键相同键在有效期内返回同一个任务号。这一条防的是两类很常见的重复用户重复点击以及网关层的自动重试。没有它「网关超时重试一次」的直接后果就是同一份权限被开通两遍。4、同步异步分派与对外契约按预估耗时决定返回形态短任务同步返回长任务返回任务号。流式通道与取消通道也在这一层统一定义。对外契约有四个每一个都必须在这一层定义清楚提交任务返回task_id, status, estimated_seconds, trace_id。任务号是后续一切查询、取消与审计的锚点。查询状态返回status, progress, partial_result, cost_so_far。长任务必须能中途看到进展否则用户只能干等。取消任务返回accepted或already_done。取消语义必须有明确回答「无响应」是最差的结果。流式输出事件类型至少包含step、delta、approval、done。审批与进度也是事件不能只流式输出文本。最常见的两个遗漏是没有取消语义用户关掉页面后台循环还在烧钱且没人知道以及没有幂等键。接入层是系统的第一道信任边界这一层之外的一切输入都是不可信的。二第二层会话与上下文层这一层做的是一件事把「模型这次能看到什么」变成一个有边界、可解释、可复现的决定。1、上下文装配是一次预算分配不是一次字符串拼接装配流水线有五步候选收集会话历史、任务状态、检索结果、工具说明、相关性筛选、预算切分、压缩改写、装配与封存。为什么不能「把能塞的都塞进去」五个理由每一个都足以单独成立成本上下文长度直接决定单次调用成本而循环里每一圈都要重付一次注意力无关内容会挤占模型对关键约束的关注表现为「明明写了它却没照做」时延长上下文的首 Token 时间明显变长泄露把不该让当前租户看到的检索结果塞进上下文等于绕过了权限系统不可复现每次装配结果都不同的话同一条请求就无法复算。所以关键动作是「预算切分」这一步先按角色分配 Token 配额系统约束多少、任务描述多少、历史多少、检索多少、工具说明多少再在各自配额内做筛选而不是先到先得。2、三类会话状态必须分开存会话状态多轮对话的消息与指代生命周期跟随会话可过期清理任务状态这次任务做到哪一步、产出了什么、失败过几次生命周期跟随任务必须持久化用户状态长期偏好与授权记录生命周期跟随用户需要可查询可删除。三者混在一个session对象里是多轮串线与跨租户泄露的主要来源。它们的存储介质、过期策略、权限模型、删除要求全都不同混在一起意味着必须按最严格的那一套来管所有数据或者按最宽松的那一套——前者浪费后者出事。3、上下文包应该是一个结构化对象它不是一段字符串而是一个带结构的对象系统约束不可被后续内容覆盖、任务描述与已确认槽位、已执行步骤的结构化摘要、检索片段带来源 ID 与权限标记、工具说明只含本次允许调用的、预算余量提示。结构化的好处是每一部分都能单独计量、单独裁剪、单独在轨迹里被审查。当线上出现「模型忽略了约束」时第一件事是去看那次运行的上下文包里系统约束段是不是被挤掉了。三第三层编排层编排层是整个系统里唯一决定「下一步做什么」的地方也是唯一应该有这种权力的地方。1、内部结构路由、计划、状态机、舱室意图路由按意图与租户策略选择处理通道四条通道各有不同的 SLO、预算与降级策略只读问询检索加生成无写操作最短路径不进状态机、标准事务模板展开步骤固定进状态机带幂等与审批、组合任务多子任务并行加聚合需要依赖管理、长尾处置进舱室全程留痕产出的提议由状态机再走一遍标准事务通道。计划与依赖把任务展开为步骤模板展开、依赖图与并发度、步骤级超时与重试。关键在于计划本身要被校验——无环、无越权、每个步骤都是已注册的动作。模型生成的计划里包含一个不存在的步骤如果不在这里拦住就会执行到一半才报错而此时前面的副作用已经发生了。任务状态机持有显式状态与转移表待澄清、待执行、待审批、执行中、已完成、已取消。每次转移落库重启后可恢复。受限自主舱室只在长尾通道进入。它的出口只有结构化提议执行交回状态机步数、Token、墙钟三个硬上限由编排层持有。2、编排层的四条纪律控制流只能在这一层。任何一个工具实现里出现「如果……就再调一次别的工具」都是控制流泄漏。这类泄漏的危害是隐性的它让编排层的计划不再等于实际执行的步骤于是追踪、预算、审计三件事同时失真。状态只能通过状态机改变。直接改库绕过转移表恢复逻辑立刻失效因为恢复依赖「当前状态一定是转移表里的合法状态」这个前提。预算由本层持有并向下传递模型访问层与工具层只做计量与上报不做判定。舱室是可选组件。关掉它系统应当退化为纯确定性编排并继续工作。如果关掉舱室系统就跑不起来说明确定性通道的覆盖不够这是一个需要立刻处理的信号。3、最容易出问题的四个地方计划没有校验状态机缺少超时转移等审批的任务永远停在「待审批」没人发现并发度不受控一个任务展开成三十个子任务同时打下游把别人的服务打挂舱室与状态机耦合舱室直接改状态于是「关掉舱室」变成一件危险的事。四第四层模型访问层这一层的判断标准只有一句上层代码里不应该出现任何一个厂商专有字段。1、这一层做五件事能力抽象把对话、工具调用、结构化输出、嵌入抽象成稳定接口、模型路由按任务难度、风险、预算选择模型策略可热更新、输出契约JSON Schema 校验校验失败时修复或重试不放行、重试与降级、计量与归账按任务号记录输入输出 Token、缓存命中与耗时。2、抽象到什么程度算合适过薄的抽象只是包一层 HTTP 调用厂商字段照样透传给上层等于没做。过厚的抽象试图抹平所有能力差异结果是最强模型的能力被抽象成最弱模型的公约数白白损失效果。合适的做法是分两类通用能力走统一接口专有能力显式声明调用方按能力探测决定用不用而不是假装它不存在。判断标准很简单换一个供应商需要改几个文件答案应该是一到两个。3、降级策略的四个层次第一层是同模型重试限流或超时指数退避重试通常能解决多数瞬时问题。第二层是同级替换切到能力相当的另一个模型或另一个区域结果质量基本不变但必须在轨迹里标记否则评测结论会被污染——你以为在评测 A 模型实际上有 8% 的样本跑在 B 模型上。第三层是能力降级切到更小的模型同时收窄任务范围例如只做分类不做生成并向用户明确说明结果的局限。第四层是明确失败。这一层最常被忽略但它很重要把失败伪装成低质量结果代价通常比直接失败更高因为用户会基于错误结果做决定。五第五层工具与集成层工具层是系统里所有副作用的唯一出口也是权限收口的地方。1、一次工具调用要穿过六道关卡名称解析工具是否在本次白名单内、参数校验Schema 校验与范围检查、权限判定租户、用户、资源三元组、幂等处理幂等键生成与重复检测、执行与熔断超时、重试、熔断、降级、结果规范化统一错误类型与证据 ID。六道关卡里第三道和第四道最容易被省掉因为它们在 Demo 阶段看不出作用。2、四类工具四套治理要求只读查询查员工档案、查权限模型、查审批进度无副作用但需要按租户过滤的数据视图、查询预算、结果脱敏。检索知识库语义检索、条款精确匹配无副作用但权限过滤必须前置到检索请求里返回结果必须带可核验来源 ID。写操作建单、改单、开通权限、发通知有副作用且难撤销需要幂等键、风险分级、人工审批、补偿动作登记。执行环境脚本执行、文件生成、浏览器访问有副作用且半可控需要沙箱隔离、网络白名单、CPU 内存时间限额。3、工具描述本身就是接口文档模型看到的工具名称、参数说明与错误类型决定了它调用成功的概率。把内部字段名如bizType、flag2直接暴露给模型等于让它猜。工具描述应当按「给一个没读过代码的新同事看」的标准来写。工具层是第二道信任边界模型的输出在这里从「文本」变成「动作」。所有在编排层做过的校验在这里都要再做一次——因为工具层无法假设调用它的一定是自己人。六第六层数据与状态层五类数据五套生命周期、五套权限策略。混在一起会同时出三种问题。1、五类数据任务状态状态、步骤、产物、错误、版本快照跟随任务归档后长期保留需要强一致存储。丢失的后果是长任务无法恢复。会话与短期记忆消息历史、指代、当前槽位跟随会话可过期清理内存缓存加落盘。最大风险是串线导致跨用户信息泄露。长期记忆用户偏好、已授权事项跟随用户必须可查询可删除。最大风险是写入无门槛导致错误被固化——一条错误的「该用户偏好自动审批」会一直影响后续所有任务。知识与索引文档、条款、向量与倒排跟随知识版本。最大风险是权限未前置导致越权检索。轨迹与审计调用链、决策、成本、审批记录保留期由合规要求决定通常按年。缺失的后果是事故无法复盘。2、三条容易踩的线把任务状态放进缓存——缓存一重启所有在途长任务全部失联。把检索索引按全量建、查询时再过滤权限——只要有一处忘记过滤就是越权正确做法是把过滤前置到检索请求里让索引层本身不可能返回越权结果。把轨迹和业务日志混在一起——两者的保留期与检索方式完全不同混在一起的结果通常是两边都不好用。3、状态与上下文不是一件事这是一个很常见的混淆。任务状态是系统的事实做到第几步、产出了什么、谁批过。它必须完整、可恢复。模型上下文是本次调用的输入它是任务状态的一个裁剪视图可以有损、可以压缩、可以省略。把上下文当状态存会丢信息恢复时发现关键中间结果被摘要掉了把状态当上下文传会爆预算把三十步的完整记录全塞进提示词。4、多租户隔离的三个层次逻辑隔离同库同表加租户列靠代码保证过滤成本最低、风险最高必须配合强制的数据访问层让「不带租户的查询」在编译期或运行时直接失败。模式隔离同库不同 schema连接时绑定租户能显著降低误查概率。物理隔离独立实例适用于有数据驻留要求的大客户。选哪一层取决于合规要求不取决于工作量。七第七层治理与观测层这一层有六项能力全链路追踪、指标与 SLO、成本归账、策略与护栏、评测与回归、开关与灰度。为什么说它包在外面因为这六项每一项都要穿过全部六层才有意义追踪要串起接入到交付成本要归到每一次模型与工具调用策略要在编排层判定、在工具层强制开关要能作用到任意一层。上线前不需要把六项做全但下面三项缺一不可1. 追踪 ID 贯通能按任务号取回完整轨迹2. 成本能按任务归账能回答「这一单花了多少」3. 有一个可以在不发版的情况下关掉高风险能力的开关。四、横切关注点与信任边界一三条横切关注点及其断点身份与租户、预算与配额、可观测——这三条不属于任何一层它们穿透所有层。任何一层漏掉一条整条链路上的保证就断了。身份断在哪就在哪泄露。最常见的断点是检索编排层已经拿到了正确的租户但检索请求没有把它带下去于是模型在上下文里看到了别的租户的文档。这类问题不会报错只会在某天被用户发现。预算断在哪就在哪超支。典型断点是工具层某个工具内部又调了一次模型例如做结果摘要这次调用不在编排层的预算账本里。任务级预算于是永远算不准而且这类隐藏调用最难被发现因为它在架构图上根本不存在。观测断在哪就在哪查不到。典型断点是异步边界任务被投递到队列之后追踪 ID 没有随消息一起传递于是执行侧的日志与提交侧对不上。一次事故的一半时间会花在把这两段日志手工拼起来。三条横切关注点的共同落地方式是同一个把它们放进运行上下文并让每一次跨层调用都必须携带运行上下文。在类型系统里把它做成必填参数比写在规范文档里有效得多。二信任边界与威胁落点把系统里的数据分成三个区不可信区用户原始输入、外部网页与文档、第三方 API 返回、知识库中的用户投稿。半可信区模型输出的文本、模型生成的提议、检索片段、历史会话内容。可信区系统配置与策略、工具白名单、权限判定结果、状态机转移表。三个区之间有两道闸。不可信到半可信这一道靠「当数据不当指令」所有外部内容在进入上下文时统一包裹为数据段并显式标注来源任何出现在数据段里的祈使句都不改变系统行为。半可信到可信这一道靠「重新校验」模型产出的每一个字段在变成动作之前都要按可信区的规则重新验证一遍。威胁落点按层来看接入层是伪造身份与越权访问上下文装配是间接注入检索到的文档里写着「忽略之前的指令」编排层是诱导跳过审批、生成越权计划工具层是参数注入与重复执行数据层是跨租户读取与敏感字段外泄。每一条的缓解手段都落在具体的层上而不是靠一句「加强提示词防护」。三一次高风险任务的跨层时序把前面所有讨论放进一次真实执行里给三位同事开通测试环境权限含一次人工审批与一次部分失败重试。这张图想说明三件事控制权全程在编排层。模型层与工具层从不互相调用——模型不会直接触发工具它只是产出一个「打算调用某工具」的意图由编排层决定是否真的调用。这个区别在架构图上只是一根箭头的方向在生产里是能不能做权限管控的分水岭。每一次跨层调用都携带同一个运行上下文快照包括异步投递到审批队列的那一次。审批通过之后回来的消息仍然带着最初那份快照所以「按当时的规则执行」是可以保证的。失败发生在工具层但决定「接下来怎么办」的仍然是编排层。三个写操作里两个成功一个返回 409工具层只负责把这个事实规范化上报补偿与重试的决策在编排层做。如果让工具层自己决定重试就会出现「工具层重试三次全失败编排层还以为一次都没试过」这类问题。五、契约、故障与可运维性一五个关键的层间契约架构图上的每一根连线背后都应该是一个写下来的契约。五个最关键的是运行上下文trace_id, task_id, tenant, actor, model_version, prompt_version, budget(steps, tokens, seconds), allowed_tools[], policy_version。由编排层在任务开始时生成并封存中途不可修改。上下文包系统约束不可覆盖、任务与已确认槽位、已执行步骤、检索片段带chunk_id, source, acl、工具说明仅本次允许的、预算余量提示。模型调用请求能力类型、消息或 Schema 或工具规格、路由提示难度与风险返回内容、工具调用意图、用量输入、输出、缓存命中与实际model_id。工具调用请求工具名须在白名单内、参数按 Schema 校验、幂等键、actor、tenant返回ok或error(type, retryable)以及供引用与审计的evidence_id。提议动作须在动作枚举内、参数、理由、置信度、证据列表缺失则整条作废。由舱室产出由编排层校验执行仍走标准事务通道。用代码表达运行上下文大致是这样一个不可变对象from dataclasses import dataclass, field from typing import Mapping dataclass(frozenTrue, slotsTrue) class Budget: max_steps: int max_tokens: int max_seconds: float dataclass(frozenTrue, slotsTrue) class RunContext: 任务开始时生成并封存数据平面的每个组件只读它不再自行读配置。 trace_id: str task_id: str tenant: str actor: str # 发起人用于权限判定与审计 model_version: str # 本次运行绑定的模型版本 prompt_version: str # 本次运行绑定的提示词版本 policy_version: str # 本次运行绑定的策略版本 budget: Budget allowed_tools: frozenset[str] # 本次允许调用的工具白名单 flags: Mapping[str, bool] field(default_factorydict) # 开关快照 def with_scope(self, tools: frozenset[str]) - RunContext: 进入受限舱室时收窄工具集只能变小不能变大。 if not tools self.allowed_tools: raise ValueError(舱室工具集必须是外层工具集的子集) return RunContext(**{**self.__dict__, allowed_tools: tools})这段代码的要点有三个它是 frozen 的所以中途没人能改with_scope只允许收窄不允许放宽这让「进入舱室后权限只会更小」成为类型层面的保证所有版本号都在里面所以「这次任务用的是哪一版」永远有答案。契约写下来之后四件事成为可能每一根连线可以单独测试每一次跨层调用可以被记录成结构化事件而不是自由文本日志版本演进有依据回放成为可能。契约演进有三条规则只增不改新增字段必须有默认值删除走两步先标记废弃并统计使用量归零后再删语义变更等同于新字段把某个字段的取值含义改掉比删掉它更危险因为它不会报错只会算错。这三条与普通的接口演进纪律完全一致没有任何特殊之处。二故障落点地图这张表可以直接拿来用把「外在表现」这一列当成告警的文案来源把「兜底动作」这一列当成 Runbook 的第一步。如果某一行的兜底动作目前还不存在那这一行就是下一个迭代要补的东西。表里唯一一个跨层的问题是部分成功它发生在工具层但只有编排层知道该补哪一部分。所以补偿逻辑必须写在编排层而不是写在工具实现里。这一点值得单独强调因为「在工具里加个重试」是最自然的第一反应也是最容易埋下不一致的做法。六、三种落地形态与演进一层是逻辑划分服务是物理划分同一份七层责任有三种落地方式。单体进程内分层七层全部在一个服务里以模块与包边界划分。适用于单团队、单租户或少量租户、日请求量十万级以内、业务边界仍在探索。优点是部署简单、调试直接、跨层调用零网络开销代价是扩容只能整体扩、故障隔离弱、多团队协作时冲突多。服务化分层接入、编排、工具、治理拆成独立服务模型访问做成网关。适用于多团队协作、多租户、工具数量上百、不同层的扩容需求差异大。优点是按层独立扩容与发布、故障隔离、权限收口清晰代价是跨层调用要处理网络失败、分布式追踪成为必需、本地开发环境变重。平台化编排、模型网关、工具注册、治理做成共享平台业务方只提供领域工具与配置。适用于公司内多个业务线都要做、需要统一治理与成本归账、有专职平台团队。优点是治理一次建设全员受益、新业务上线周期最短代价是平台本身需要产品化、业务方灵活性受限、平台故障是全局故障。一条常被忽略的事实是三种形态的七层责任完全相同区别只在于边界是模块边界、网络边界还是组织边界。这意味着从单体走向服务化并不需要重新设计架构——前提是单体阶段就按七层划清了模块且层间契约是显式的。二决策表与推荐流程第一步先看四个硬条件任一命中直接定档有数据驻留或物理隔离要求的租户 → 至少服务化且数据层可独立部署多个业务线复用同一套治理 → 平台化团队人数少于六人且业务边界未定 → 单体分层不要提前拆工具数量超过五十且由多方提供 → 至少服务化工具层必须独立。不满足任何硬条件时默认单体分层。然后按七个维度初始交付速度、独立扩容能力、故障隔离、治理一致性、多团队协作、运维复杂度、退出成本对照决策表。推荐决策流程是四步先按硬条件定档单体阶段就按七层划模块、把五个层间契约写成代码里的类型当某一层出现独立扩容需求或独立发布需求时把那一层拆出去只有当第三个业务线提出同样需求时才考虑平台化。最贵的两个错误是过早服务化五个人维护七个服务绝大部分精力花在联调与发布上和过晚拆分单体里层与层之间互相直接访问对方的数据结构到了必须拆的时候发现契约根本不存在只能重写。两个错误的共同解药都是单体阶段就把契约当真。三演进路线与退出成本四个阶段每个阶段都能独立交付业务价值第一阶段·能跑通单体七层划模块只做只读通道状态在关系库有追踪 ID 与成本归账。退出判据只读通道端到端成功率达标追踪与成本可按任务号查到。退出成本几乎为零。第二阶段·能写加入状态机与幂等、审批与补偿工具注册表成形契约写成类型。退出判据写操作全部经过幂等与审批重启后在途任务可恢复。退出成本低。第三阶段·能扩拆出工具服务与模型网关接入分布式追踪按层独立扩容灰度与开关平台化。退出判据任一层可以独立发布且不影响其他层。退出成本中等。第四阶段·能共享编排与治理产品化多业务线接入统一评测与门禁、统一成本与配额。退出判据第二个业务线在不改平台代码的前提下完成接入。退出成本高。没达到判据就进下一阶段是返工的最常见来源。尤其是第二阶段——很多团队在幂等还没做好的时候就去拆服务结果是把一个数据一致性问题变成了一个分布式数据一致性问题。迁移成本的真实构成中代码重构通常不是最贵的部分。最贵的是三样契约变更引发的多方联调参与方越多成本越接近平方增长历史数据迁移状态机的状态定义一旦变更在途任务要么迁移要么跑完两条路都要写一次性代码评测基线重建架构变了原有评测结论未必还成立需要重新跑一遍回归并解释差异。把这三项算进排期迁移决策才是诚实的。七、架构评审检查清单分层与职责四项七层责任已明确到人没有「暂时先放这里」的组件控制流只出现在编排层工具实现里没有编排逻辑模型访问层之上没有任何厂商专有字段所有副作用只经过工具层这一个出口。契约与状态四项五个层间契约已写成类型或 Schema而不只是文档运行上下文在任务开始时封存且不可变状态机转移表可打印、可评审五类数据分开存储各有生命周期与权限策略。横切关注点四项身份贯通到检索与数据访问无断点预算贯通到每一次模型与工具调用包括工具内部的模型调用追踪 ID 跨越异步边界仍然连续成本能按租户与任务类型归账。安全与可靠四项三个信任区与两道闸已明确外部内容统一作为数据段包裹不作为指令每一层的典型故障都有兜底动作与告警部分成功的补偿逻辑写在编排层。演进与退出四项当前处于哪个演进阶段有明确结论进入下一阶段的退出判据已写下来迁移成本按三项构成分别估算过有一键关闭高风险能力的开关且演练过。这二十项里只有三项与模型有关。生产级 Agent 架构的主体是把已经成熟的后端工程纪律正确地施加到一个输出带有不确定性的组件周围。八、结论与延伸一本文结论第一架构不应该从「模型、工具、记忆」三个方块开始画而应该从一次真实请求的生命周期开始推。生命周期上的每个环节都会逼出一个具体问题这些问题的答案加起来才是架构。第二七层的划分依据是「变化原因」而不是「调用顺序」。接入、会话与上下文、编排、模型访问、工具与集成、数据与状态、治理与观测对应七个不同的变化源。第三控制平面与数据平面必须分开最小实现是一个在任务开始时封存、中途不可变、随任务落库的运行上下文。第四三条横切关注点身份、预算、可观测穿透所有层它们的断点分别导致泄露、超支与查不到。把它们做成运行上下文里的必填字段比写在规范文档里有效得多。第五五个层间契约决定了这张架构图能不能用来分工和验收。没有契约的架构图只是示意图。第六三种落地形态的七层责任完全相同区别只在边界类型。单体阶段把契约当真是后续所有演进的前提。第七二十项架构评审项里只有三项与模型有关——这既说明大部分工作在熟悉的领域也说明不能因为「这是个 AI 项目」就跳过这些工作。二与专栏其他文章的衔接《Agent 工作流实战》专栏导读地图与阅读路径说明-CSDN博客「这个需求到底要不要做成 Agent」的判定方法在《先别急着做 AgentChatbot、Workflow 与 Agent 的边界》给出本文编排层里那个「受限自主舱室」的内部实现在《不依赖框架实现最小 Agent模型、工具、观察与终止》用最少代码拆开本文提到的每一层「可上线」标准如何量化成验收条件在《「能跑」不等于「可上线」生产级 Agent 的验收标准》展开本文故障落点地图里的每一类缺口在《Agent Demo 上线为何频繁翻车12 类隐性工程缺口》逐条给出成因与修法七层责任由自研还是由现成框架承担在《Agent 框架怎么选自研、编排框架、工作流引擎与托管平台》给出评估矩阵。参考资料架构方法与分层Domain-Driven Design ReferenceEric Evans —— 限界上下文与分层的经典表述本文「按变化原因划层」与之同源。Fundamentals of Software Architecture 配套资源 —— 架构特性、权衡分析与决策记录的方法。Architecture Decision Records —— 把架构决策与其理由固化下来的轻量格式配合本文的层间契约使用。C4 Model —— 分层次绘制架构图的记法适合把本文七层展开成不同抽象级别的图。Agent 与 LLM 应用架构Building effective agentsAnthropic 工程博客 —— 编排模式与「何时需要自主」的讨论。A practical guide to building agentsOpenAI —— 护栏、工具与编排的落地建议。Model Context Protocol 规范 —— 工具与上下文接入的开放协议对应本文工具层的注册与发现。状态、工作流与一致性Temporal 文档Workflows —— 持久化执行与确定性重放。AWS Step Functions 开发者指南 —— 状态机式编排的具体形态与限制。Saga Patternmicroservices.io —— 跨系统副作用的补偿模型对应本文的部分成功处理。Idempotency-Key HTTP 头草案IETF —— 幂等键在 HTTP 层的标准化尝试。可观测性与成本OpenTelemetry 文档 —— 追踪、指标与日志的统一模型。OpenTelemetryGenerative AI 语义约定 —— 模型调用与工具调用的标准化字段。Site Reliability EngineeringGoogle在线全文 —— SLO、错误预算与故障响应。安全与多租户OWASP Top 10 for LLM Applications —— 提示注入与过度代理权限的标准分类。OWASP API Security Top 10 —— 接入层与工具层的通用风险清单。PostgreSQL 行级安全策略 —— 在存储层强制租户隔离的一种做法。NIST AI Risk Management Framework —— 风险治理框架。