主流 Agent 架构分析指南当 ChatGPT 还停留在对话阶段时一批能干活的 AI已经悄然崛起——它们能读写文件、执行命令、操作浏览器甚至自我进化。本文将深入剖析五大主流 Agent 框架的架构设计带你从源码层面理解 AI Agent 是如何工作的。一、什么是 AI Agent在深入架构之前我们先建立一个统一的认知模型。一个 AI Agent智能体的本质是一个“LLM 推理 工具调用 环境观察 状态更新 反馈闭环”的循环系统。它的核心能力不是聊天而是自主地完成目标。用通俗的话说LLM大模型是 Agent 的大脑——负责理解任务、做出决策工具系统是 Agent 的手脚——负责读写文件、执行命令、搜索代码环境观察是 Agent 的眼睛——负责观察执行结果判断下一步上下文管理是 Agent 的记忆——负责记住任务历史和中间状态安全治理是 Agent 的边界——负责权限控制、沙箱隔离、错误恢复五大框架的共同基础可以用一个公式概括Agent LLM推理 工具调用 环境观察 状态更新 反馈闭环理解了这一点我们就能从统一视角来看待各框架的架构差异。二、六大分层架构模型我们用一个统一的六层架构模型来解构所有 Agent 框架。这个模型把 Agent 从外到内分为六层层级名称核心职责①入口与输入用户如何与 Agent 交互CLI、IDE、Web、API 等②上下文与模型如何管理对话上下文、选择模型、构建提示词③核心循环Agent LoopAgent 的推理-执行-观察循环④工具与执行Agent 能调用哪些工具、如何执行⑤记忆与扩展技能、钩子、子Agent、会话持久化、分层记忆等⑥治理与输出权限策略、安全边界、错误恢复、结果输出下面是五大框架在这六层上的完整对比图核心思想五大框架共享相同的基础范式LLM推理 工具调用 环境观察 状态更新 反馈闭环但在每一层的实现方式、设计哲学和取舍上存在显著差异。三、逐框架深度解析3.1 Claude Code —— 可扩展性与人类控制设计哲学Claude 负责理解与决策Agent 框架负责上下文管理、工具编排、权限边界、扩展机制与可靠恢复。架构亮点① 入口层多入口统一调度Claude Code 支持三种入口方式CLI终端最核心的使用方式直接在终端中与 Agent 对话IDE 集成嵌入 VS Code、JetBrains 等编辑器所见即所得Agent SDK编程接口可以构建自定义的 Agent 应用用户的自然语言指令和项目代码库作为输入进入 Agent 系统。上下文层CLAUDE.md 驱动Claude Code 的上下文管理非常有特色——它用CLAUDE.md文件定义项目规则让 Agent 自动了解项目的编码规范、技术栈偏好等。此外还管理会话历史、代码文件上下文、环境信息并通过上下文压缩机制控制 Token 消耗。③ 核心循环七步推理链Claude Code 的 Agent Loop 包含七个步骤理解任务 → 制定/调整计划 → 选择工具 → 生成工具调用 → 接收执行观察 → 更新上下文 → 判断完成条件这个循环的核心是 Claude 模型本身。在循环过程中如果需要用户确认会弹出权限审批请求如果任务完成则生成最终回复。④ 工具层丰富的内置工具 MCP 扩展内置工具包括文件系统读取、编辑、新建文件终端Shell 命令执行、构建、测试代码搜索搜索、定位、分析代码MCP连接外部服务和数据源所有工具的结果都会经过标准化处理然后反馈给核心循环。⑤ 扩展层Skills / Hooks / Commands / Subagents这是 Claude Code 最强大的特性之一扩展类型功能Skills按需加载专业工作流类似即插即用的技能包Hooks生命周期事件自动化在特定阶段触发预设操作Commands可复用的命令入口用户自定义常用操作Subagents任务委派与结果汇总子Agent可以独立工作MCP Servers连接外部工具和数据源会话持久化跨会话保存工作上下文⑥ 治理层权限网关安全是 Claude Code 的核心设计理念权限模式从完全自动到每次都需要审批的多级控制工具调用审批危险操作必须经过用户确认命令风险检查自动识别危险命令文件访问边界限制 Agent 能访问的文件范围信任目录项目级别的信任配置中断与错误恢复异常情况下能安全回退设计取舍优势局限极其丰富的扩展系统依赖 Anthropic 的 Claude 模型强大的权限控制和安全边界代码库庞大108 内部模块未开源IDE 集成体验优秀会话间状态持久化有限Skills/Hooks 机制灵活闭源内部功能多3.2 OpenAI Codex —— 安全执行与可验证变更设计哲学Codex Agent Loop 编排模型、上下文与工具受控沙箱和验证机制将自然语言目标转化为可审查的软件变更。架构亮点① 入口层CLI Cloud IDE 三端覆盖Codex CLI终端命令行入口IDE/编辑器集成支持 VS Code、Cursor、Windsurf 等Codex Cloud云端 Agent通过 chatgpt.com/codex 使用② 上下文层AGENTS.md 项目指令与 Claude Code 的CLAUDE.md类似Codex 使用AGENTS.md文件定义项目指令。管理会话状态、消息历史、代码库上下文、权限模式配置并通过提示与上下文构建机制控制 Token 使用。** 核心循环Responses API 驱动**Codex 的 Agent Loop 使用 OpenAI 的 Responses API构建提示与上下文 → 模型推理 → 生成工具调用请求 → 权限判定/请求审批 → 执行工具 → 接收观察结果 → 更新计划与上下文 → 验证完成条件一个特色是并行探索能力——Codex 可以委派多个 Subagent 同时探索不同的解决方案路径然后汇总结果。④ 工具层受控执行环境Codex 的工具设计强调安全性Shell命令、脚本、构建执行文件补丁读取、修改、新建文件代码搜索定位和分析代码测试与验证运行单元测试、静态检查MCP/外部工具扩展工具能力所有执行结果stdout/stderr/diffs/测试结果都经过标准化处理。⑤ 扩展层计划与可观测性Codex 的扩展设计更偏向工程化扩展类型功能计划与任务进度可视化的任务执行计划Subagents并行委派与汇总多路径探索可复用 Skills/工作流标准化操作流程MCP Servers外部工具集成会话轨迹与事件完整的执行时间线可观测性执行过程的全面监控⑥ 治理层文件系统沙箱Codex 的安全设计是其最大特色权限模式多级控制自动/审批/只读用户审批关键操作的人工确认文件系统沙箱隔离的文件操作环境网络访问控制限制网络请求命令风险边界危险命令检测中断/失败恢复异常处理机制设计取舍优势局限强大的沙箱和安全控制依赖 OpenAI 模型和 API可验证的软件变更diff/测试Subagent 并行消耗较多 Token响应式 API 支持流式输出本地执行能力相对有限IDE 集成成熟自定义扩展不如 Claude Code 灵活3.3 Pi Agent —— 轻量模块化与多模型运行时设计哲学将模型访问、Agent Loop、编码会话、交互界面与工具拆分为可组合包以小型核心支持多提供商和多种运行方式。架构亮点① 入口层CLI TUI Web 嵌入式Pi Agent 的入口方式最为多样命令行 CLI终端直接交互终端 TUI全功能的终端用户界面Web 界面浏览器访问嵌入式应用可以嵌入到其他应用中② 上下文层coding-agent 会话管理Pi 使用coding-agent包管理会话包括系统提示/用户提示管理消息历史Agent 状态模型与参数配置会话持久化/恢复③ 核心循环流式驱动Pi 的 Agent Loop 设计为流式响应接收用户消息 → 组装上下文 → 调用模型流 → 解析文本/工具调用 → 执行工具 → 追加工具结果 → 更新Agent状态 → 判断继续/完成与 Claude Code 和 Codex 不同Pi 的核心循环是事件驱动的——工具执行是独立进行的结果通过状态事件传递。④ 工具层四层架构Pi 的工具系统设计为清晰的分层模型抽象层 ├── 统一 LLM API ├── 多提供商适配OpenAI, Anthropic, Google, ... ├── 模型切换 └── 流式响应 编码工具层基础工具 ├── read读取文件 ├── write写入文件 ├── edit精确编辑 ── bash执行命令 工具结果标准化这种设计使得 Pi 可以无缝切换不同的 LLM 提供商而不需要修改核心代码。⑤ 扩展层事件流 状态存储Pi 的扩展机制基于事件系统扩展类型功能事件流向外广播消息增量、工具开始/结束、状态更新、错误与中止状态存储消息历史、Agent 状态、会话存储扩展与自定义自定义工具、扩展/插件、主题与快捷键⑥ 治理层运行治理Pi 的治理相对轻量生命周期控制启动、暂停、停止取消/中止信号Graceful shutdown错误传播错误在事件流中传递工具执行边界限制工具权限状态一致性确保状态机正确性会话恢复中断后继续工作设计取舍优势局限多模型支持OpenAI/Anthropic/Google没有内置权限系统模块化设计包可以独立使用安全控制需要外部容器化代码库精简易于理解和定制功能丰富度不如 Claude Code/Codex流式响应交互体验好扩展生态尚在早期3.4 GenericAgent —— 信息密度与自我进化设计哲学少量原子工具通过组合获得广泛能力记忆按需加载上下文持续压缩成功经验被结晶为可复用 SOP 与技能。一句话概括~3K 行种子代码 9 个原子工具 ~100 行 Agent Loop 可以自主完成任何电脑任务的智能体。架构亮点① 入口层CLI GUI 环境感知GenericAgent 的入口非常灵活CLI/图形界面用户任务输入环境观察自动感知当前系统状态历史经验从记忆中获取本地计算机环境浏览器/文件/终端② 上下文层信息密度最大化这是 GenericAgent 最独特的设计之一——它不是在有限上下文中塞入尽可能多的信息而是在有限上下文中保留更多决策相关信息系统提示与当前任务L1 记忆索引常驻按需检索的事实/SOP工具结果与检查点上下文预算检测③ 核心循环~100 行代码的统一 Agent Loop感知任务与环境 → 检索必要记忆 → 推理与选择工具 → 执行原子工具 → 接收环境反馈 → 验证执行结果 → 更新工作检查点 → 继续/完成如果任务复杂可以组合工具或子智能体如果验证成功进入反思与经验结晶。④ 工具层9 个原子工具这是 GenericAgent 的核心创新——只定义 9 个原子工具通过组合获得广泛能力工具功能code_run执行任意代码Python/PowerShellfile_read读取文件file_write写入/创建/覆盖文件file_patch补丁/修改文件web_scan感知网页内容web_execute_js控制浏览器行为ask_user人机协同确认update_working_checkpoint记忆短期工作便签start_long_term_update记忆提炼长期记忆通过code_runGenericAgent 可以动态安装依赖包、编写新脚本、调用外部 API将临时能力固化为永久工具。⑤ 记忆层四层记忆系统这是 GenericAgent 与其他框架最大的区别层级名称描述L0元规则核心行为规则和系统约束L1洞察索引最小记忆索引用于快速路由和回忆L2全局事实长期运行中积累的稳定知识L3任务技能/SOP可复用的工作流L4会话归档从已完成会话中提炼的任务记录自我进化循环[新任务] → [自主探索] → [结晶为技能] → [下次相似任务直接调用]每次完成新任务GenericAgent 都会自动将执行路径结晶为可复用的 Skill。用得越久技能树越丰富。⑥ 治理层上下文治理工具结果截断控制输出长度标签级压缩智能压缩上下文FIFO 淘汰按先进先出淘汰旧信息有限 Token 预算严格控制上下文大小30K检查点保护关键信息不丢失验证后再写入长期记忆设计取舍优势局限极简代码~3K 行易于理解和修改生态和文档不如商业框架成熟自我进化能力独一无二主要面向 Python 环境四层记忆系统越用越聪明安全控制相对基础Token 消耗极低30K不适合需要复杂权限控制的场景9 个原子工具组合灵活模型支持不如 Pi Agent 丰富3.5 Hermes Agent —— 跨端运行与闭环学习设计哲学多个入口共享同一 AIAgent窄核心通过工具注册表连接多种执行后端会话、记忆与 Skills 构成可持续改进的闭环。架构亮点① 入口层跨端统一Hermes Agent 的入口方式最为广泛CLI / TUI终端交互Desktop桌面应用消息网关Telegram、Discord、Slack、WhatsApp、SignalACP / API Server程序化调用Batch Runner批量自动化任务Python Library代码集成本地/远程执行环境灵活部署② 提示与模型层多提供商解析Hermes 的模型管理非常强大Prompt Builder系统提示/人格/Skills 构建MEMORY.md / USER.md长期记忆和用户模型Provider Resolution支持多种 API 模式Chat CompletionsOpenAI 兼容Codex ResponsesOpenAI CodexAnthropic Messages提示缓存 上下文压缩统一内部消息格式③ 核心循环AIAgent Loop接收任务/恢复会话 → 构建或复用系统提示 → 压缩前检查 → 选择提供商/API模式 → 可中断模型调用 → 解析文本与工具调用 → 顺序/并发执行工具 → 追加结果并判断继续特色机制可中断模型调用支持中途取消F allback 提供商主模型失败时自动切换迭代预算控制推理轮次④ 工具层注册表 多后端Hermes 的工具系统是其架构亮点Tool Registry工具注册表 ├── Toolsets / 平台预设 ├── 工具发现 · Schema 收集 · 调度 ├── Terminal / Process本地终端 ├── Browser / Computer Use浏览器控制 ├── Web / 文件 / Vision网页/文件/视觉 ├── MCP 动态工具 ├── Memory / Session Search记忆/搜索 └── Skill Manage / Delegate Task / Cronjob 执行后端运行环境 ├── 本地 ├── Docker ├── SSH ├── Singularity ├── ModalServerless └── DaytonaServerless这意味着 Hermes 可以在本地、Docker、远程 SSH、Serverless 平台等多种环境中运行且切换透明。⑤ 记忆层持久化状态 闭环学习组件功能SQLite 会话存储完整的会话持久化FTS5 历史搜索全文检索历史会话会话摘要/恢复跨会话记忆MEMORY.md长期事实存储USER.md用户模型学习与改进闭环复杂任务执行 → 经验与轨迹 → 技能创建 → 后续任务复用 → 使用中改进与 GenericAgent 类似Hermes 也有自我进化能力但更强调跨会话的持续学习——它会在你使用过程中不断改善自己的技能。** 治理层运行治理与可靠性**Iteration Budget迭代预算控制取消/中断Graceful 终止工具状态回调实时跟踪错误重试自动恢复Fallback Providers多模型容错压缩前记忆刷新防止信息丢失缓存一致性数据一致性保证会话谱系与恢复完整的会话恢复链设计取舍优势局限跨平台部署$5 VPS 到 GPU 集群配置复杂度较高多消息平台集成学习曲线较陡6 种执行后端灵活部署社区规模不如商业框架内置 cron 调度器中文文档相对较少闭环学习 技能自改进对 Nous Research 生态有一定依赖四、五大框架横向对比4.1 核心设计哲学对比框架一句话定位设计重点Claude Code可扩展性与人类控制扩展框架 权限控制OpenAI Codex安全执行与可验证变更受控沙箱 验证闭环Pi Agent轻量模块化与多模型运行时可组合包 事件驱动GenericAgent信息密度与自我进化分层记忆 经验结晶Hermes Agent跨端运行与闭环学习跨端入口 持久学习4.2 Agent Loop 设计对比框架循环步骤数特色机制循环复杂度Claude Code7 步权限审批 计划调整高含人机协同Codex8 步并行探索 验证闭环高含 Subagent 委派Pi Agent8 步流式响应 事件驱动中轻量循环GenericAgent8 步记忆检索 自我进化低~100 行代码Hermes Agent8 步可中断 Fallback 预算控制中多提供商支持4.3 工具系统设计对比框架工具数量扩展方式特色Claude Code40Skills / Hooks / MCP最丰富的内置工具集Codex20Skills / Subagents / MCP受控执行 测试验证Pi Agent4 基础 自定义插件 / 自定义工具极简 事件驱动GenericAgent9 原子工具代码运行动态创建组合获得广泛能力Hermes Agent动态注册工具注册表 多后端跨环境执行能力最强4.4 记忆系统设计对比框架记忆类型跨会话自我进化Claude Code会话持久化✅ 有限Codex会话轨迹✅ 有限❌Pi Agent会话存储✅❌GenericAgent四层记忆L0-L4✅ 完整✅ 技能结晶Hermes AgentSQLite FTS5 MEMORY.md✅ 完整✅ 闭环学习4.5 模型支持对比框架模型支持切换方式Claude CodeClaude 系列固定AnthropicCodexGPT / o-series固定OpenAIPi AgentOpenAI / Anthropic / Google / …统一 API 切换GenericAgentClaude / Gemini / Kimi / MiniMax / …配置文件切换Hermes AgentNous / OpenRouter / OpenAI / Anthropic / …hermes model命令4.6 安全治理对比框架权限控制沙箱网络控制错误恢复Claude Code多级权限 信任边界项目级✅✅Codex权限模式 用户审批文件系统沙箱✅✅Pi Agent无内置需外部容器化需外部❌✅GenericAgentask_user 检查点❌❌✅Hermes Agent迭代预算 状态回调多后端隔离✅✅五、如何选择按使用场景推荐场景推荐框架理由日常编码辅助Claude CodeIDE 集成好权限控制强Skills 扩展丰富企业级代码审查Codex沙箱安全变更可验证测试集成多模型实验Pi Agent切换模型零成本模块化设计灵活自动化复杂任务GenericAgent自我进化记忆积累Token 消耗低7×24 无人值守Hermes Agent跨平台部署cron 调度持久记忆想自己改源码GenericAgent~3K 行代码100 行 Agent Loop最易理解需要浏览器自动化GenericAgent真实浏览器会话保持支持 ADBTelegram/Discord 机器人Hermes Agent原生多平台消息网关追求极致安全Codex文件系统沙箱 网络控制 验证闭环快速原型开发Pi Agent模块化组合npm 安装即用按技术背景推荐技术背景推荐框架理由前端/全栈开发者Claude CodeTypeScript 源码VS Code 集成Rust 开发者CodexRust 实现性能优异Python 开发者GenericAgentPython 实现代码极简DevOps/运维Hermes Agent多后端部署Serverless 支持AI 研究者GenericAgent自我进化机制有研究价值想学 Agent 原理GenericAgent100 行 Agent Loop最容易理解六、架构演进趋势从这五大框架的架构对比中我们可以观察到几个明显的趋势趋势 1从固定模型 → 多模型运行时Claude Code 和 Codex 绑定单一模型提供商而 Pi Agent、GenericAgent、Hermes Agent 都支持多模型切换。未来的 Agent 框架必然走向模型无关化。趋势 2从会话态 → 持久记忆Claude Code 和 Codex 的会话间状态有限而 GenericAgent 和 Hermes Agent 都有完整的跨会话记忆系统。持久记忆是 Agent 从工具进化为助手的关键。趋势 3从预设技能 → 自我进化GenericAgent 和 Hermes Agent 都有自我进化能力——从成功执行中学习并结晶为可复用技能。这是 Agent 框架的下一代能力。趋势 4从本地执行 → 跨端部署Hermes Agent 支持 6 种执行后端本地、Docker、SSH、Serverless 等代表了 Agent 部署的未来方向——不绑定特定环境。趋势 5从单一入口 → 多通道接入从 CLI 到 IDE 到消息平台到 APIAgent 的入口正在多元化。Hermes Agent 在这方面走得最远支持 Telegram/Discord/Slack/WhatsApp/Signal。七、总结五大 Agent 框架虽然共享相同的基础范式LLM推理 工具调用 环境观察 状态更新 反馈闭环但在设计哲学、架构选择和工程取舍上各有特色Claude CodeCodexPi AgentGenericAgentHermes Agent语言TypeScriptRustTypeScriptPythonPython核心代码量大大中~3K 行中Agent Loop复杂复杂中等~100 行中等最大特色扩展系统安全沙箱多模型支持自我进化跨端部署适合谁专业开发者企业团队实验者自动化爱好者运维/全栈选择框架的本质是选择设计哲学的取舍——没有最好的框架只有最适合你场景的框架。参考资源Claude Code 源码分析OpenAI Codex 文档Pi Agent 文档GenericAgent 官方仓库GenericAgent 教程DatawhaleHermes Agent 文档一文读懂 OpenAI Codex 源码
