我记得自己第一次正经写Agent，是在一个自动化运营工具的项目里。需求很简单——让AI根据用户输入自动查数据库、调接口、回邮件。一开始我想得特别天真：不就是循环调LLM吗？给它一个system prompt，加几个function，让模型自己决定怎么调用，完事。结果真正接到生产环境里，才发现问题远没有那么简单：长时间运行时上下文越塞越满，模型开始答非所问；两三个工具还行，几十个工具注册进去后准确率直线崩塌；重试、超时、并发限制，每一件事都在等着你去踩一遍坑。所以那之后我开始认真思考一个问题：Agent开发需不需要一个自己的"架构"？
答案当然是要的。这也是我写"构建你的Agent框架"这一系列内容的初衷——不是鼓励你去造重复的轮子，而是希望你在动手写任何Agent之前，脑子里先有一张完整的设计图。本文是第七章7.1节，聚焦整个框架的总纲：整体架构设计。它决定了你后续所有模块（模型接入、推理循环、工具注册、记忆管理、编排模式）的边界和关系，也直接关系到这个Agent是能跑通Demo，还是能扛住生产。这章面向的读者是：已经跑通过最简单的"LLM+Function Calling"Demo，正准备从脚本式代码往结构化框架演进的人。
1. Agent框架到底在解决什么问题
1.1 从"调模型"到"跑完一个任务"的距离
先说结论：Agent框架不是为了让模型调用更花哨，而是为了把"单次模型调用"升级为"可靠的任务执行系统"。
单次LLM调用是这样的：输入Prompt → 模型生成 → 拿到文本，完结。
Agent执行是这样的：输入目标 → 模型规划 → 调用工具 → 观察结果 → 调整计划 → 再调用工具……直到达成目标或主动放弃。
这两者之间的差距，就是Agent框架的价值空间。说白了，框架就是一套"执行骨架"：它帮你处理好哪些事呢？我列一下核心职责：
- 管理Agent执行时的状态，包括当前目标的进度、步骤、中间产物。
- 维护模型对话的上下文，让模型始终知道"现在在哪一步、刚才干了什么、接下来可以做什么"。
- 编排规划-行动-观察的循环，处理工具调用结果的解析、异常归类、重试策略。
- 提供统一的资源边界，如并发控制、token预算、工具权限、沙盒隔离。
- 把每个环节做成可插拔的，这才叫框架，而不是一个写死的脚本。
现实世界里，很多人把Agent直接理解为"LLM+工具循环"。这句话不算错，但太粗了。它只描述了"跑起来"的最小闭环，没有回答"怎么跑得好、扛得住、出问题时怎么收敛"。
1.2 框架的三大核心义务：状态、流程、边界
我在设计Agent框架时习惯把问题收敛为三件事：状态管理、流程编排、边界控制。
状态（State）是很多初版实现最先出问题的地方。Agent在跑一个复杂任务的时候，它需要知道自己已经完成了什么，接下来要做什么，当前这个环节卡在哪个工具上。这些状态如果散落在各种局部变量里，一旦出现并发或重试，逻辑很快会乱成一团。正规点的做法是引入一个执行状态机，把Agent的每个阶段定义清楚：初始化、规划中、执行中、等待工具结果、异常处理、完成、终止。
流程（Flow）描述的是Agent怎么从一个状态迁到另一个状态。最基础的是ReAct式的循环，进阶一点有Plan-and-Execute、反射机制（Self-Refine）等。流程设计直接决定了Agent的稳定性和可调试性。
边界（Boundary）则是很多人会忽略的部分：Agent能访问什么工具？能使用多少token预算？怎么限流？怎么在出问题时安全熔断？框架层面的边界设计决定了Agent在生产环境中能不能被信任。
提示：设计框架的第一件事不是写代码，而是把这三大义务用文档画清楚。哪怕只在白纸上画一张图，也会让后续效率提升数倍。
2. 分层架构：Agent框架的基本骨架
2.1 模型接入层：让LLM调用变成可替换的抽象
很多人设计Agent框架时，第一步就把所有代码和某一个模型的API强耦合了。这在大模型迭代飞快的当下是很危险的。我建议在底层抽象一个模型接入层，所有上层逻辑只和抽象接口打交道，不直接碰具体模型。
模型接入层的核心接口大概是这样：
chat(messages, tools, **kwargs) -> model_response- 输入统一格式的消息列表和工具定义。
- 输出统一的响应结构，包括文本、工具调用请求、token用量等。
在这个抽象设计里需要考虑什么？
- 请求与响应的归一化。不同厂商的接口格式有差异，特别是工具调用的表达方式。有的模型用function call字段，有的用tool_calls字段，有的走XML协议。接入层要把这些差异吃掉，对外输出统一结构。
- 重试与流式处理。LLM接口经常超时或返回限流，接入层统一提供重试策略、退避算法、流式聚合。
- 模型路由。生产环境里，不同的任务可能由不同模型处理，比如简单分类用小模型、复杂推理用大模型、长文档用长上下文模型。接入层应该支持一种路由机制，让上层按任务类型选择模型。
有人可能会问：一个Demo真的需要这么精细的模型接入层吗？我的经验是，如果只是为了跑通Demo，确实不需要。但只要你打算把Agent放进业务流程，就早晚要面对"换模型、加模型、分配模型"的需求。先抽象出来，成本很低，收益却很高。
2.2 推理与规划层：核心循环的几种范式
Agent区别于普通LLM应用的核心，是它拥有"推理—行动"的循环。推理规划层就是实现这一循环的地方。
目前业界常见的循环模式有几种：
- ReAct：每轮让模型先思考（Reasoning），再决定采取什么行动（Action），执行工具后观察结果（Observation），不断循环。实现简单、可控性好，适合大多数任务。
- Plan-and-Execute：先把大目标拆解为多个子任务计划，再逐个执行。相比ReAct，它把"规划"和"执行"分开，避免每一轮都重复规划，效率更高，但对规划的准确性要求也更高。
- Reflection模式：在循环中加入"自我反思"环节，让模型评估自己之前的结果是否合理，再决定继续还是修正。它会增加token消耗，但对复杂任务的正确率有提升。
框架的推理层在设计上要注意什么？
- 循环终止条件必须是显式的，包括：达成目标（模型显式声明完成）、达到最大轮数、触发异常熔断。
- 必须支持人工介入。生产环境里的Agent不应该完全自主，架构上要留出中断点，让人可以观察、修正、批准工具调用。
- 循环状态要外部可见、可序列化。这样即便进程崩溃了，也能从某一步恢复，而不是从零重来。
注意：不要一上来就搞花哨的多阶段复杂循环。能把标准的ReAct循环写得干净、可观测，再去加Plan-and-Execute等模式，一步一个脚印会更省心。
2.3 工具层：工具注册与调度
工具层是整个Agent和外部世界交互的桥梁。模型接入层解决的是"怎么和LLM说话"，工具层解决的是"LLM打算做什么，框架怎么做"。设计工具层时，我主要考虑这几个点：
- 工具注册表：一个中心化的工具注册表。一个工具至少包含函数名、描述、参数Schema（JSON Schema格式）、权限等级、执行入口。注册表负责校验工具定义是否合法、去重、索引。
- 工具调用的路由与执行：模型返回"用户想调用工具A，参数是xxx"之后，框架要校验参数、执行函数、捕获执行结果，再以消息形式注入模型上下文。
- 工具执行的错误处理：工具调用不像LLM生成那样容错。一次真实的HTTP请求失败、数据库超时、文件不存在，都需要框架统一处理并反馈给模型，让模型可以调整策略，而不是直接让整个Agent崩溃。
这里有个经验之谈：工具的"可发现性"设计非常重要。当工具数量超过几十个时，模型常常会选错工具或编造工具名。一个常见缓解手段是给工具做分组或者命名空间，描述信息写清楚使用场景和边界条件，必要时还可以用子Agent做工具检索。
2.4 记忆层：短时、长期与工作记忆
说到Agent记忆，很多人一开始容易忽略，但后期不得不回来补的模块。我在设计框架时，会把它拆成两个层面来考虑。
第一层是对话上下文记忆，本质是和模型的短时交互记录。它的设计重点是上下文管理：不用的内容及时裁剪、关键信息做总结压缩、保险起见保留原始日志。否则Agent跑了几轮tool调用之后，prompt会膨胀到模型无法有效聚焦。
第二层是跨会话的长期记忆，它依赖于外部存储。常见的做法是把用户信息、项目历史、领域知识等转成向量后存入向量数据库，需要时语义检索再放回上下文。金融、医疗、企业知识库等场景里，长期记忆往往是核心卖点之一，但前提是要做好权限与数据隔离，否则会把不该泄露的信息带进推理。
在设计记忆层时，我还有一个自己的做法：引入类似"工作记忆"（working memory）的概念，专门存放当前任务产生的中间状态，比如检索到的文档片段、工具返回结果、推演中的候选方案。它和长期记忆的分工很明确：工作记忆随任务的推进而不断更新和清理，任务结束后可以不再保留，或按需沉淀进长期记忆库。这样Agent既不会"失忆"，也不会被过时信息拖拽住。
3. 编排层设计：从单Agent循环到多Agent协作
3.1 单Agent循环的可靠设计
在说多Agent之前，先把单Agent设计稳固。单Agent的循环是所有框架的底座。我把它拆成三个核心组件：
- Agent对象：暴露run(task)入口，内部维护状态机，统领循环。
- 上下文管理器：负责所有消息的增删改查，决定什么信息进模型、什么信息不进模型。
- 工具路由器：接收模型输出的工具调用，经过权限校验之后分发给对应执行器。
这三个组件在代码层面相互独立，通过数据解耦，可以让调试变得特别顺。比如上下文出问题了，只动上下文管理器，不需要动Agent主体。这也是"框架"的价值——它逼着你把职责分离，而不是把所有逻辑堆在一个大函数里。
还有一个特别容易被忽视的点：日志与可观测性。Agent循环是多轮次的，每一轮里模型看到了什么、模型输出了什么、工具返回了什么、为什么Agent决定终止，这些都应该有结构化日志。没有可观测性的Agent框架，在排障时就是一场灾难。我在实际项目里，始终会在每个循环周期打印一条标准格式的轨迹日志，包含轮次编号、动作类型、耗时、token消耗，排障时按时间轴回放，比拿着Prompt猜快了不是一点。
3.2 多Agent协作模式：主从、流水线与黑板模式
任务复杂到一定程度，单Agent会出现两个瓶颈：上下文窗口不够用，以及单一角色能力不够用。这时就要考虑多Agent架构。多Agent框架的本质，不是多个Agent一起跑，而是设计一套Agent之间的"通信协议"和"协作模式"。
业界实践中常见的模式：
- 主从模式（Orchestrator-Workers）：一个主Agent负责拆解任务、调度分发、整合结果，多个Worker Agent各司其职。这是最通用、最容易实现的一种模式。主Agent可以说就是"总编导"，Worker是"执行者"。
- 流水线模式（Pipeline）：任务被拆成多个阶段，每个阶段由专门的Agent处理，前一个Agent的输出作为后一个Agent的输入。适合结构固定的流程，比如"分析需求 → 生成代码 → 测试执行 → 结果汇报"。
- 黑板模式（Blackboard）：多个Agent共享一块"黑板"（公共状态区），各自读取、更新自己负责的部分，最终汇总成型。它在需要多个Agent交叉协作、共享中间结果的场景中很有效，但对同步和一致性要求更高。
在设计多Agent编排层时，有一个原则我认为最重要：多Agent模式只应在"收益 > 复杂度成本"时使用。如果单Agent能完成任务，就不要硬拆。多Agent带来的通信开销、状态同步问题、调试难度都是指数级上升的。
另外，关于"harness和agent的区别"这类问题，在编排层面其实有对应的答案。Harness更偏底层的一套执行与控制机制，可以简单理解为"Agent运行的环境与控制器"；Agent则是在这个环境上运行的智能主体，通过循环调用模型和工具完成目标。设计框架时，harness和agent往往是在不同层级上落地的——harness提供通用执行能力，agent在其上表达业务语义。
3.3 并发与治理：让Agent扛住真实流量
"AI agent怎么扛并发"是个热门话题，本质上这是个架构问题，不是模型问题。单Agent内部的并发瓶颈，通常是LLM接口限流、工具执行阻塞、状态冲突。框架层面要提供分级处理。
我的经验是按三层治理并发：
- 请求层：所有LLM调用统一走异步队列，控制消费者的并发上限，实现令牌桶限流。我在实际项目里会把并发上限配成模型供应商允许速率的一半，留出余量应对突发。
- 任务层：每个业务任务对应一个独立的Agent实例或会话，不共享上下文状态，从根上避免状态污染。
- 资源层：工具调用要单独做信号量控制，尤其是外部API和数据库操作，避免Agent把后端系统打挂。外部服务没有降级预案的话，宁可任务排队也不要在高峰期硬闯。
同时要处理超时与熔断。框架里我习惯给每个循环周期设置硬超时，比如单轮规划+工具执行的预算时间是30秒，超过就中断本轮；连续失败超过阈值就触发熔断，把坏Agent停掉并上报。
4. 安全边界与生产落地
4.1 权限最小化与工具防护
Agent再强，也必须被装在安全的"笼子"里。这里的安全不仅是防止外部攻击，更是防止Agent自身因为幻觉或误判而执行危险操作。
在框架层面可以做这些安全措施：
- 工具级鉴权：不同敏感度的工具需要不同级别的授权。比如只读查询自动放行，写操作必须人工确认，高权限操作实施双人审核。
- 参数校验：模型传给工具的参数不可信，必须按JSON Schema做强校验与类型检查，杜绝注入和越界参数。
- 沙盒执行：对于可脚本化或可执行代码的工具，尽量跑在隔离的沙箱里，限制网络访问与文件系统权限。Docker容器是一种常见方案，配置时需要关掉不必要的capabilities。
- 敏感信息脱敏：工具返回结果和模型提示词都不应泄露密钥、个人隐私、内部数据。日志系统里也要做脱敏处理，防止trace里明文出现密钥。
这部分的思路和"agent安全"热搜词高度相关。安全边界不能等出了问题再补，必须在架构设计阶段就把它作为一等公民考虑进去。上线前给Agent做一轮红队测试，专门用诱导性提示词试探权限边界，往往能发现意想不到的漏洞。
4.2 会话与状态隔离：多租户数据不能串
如果你做的Agent平台不止服务一个用户或一个租户，那数据隔离就是红线。一个用户A的长期记忆和私有资料，绝不能出现在用户B的Agent上下文中。
实现要点是：
- 会话绑定：所有Agent实例在初始化时绑定租户ID，上下文管理器在读取任何历史或记忆时都要带上租户过滤。
- 存储层隔离：长期记忆库的向量集合按租户建立命名空间，检索时强制限定命名空间。
- 审计日志：记录谁在什么时间让Agent执行了什么操作，尤其是工具调用，这对追责和合规来说必不可少。
我在一个企业知识库项目里就因为没做存储层隔离，出现过一次不同部门的数据串查询，虽然只发生在测试环境，但也足够让人后怕。从那之后，"所有检索操作必须携带租户上下文"就成了我框架里的一条硬约束。
5. 从架构图到第一步代码：落地时的优先级建议
5.1 演进式设计比一步到位更现实
最后想说的是，不要指望第一章就把图里所有组件一次写完。架构图是终点，不是起点。我在实操中推荐这样演进：
- 第一版：只写Agent + 上下文管理器 + 工具注册表的最小闭环，能让模型调用2-3个工具跑通一个场景。这一版的目标是验证"循环转得起来"。
- 第二版：加入状态机和可观测性，把对话日志、工具日志、状态迁移记录全部接出来。这一版的目标是"问题看得见"。
- 第三版：补上记忆模块，先做上下文压缩，再做向量检索。这一版的目标是"跑得长"。
- 第四版：做并发和限流，再上多Agent编排。这一版的目标是"扛得住"。
每一版都保持可运行、可验证，而不是等框架"完美"了再开始用。很多团队死在"架构设计完美主义"上，画了三个月图，一行代码没跑，最后业务根本不买单。
5.2 框架好用的检验标准：改动的边际成本
框架设计里还有一个判断标准：你的框架能不能快速适应变化。LLM底座的迭代、工具系统的调整、新业务场景的接入，如果每一次变化都要动框架主干，说明你的抽象层级搞错了。健康的Agent框架，变化应该发生在边缘模块——换模型只改接入层，加工具只注册表加一条，多Agent只增编排配置。我把这当作架构设计最终的检验标准：大部分改动都应该是"增量"，而不是"重写"。
以我自己的经验，判断某个模块要不要抽象成框架，就看它在6个月内会不会变更三次。会，就值得抽象；不会，就先写死。等需求降临时再重构，成本通常比想象中低，因为你真正理解了它的输入输出，而不是靠猜。
最后说点个人体会吧。Agent框架整体架构设计这一节，内容是个总纲，后续章节再展开讲每一层里的设计和代码实现。Agent框架最难的往往不是某一个技术点，而是整套体系的权衡：什么时候该做记忆、什么时候该上多Agent、怎么在灵活和可控之间取平衡。我个人的建议还是那句话：从一个极简可运行的循环开始，让架构图慢慢长出来，比一次写完更靠谱。手里有多个Agent项目跑过几轮之后，你会自然知道哪个模块值得投入，哪个模块可以继续轻量。
