直接做 Agent 工程，干了两年多，踩遍了"循环失控"、"上下文爆炸"、"工具调用失灵"这些坑之后，再回头看现在的 Agent 项目，你会发现市面上所有能落地的东西，本质上都离不开三个抽象：Harness、Loop、Graph。这不是某个框架的发明，而是 Agent 工程从玩具走向生产系统时，必然长出来的三层骨架。这篇就围绕这三层架构，把每一层到底解决什么问题、层与层之间怎么配合、生产环境里这么设计能换来什么，全部拆开讲透。别指望看完就能写出生产级 Agent，但至少可以让你在下一轮架构评审里，不再被"这个 Agent 能不能扛并发""这个循环会不会死掉"这类问题问住。
1. 三层架构的整体认知：为什么一定是这三层
1.1 一个 Agent 项目从零到一，最先缺的是什么
很多团队刚开始做 Agent，第一反应是"调用大模型 API，写提示词，解析返回结果"。跑一个 Demo 确实不难，一个 Python 脚本加一个简单的 while 循环就够了。但等到要接真实业务、接多个工具、要控成本、要排错的时候，麻烦全出来了：模型偶尔输出 JSON 带点尾巴，工具一次没调成，对话历史越塞越长，同一个任务跑三次结果都不一样。这时候你才意识到，真正的问题不是"怎么调大模型"，而是"怎么把一次模型调用，包装成一个可控、可观测、可扩展的执行过程"。
这就是 Harness、Loop、Graph 存在的意义。Harness 管的是 Agent 的"外部能力"——模型怎么配、工具怎么接、上下文怎么组织、日志怎么埋；Loop 管的是 Agent 的"内部思维"——模型怎么反复推理、工具结果怎么反馈、什么时候该停；Graph 管的是 Agent 的"整体流"——任务怎么拆、分支怎么走、并行怎么合。三层各管一段，组合起来才能让一个 Agent 从"能跑"变成"能扛"。
1.2 分层不是为设计而设计，是为了控制"不可控性"
我给非技术朋友打过一个比方：Harness 是汽车的驾驶舱，按键布局、仪表盘、安全气囊都在这一层；Loop 是发动机的运转循环，吸气、压缩、做功、排气周而复始；Graph 是导航系统，哪里拐弯、哪里上高速、哪里有岔路，提前规划好。没有导航，发动机再强也只是原地轰鸣；没有驾驶舱，操作再娴熟也无处下手。
从这个类比能看出分层的第一性目的：把不确定性隔离开。模型本身的输出是概率性的，工具的执行结果是不可预测的，外部输入是多变的。如果这些不确定性全部搅在一起，任何一个小抖动都会导致整个流程崩塌。Harness 把"模型和工具的不确定性"限制在可控区间；Loop 用循环结构把"多步推理的不确定性"收敛成一个结果；Graph 则把"业务流程的不确定性"变成显式的图结构，每一条边、每一个条件判断都可以单独审查和测试。
我在实际项目里见过不少反面案例，比如把全部工具调用逻辑写在循环里，没有 Harness 做统一封装，结果三十个工具函数散落在多个文件里，互相引用、参数混乱，最后改一个工具的入参，影响面波及七八个节点。再比如用纯循环做复杂流程，想在中间插入一个人工审批节点，结果只能靠 if-else 硬编码，代码越改越烂。三层架构的约束，本质上是在帮你提前划好雷区：哪块逻辑归哪层管，不要在错误的地方用错误的手段解决问题。
2. Harness 层：Agent 的"驾驶舱"与运行环境
2.1 Harness 到底封装了什么
Harness 这个词在 Agent 工程里的准确理解，是一个"统管 Agent 运行所需一切外部依赖的容器"。它不是某个单一功能，而是一个组合体。我自己的项目里，Harness 层通常包含五块能力：
模型配置：基础模型选哪个、温度参数怎么设、是否启用流式输出、多模型切换策略（比如复杂任务走强模型，简单任务走轻模型）。这些不应该散落在业务代码里，而是统一放在 Harness 配置里，做到一处修改、全局生效。
工具注册与调度：Agent 能调用哪些工具，每个工具的入参、出参、权限、调用方式（同步/异步）、超时和重试策略是什么。有些 Harness 实现还会做工具自动选择，根据任务类型把无关工具临时摘掉，减少模型误调用的概率。
上下文管理：系统提示词怎么拼、历史对话怎么截断、检索到的资料怎么注入、大段工具返回结果怎么压缩。这块最容易被低估，但也是"上下文爆炸"问题的多发区域。
观测与追踪：每轮模型调用的输入输出、每次工具调用的耗时结果、全局的 token 消耗，全部以结构化日志的形式记录。没有这一块，生产环境里出了问题你连从哪儿排查都不知道。
安全与隔离：敏感操作前的二次确认、输出内容的合规过滤、工具调用的权限校验。Agent 的自主性越强，这一块越重要，甚至应该单独做成一个安全层。
2.2 工具注册与上下文管理的核心机制
工具注册这块，我看到的主流做法是"声明式注册 + 运行时校验"。你定义一个工具函数，标注清楚它的名称、描述、参数结构（通常用 JSON Schema），Harness 启动时把它们统一收集起来，转成模型可读的 tools 协议格式。这样做有一个明显好处：工具元信息和实现代码放在一起，不会出现"文档里写了一个参数，代码里却是另一个"的错位问题。
上下文管理则要特别说说。很多人以为把历史消息一股脑丢给模型就行，等到上下文窗口被占满才开始想办法。我的经验是，与其事后压缩，不如事前做"分段注入"——系统提示词单独占一个 segment，业务上下文占一个 segment，工具调用历史单独管理，这样既方便按权重做截断，也方便针对不同 segment 设置不同的保留策略。早期我最常犯的错误就是把所有内容拼成一段超长文本，结果模型的理解力明显下降，后来改成结构化分段之后，长对话场景的效果立刻改善。
提示：Harness 层最容易犯的错是"过度封装"。我见过有的团队把模型调用包了五六层抽象，为了支持"未来可能的扩展"，结果改一个小小的提示词要翻四个文件。Harness 不需要把每个细节都封装起来，把边界定清楚，把频繁变化的东西收敛到配置里，就够了。
2.3 Harness 与 Agent 框架的关系
市面上的 Agent 框架，比如 LangChain、LlamaIndex、Pydantic AI，其实都内置了部分 Harness 能力。但如果只依赖框架自带的那一套，到生产阶段通常会吃力的。框架可以帮你把基础功能搭好，但真正的 Harness 一定要基于你自己的业务场景去做定制：你的工具链是特有的，你的上下文格式是特有的，你的安全机制是特有的，这些是一套通用框架给不了你的。
我现在的项目里，Harness 层是一组接口加一个配置中心，Agent 主体逻辑不感知模型厂商和工具实现的细节，只管面向接口编程。这样做的代价是前期要多写一些胶水代码，但收益在于后续无论是换模型、加工具还是调策略，都只是配置变化，不用动业务代码。
3. Loop 层：Agent 的"思维循环"与执行引擎
3.1 从一次调用到多轮循环：Agent 的本质特征
单次的大模型调用不叫 Agent，只能叫"增强型问答"。Agent 和普通 AI 服务的本质区别在于"多轮自主决策"——模型观察当前状态，决定要调用什么工具，拿到工具结果后重新推理，再决定下一步动作，直到达成目标或到达终止条件。这个"观察—推理—行动—再观察"的过程，就是 Loop 层要管的核心。
我在团队内部画过一张示意图，一个标准的 Agent Loop 包含四个阶段：
观察：收集当前任务目标、历史对话、工具返回结果、环境状态，形成模型可读的上下文。
推理：模型基于当前上下文思考，输出下一步意图，可能是继续调用某个工具，也可能是给出最终答案。
行动：解析模型的工具调用指令，对参数做校验，执行真实工具调用，获取结果。
更新：把工具结果写回上下文，循环进入下一轮，直到满足终止条件。
这个循环看起来简单，实际工程里每个环节都有数不清的细节。只说一个最常见的坑：模型第一次返回的工具参数里，某个字段格式和工具要求的不一致，比如它给了一个数字字符串，而工具要用整数。如果你在行动阶段不做类型转换和校验，工具直接抛错，循环就会走进异常分支。别指望模型每次都输出完全规范的 JSON，生产级的 Loop 必须在"行动"之前加一层严格的参数解析和校验，甚至要具备根据报错信息自动修正参数重试的能力。
3.2 循环收敛：让 Agent 知道什么时候该停
Loop 层比"循环本身"更重要的是"循环的终止条件"。这一块如果不设计好，Agent 就会陷入两个极端：要么过早停止，任务没完成就给出了半吊子答案；要么无限循环，在几个工具之间反复打转，token 烧完才被熔断。
我常用的终止条件有四种，实际项目中通常会组合使用：
任务完成判定：模型输出明确表示已完成，且包含了最终答案。判定词可以是"FINAL_ANSWER""任务完成"等约定标记，也可以让模型输出结构化结果，由 Harness 层校验必填字段。
最大轮次限制：给循环设上限，比如最多 15 轮工具调用。这是一个兜底保护，防止任何逻辑漏洞导致无限循环。生产环境里这个限制一定要有，而且要根据业务场景谨慎调整，太小会误杀正常任务，太大则失去保护意义。
成本预算限制：跟踪累计 token 消耗，超过预算后强制终止，进入降级流程（比如转人工、转轻量模型）。尤其在模型费用敏感的场景，这个比最大轮次更有效。
人工介入：关键时刻让真人确认，确认通过才继续执行。这是目前所有生产级 Agent 都应该保留的一个兜底。
我在一个表单自动填写项目里遇到过典型的循环问题：Agent 在一次填写失败后，反复尝试用同样的方式重新提交，连续循环了八次，每次都在同一个校验错误上失败。原因是提示词里没有约束"当遇到明确的业务规则校验失败时应该停止并报告"，而只有"如果失败就重试"。后来我在系统提示词里加了一条"如果同一个错误连续出现两次，停止尝试并认为任务失败，输出失败原因"，再配合最大轮次限制，这个问题才算根治。
3.3 Loop 的错误处理与自愈机制
Loop 的另一个关键设计是"错误后的自愈路径"。工具调用大概率会失败：网络超时、第三方接口限流、参数不合法、数据格式变化。如果只做简单重试，很多问题会重复发生。正确的做法是区分错误类型：
临时性错误（超时、限流、瞬时的网络抖动）：自动重试，采用指数退避策略，重试次数限制在 2-3 次。
参数性错误（工具入参不合法、缺少必要字段、类型不匹配）：不重试，而是把详细的报错信息喂回给模型，让模型基于报错修改参数后重新调用。
业务性错误（业务规则校验失败、数据冲突、权限不足）：立即终止该路径，向用户返回明确的失败原因，不要盲目重试。
这个分类在代码里可以做成一个统一的异常处理中间件，挂在工具调用的外层。我见过最愚蠢的做法是所有的错误一视同仁地重试三次，结果一个参数性错误被重试三次，白白浪费 token 和时间，还把日志刷得没法看。
实操心得：Loop 层一定要做"思考痕迹"的留存。每一轮模型推理时，把它的思考过程、工具调用决策、结果摘要都记录下来。这不仅是审计需要，更是调试 Agent 的核心抓手。很多 Agent 表现异常的根因不看思考痕迹根本定位不到。
4. Graph 层：从线性循环到可控的工作流编排
4.1 为什么纯 Loop 撑不起复杂业务
先澄清一个容易混淆的概念：Loop 是单次任务内部的推理循环，Graph 是多个任务步骤之间的编排结构。一个复杂业务，比如"调研竞品 → 生成对比报告 → 发送到内部群"，单个 Loop 搞不定，因为步骤之间有关联和条件分支，需要一种更高层的组织方式。
如果硬用纯 Loop 做多步骤任务，会面临三个问题：状态难以管理，每一步产生的结果散落在上下文里，下一步怎么引用全靠模型自觉；分支逻辑不清晰，条件判断只能写在提示词里，模型可能判断错，还没有办法人工干预；步骤不可复用，流程一多，每一条路径都要重新写一遍循环，代码大量重复。
Graph 层解决的就是这些问题。它把业务流程抽象成一个有向图：节点表示一个具体的执行步骤（可能是一个子任务、一个工具调用、一个判断条件），边表示执行顺序和依赖关系。图上可以挂条件分支、并行节点、循环子图，整条流程的"形状"是显式的，可以被测试、被监控、被人为干预。
4.2 Graph 的核心元素：节点、边与状态
要理解 Graph 层，至少要搞清楚三个核心概念。
节点（Node）：一个节点就是一次"执行单元"，它可以是调用一个子 Agent（内部又有自己的 Loop），可以是调用一个工具函数，也可以是一个纯逻辑节点（比如条件判断、数据清洗）。节点之间通过边连接，每个节点接收上游传入的数据，处理后传给下游。
边（Edge）：边表达流向。最简单的是"顺序边"，上一个节点完成，下一个节点开始。复杂一点的是"条件边"——根据上游节点输出的内容，决定走哪个分支。再复杂的是"循环边"，某一部分流程可以被重复执行，直到满足退出条件。
状态（State）：这是 Graph 与 Loop 最大的不同。Loop 的"上下文"是隐式的、向模型暴露的连续文本；Graph 的"状态"是显式的、由你定义的数据结构。比如一个报告生成流程的 State 可以包含research_results、draft_content、review_comments、final_version等字段，每个节点只读写自己需要的字段。这样状态流转完全可控，不依赖模型的"记忆"。
我最初从纯 Loop 迁到 Graph 时，最大的不习惯就是状态设计。以前"让模型记住上一步的结论"靠的是把结论写进对话历史，模型通常能记住，但偶尔会记混。后来用 Graph 显式地把关键结果写入 State，节点之间传参不走上下文，准确率立刻上来了，而且每一步的数据都能精确定位。
4.3 分支、并行与人工节点的生产意义
Graph 真正的工程价值体现在三种特殊节点的设计上。
分支节点：代码里就是 if 条件，但 Agent 工程里常常让"模型来决定条件"。比如一个客服 Agent，先判断用户意图，是退换货、咨询还是投诉，然后走不同的处理子流程。这个"意图分类"可以是一个独立的 LLM 节点，输出一个结构化的分类标签，Graph 根据标签路由到对应分支。这样做比在提示词里让模型"自己看着办"要稳定得多——意图判断的准确率可以被单独测评和优化。
并行节点：有些步骤彼此独立，比如同时查三个不同的数据库，或者同时调用多个外部 API，Graph 支持把它们并排列出，所有节点完成后统一汇总。在提效这件事上，并行往往比优化单个模型的推理速度更能立竿见影。
人工审批节点：高风险的业务操作（发送对客邮件、执行转账、删除数据）必须有人工确认。Graph 里把这些操作设计成一个"暂停节点"，运行到此处时流程暂停，等待人工通过 API 或消息系统确认后才继续。这在纯 Loop 架构里实现起来极其痛苦，在 Graph 里则只是节点类型的一种。
4.4 用 Graph 控制复杂度的经验
Graph 也不是越多越好。我见过把 Graph 用到极致的团队，一张体系图塞了几百个节点，几乎无法维护，加一个新功能要在一个巨型图里找半天位置。我的经验是遵循"漏斗式分层"：顶层保持简洁，每个大步骤是一个子图，细节在子图里展开。主图最好控制在 5-8 个节点，给一个非技术的产品经理也能看懂；真正复杂的逻辑下沉到子图里。
另一个经验是"图结构和代码描述要保持一致"。有些框架允许你用代码声明式地构建图，但生成的图结构很难直观预览；有些框架提供可视化界面。不管用哪种，一定要保证团队对"当前线上的流程长什么样"有共识，否则改了一个节点连带的边界条件没人能说清楚。
5. 生产实践：三层架构如何在一个真实项目里协作
5.1 一个典型的"智能资料整理 Agent"架构拆解
用一个我自己做过的项目来串起三层架构。背景是企业内部需要定期整理外部竞品动态，收集公开信息、过滤噪音、按模版输出周报。任务不算特别复杂，但流程长、环节多、还有人工审核，纯 Loop 绝对搞不定。
开始设计时，我把它拆成了四个主节点，对应一个 Graph：资料抓取 → 内容清洗与去重 → 分析师子 Agent 摘要 → 人工审核并发送。主图大概 6 个节点，每个节点内部再有子图或者内置一个 Loop。
Graph 的顶层：入口节点（接收任务参数，比如竞品名单和时间范围）、抓取节点（调用各类检索工具，并把原始结果写入 State 的raw_docs字段）、清洗节点（纯代码逻辑，不经过模型，做格式规范化、去重）、摘要节点（一个内置 Loop 的子 Agent，加载模板并生成摘要初稿）、审核节点（挂起等待人工确认）、发送节点（确认通过后发送，并归档）。
这个架构里，Harness 层负责所有外部工具的接入：搜索 API、网页抓取工具、企业内部分发接口，以及统一的两套模型配置（强模型用于摘要生成，轻模型用于意图分类），上下文策略也在这里定义。Loop 层主要活在该子 Agent 内部：摘要 Agent 需要先读所有原始资料，然后生成提纲，再根据提纲逐段撰写，中间可能要多次调整措辞；这个"多次迭代"就是 Loop 的工作。Graph 层承担整体的流程编排、条件分支和人工审核中断。
5.2 状态传递与数据流设计
这个项目里，State 的设计是最关键的部分。我定义了大约八个字段：task_config、raw_docs、cleaned_docs、summary_drafts、review_status、final_content、dispatch_log、error_log。每个节点只负责读写和自己相关的字段，上下游之间不直接传对象，而是通过 State 读写接口完成。
选择这要样的设计是出于一个特别实际的考虑：便于并行和重放。并行节点各自写入不同的字段，互不冲突；执行失败时能精确定位到是哪个字段没有赋值，哪个节点没跑完。调试时还能把一个 State 快照导出，在测试环境里"重放"整个流程，这个能力在生产排错时极其好用。
另一个实际收益是"上下文隔离"。顶级 Graph 的各个节点内部有各自的 Loop，这些 Loop 的上下文相互隔离，不会出现上一个节点的历史对话污染下一个节点的情况。以前用单一大循环做整条流程时，问题层出不穷：摘要 Agent 会"记住"上次检索的噪音信息，或者把上一步的中间结果当成最终结论。Graph 的隔离机制把这类问题从根上解决了。
5.3 可观测性与日志体系怎么搭
三层架构的每一层都要对应到可观测性设计。我的日志体系分成三级，和三层架构对应：Harness 层记录每一次模型 API 调用的耗时、token 消耗、温度参数；Loop 层记录每一轮的推理摘要、调用的工具、返回的结果摘要、重试原因；Graph 层记录每个节点的开始/结束时间、状态快照、分支走向、审批动作。
生产环境里真正会被逼疯的是两个问题：一个是"模型为什么做了这个决策"，一个是"这个流程为什么会卡住"。三级日志体系基本能把这两个问题回答清楚。我还会在 State 变化的关键节点输出 diff 日志，显式标出"哪个字段被哪个节点改了"，这在实际排错中省了太多时间。
5.4 并发能力与资源控制
标题里相关的热词还有"AI Agent 怎么扛并发"，这里展开说一下三层架构对并发的支撑。三个层各自要做的并发处理完全不同。
Harness 层的并发重点是 API 限流与队列管理。我通常会做一个按任务维度分组的调度器，控制同一时刻发往模型供应商的请求数，避免触发限流。可以做一个简单的信号量控制：
import asyncio from contextlib import asynccontextmanager class ModelRateLimiter: def __init__(self, max_parallel=8): self._sem = asyncio.Semaphore(max_parallel) @asynccontextmanager async def acquire(self): async with self._sem: yield这个限流器在 Harness 层的模型调用接口前统一挂上，不管上游有多少任务并发进来，实际打到模型接口的并发都控制在安全水位。核心逻辑就是"吞吐量优先在用户侧排队，不要让供应商把你封了"。
Loop 层的并发重点是工具调用的超时和并发。一个 Loop 内部可能同时调用多个工具，用asyncio.gather做并行，但每个调用都要设置超时，否则一个慢工具会拖死整个循环。
Graph 层的并发重点是节点间的依赖关系。相互独立的节点天然可并行，Graph 引擎要能识别这类依赖并自动调度。如果每张图都是串行跑，那并行节点的设计就白做了。
6. 常见问题与排查经验实录
6.1 Agent 陷入循环出不来，怎么排查和根治
现象：Agent 在同一个工具上来回调用，每次参数几乎相同，结果也一样，但就是不停。
排查步骤：第一步，看 Loop 层日志里的"思考痕迹"，确认它是真的没有意识到重复，还是意识到了但提示词没给它"该停"的指令。第二步，看最大轮次限制是否生效，如果生效了为什么没有走降级分支。第三步，看工具返回的结果是否每次一致，如果工具结果是相同报错，说明是"参数修复失败"的问题。
根治方案：在系统提示词加入"相同错误不得连续重试超过一次"这类护栏；对工具调用结果做哈希去重，检测到连续相同行为时强制跳出；提高最大轮次数或者引入成本熔断。我建议先做工具结果去重，这个在代码层面就能搞定，不需要依赖模型的自觉性。
6.2 上下文爆炸与"记忆丢失"
现象：任务进行到中后段，模型开始"忘记"早期的重要信息，或者回答质量明显下降。
根因：上下文管理策略太简单，把整个过程产生的所有内容都堆到对话历史里，窗口被占满后，早期的关键信息被截断，或者模型注意力被噪音分散。
解法：Harness 层做按 segment 的结构化上下文管理，关键信息（任务目标、用户约束、中间结论）放进"持久区"，普通对话内容放进"滚动区"并限制保留轮数；定期用一个小模型做"关键信息抽取"，把长对话压缩成结构化摘要写入上下文。这个技巧我用过很多次，效果立竿见影，唯一的代价是每次摘要多一点 token 开销，但比起上下文爆炸带来的失败和重试成本，这点开销完全可以接受。
6.3 工具调用参数总是出错
现象：模型生成工具调用，参数经常不合法，字符串、数字类型混淆，必填字段缺失，枚举值超出范围。
根因：工具描述和参数 Schema 不够详细，或者模型本身在长上下文下的工具调用精度下降。有时候问题出在 Harness 层没做好参数校验，错误信息没有回传给模型。
解法：把工具参数的 JSON Schema 写细，每个字段的枚举值、格式、示例都写清楚，别指望模型看到"string"类型就自动会传对；参数校验放在工具执行前，校验失败时把结构化的错误信息返回给模型，并给一句"根据错误信息修改参数后重新调用"的指令；实在频繁出错的场景，可以在工具调用与执行之间加一个小型"参数修复专用模型"，用轻量模型专门做参数修正，成本很低，准确率提升明显。
6.4 多任务并发时状态互相污染
现象：两个任务同时跑，结果一个任务的中间结果写进了另一个任务的 State，或者日志里面出现了另一个任务的上下文。
根因：对"每个 Agent 实例"的隔离做得不彻底。Loop 内部使用了一些全局变量，或者 State 被设计成单例/类级别的对象，并发跑的时候就互相踩。
解法：状态对象必须按"一次运行一个实例"，每次任务分配独立的 State 对象和对应的日志上下文 ID（trace ID）；工具调用队列也要按实例隔离，不要在多个 Agent 实例之间共用同一个工具执行器；把并发测试写进 CI，每次改动都跑一遍双任务并发用例。
注意：这里的"并发"指的是应用层同一进程内多任务并发，不要和模型供应商侧的高并发混淆。很多团队在设计时没在意实例隔离，生产环境第一次上并发压力就翻车，提前在设计上就把"一个任务一个 State 实例"的原则钉死，后续能避免大量事故。
7. 三层架构与工程框架的选型建议
7.1 源码还是框架：各有利弊
现在聊到落地，免不了要说框架。市面上的 LangGraph、Pydantic AI、自研 Graph 引擎各有取舍。
LangGraph这类重框架，最大的优势是图引擎成熟，状态管理、断点恢复、人机交互都有现成的方案，社区资料也多。劣势是抽象层厚，出了问题你要翻框架源码才能搞明白，调试成本高；升级版本还可能破坏旧行为。
Pydantic AI这类轻框架，胜在模型定义清晰、类型安全好，适合 Hint 面。但 Graph 能力相对简单，复杂流程还得自己叠一层。
自研是很多团队走过弯路之后的选择。我的观点是，如果团队有比较强的工程能力，且 Agent 的业务逻辑是非标准化的，自研一个轻量引擎并没有想象中那么贵——核心就是状态管理、节点调度、日志追踪、人工介入，大约一至两周能搭出一个够用的骨架。自研的优势是完全掌控修改边界，没有被框架升级绑架的风险。但如果你只是想快速验证业务价值，建议直接用成熟框架，别一上来就自研，前期可以省下大量时间。
我在项目里的做法是"框架做底座，自研做外壳"：Graph 引擎用选型好的框架，Harness 和业务编排完全自研，这两层属于业务高度相关的地方，框架的通用抽象帮不上太多忙。
7.2 对团队能力的要求
三层架构对团队的最小要求是：每个人都要能区分"这三层在项目里各自负责什么"。Harness 层需要熟悉模型 API 和工具链，Loop 层需要理解推理循环和异常处理，Graph 层需要会做流程建模和状态设计。一个人全干也不是不行，但很容易出现"某一层特别强、其他两层薄弱"的不均衡状态。在我见过的团队里，最常出现的问题是 Graph 层变成摆设——图标得天花乱坠，实际执行还是靠写死代码拼出来的。这种"伪 Graph"架构往往比真 Graph 更脆弱，因为图结构已经名存实亡，但没有人发现。
如果团队刚起步，我的建议是不要急着上完整的三层架构。先用一个最简单的 Loop（模型加一个工具循环）跑通一个端到端场景，理解 Agent 的执行过程；然后引入 Harness，把工具和上下文管理规范化；最后等出现了多步骤、分支、人工介入这类需求时，再引入 Graph。循序渐进，比一开始就上一个复杂框架然后陷入抽象陷阱要有效得多。
7.3 三层架构的演进方向
聊点扩展的方向。多层架构不是终点，用 Harness 和 Graph 搭建起的 Agent 工程底座，天然有一个演进路径：Harness 层的下一步是强化自省能力——让系统自动评估上下文质量，主动压缩或补充信息，而不是等模型犯错后再修；Loop 层的下一步是多 Agent 协同循环——几个 Loop 并行跑、互相校验结果，类似"生成—批评—修改"的对抗模式；Graph 层的下一步是动态组装——不再固定一张图，而是让模型根据任务现场动态生成图结构，再交给执行引擎去跑。这条路很难，但现在越来越多的框架开始探索了。
回到实际操作，我个人最大的体会是：这套三层架构不是哪个框架、哪篇论文发明的教条，而是从一次次线上事故里"长出来"的实践约束。它帮助团队在模型层、工具层、流程层之间划出清晰的边界，让排错有了方向，让测试有了粒度。理解它、掌握它，再去评价一个 Agent 项目的工程质量，你的判断会精准很多。
