主流 Agent 架构分析指南

主流 Agent 架构分析指南

当 ChatGPT 还停留在对话阶段时，一批”能干活的 AI”已经悄然崛起——它们能读写文件、执行命令、操作浏览器，甚至自我进化。本文将深入剖析五大主流 Agent 框架的架构设计，带你从源码层面理解 AI Agent 是如何工作的。

一、什么是 AI Agent？

在深入架构之前，我们先建立一个统一的认知模型。

一个 AI Agent（智能体）的本质是一个 “LLM 推理 + 工具调用 + 环境观察 + 状态更新 + 反馈闭环” 的循环系统。它的核心能力不是”聊天”，而是自主地完成目标。

用通俗的话说：

  • LLM（大模型） 是 Agent 的”大脑”——负责理解任务、做出决策
  • 工具系统 是 Agent 的”手脚”——负责读写文件、执行命令、搜索代码
  • 环境观察 是 Agent 的”眼睛”——负责观察执行结果，判断下一步
  • 上下文管理 是 Agent 的”记忆”——负责记住任务历史和中间状态
  • 安全治理 是 Agent 的”边界”——负责权限控制、沙箱隔离、错误恢复

五大框架的共同基础可以用一个公式概括：

1
Agent = LLM推理 + 工具调用 + 环境观察 + 状态更新 + 反馈闭环

理解了这一点，我们就能从统一视角来看待各框架的架构差异。

二、六大分层架构模型

我们用一个统一的六层架构模型来解构所有 Agent 框架。这个模型把 Agent 从外到内分为六层：

层级 名称 核心职责
① 入口与输入 用户如何与 Agent 交互（CLI、IDE、Web、API 等）
② 上下文与模型 如何管理对话上下文、选择模型、构建提示词
③ 核心循环（Agent Loop） Agent 的推理-执行-观察循环
④ 工具与执行 Agent 能调用哪些工具、如何执行
⑤ 记忆与扩展 技能、钩子、子Agent、会话持久化、分层记忆等
⑥ 治理与输出 权限策略、安全边界、错误恢复、结果输出

下面是五大框架在这六层上的完整对比图：

agent_all.png

核心思想：五大框架共享相同的基础范式（LLM推理 + 工具调用 + 环境观察 + 状态更新 + 反馈闭环），但在每一层的实现方式、设计哲学和取舍上存在显著差异。

三、逐框架深度解析

3.1 Claude Code —— 可扩展性与人类控制

claude code.png

设计哲学：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 包含七个步骤：

1
理解任务 → 制定/调整计划 → 选择工具 → 生成工具调用 → 接收执行观察 → 更新上下文 → 判断完成条件

这个循环的核心是 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.png

设计哲学：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：

1
构建提示与上下文 → 模型推理 → 生成工具调用请求 → 权限判定/请求审批 → 执行工具 → 接收观察结果 → 更新计划与上下文 → 验证完成条件

一个特色是并行探索能力——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 —— 轻量模块化与多模型运行时

pi agent.png

设计哲学：将模型访问、Agent Loop、编码会话、交互界面与工具拆分为可组合包，以小型核心支持多提供商和多种运行方式。

架构亮点

① 入口层：CLI + TUI + Web + 嵌入式

Pi Agent 的入口方式最为多样：

  • 命令行 CLI：终端直接交互
  • 终端 TUI：全功能的终端用户界面
  • Web 界面：浏览器访问
  • 嵌入式应用：可以嵌入到其他应用中

② 上下文层：coding-agent 会话管理

Pi 使用 coding-agent 包管理会话，包括：

  • 系统提示/用户提示管理
  • 消息历史
  • Agent 状态
  • 模型与参数配置
  • 会话持久化/恢复

③ 核心循环：流式驱动

Pi 的 Agent Loop 设计为流式响应：

1
接收用户消息 → 组装上下文 → 调用模型流 → 解析文本/工具调用 → 执行工具 → 追加工具结果 → 更新Agent状态 → 判断继续/完成

与 Claude Code 和 Codex 不同，Pi 的核心循环是事件驱动的——工具执行是独立进行的，结果通过状态事件传递。

④ 工具层：四层架构

Pi 的工具系统设计为清晰的分层：

1
2
3
4
5
6
7
8
9
10
11
12
13
模型抽象层
├── 统一 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 —— 信息密度与自我进化

generic agent.png

设计哲学：少量原子工具通过组合获得广泛能力；记忆按需加载；上下文持续压缩；成功经验被结晶为可复用 SOP 与技能。

一句话概括：~3K 行种子代码 + 9 个原子工具 + ~100 行 Agent Loop = 可以自主完成任何电脑任务的智能体。

架构亮点

① 入口层：CLI + GUI + 环境感知

GenericAgent 的入口非常灵活：

  • CLI/图形界面
  • 用户任务输入
  • 环境观察（自动感知当前系统状态）
  • 历史经验（从记忆中获取）
  • 本地计算机环境（浏览器/文件/终端）

② 上下文层：信息密度最大化

这是 GenericAgent 最独特的设计之一——它不是在有限上下文中塞入尽可能多的信息，而是在有限上下文中保留更多决策相关信息：

  • 系统提示与当前任务
  • L1 记忆索引（常驻）
  • 按需检索的事实/SOP
  • 工具结果与检查点
  • 上下文预算检测

③ 核心循环：~100 行代码的统一 Agent Loop

1
感知任务与环境 → 检索必要记忆 → 推理与选择工具 → 执行原子工具 → 接收环境反馈 → 验证执行结果 → 更新工作检查点 → 继续/完成

如果任务复杂，可以组合工具或子智能体；如果验证成功，进入反思与经验结晶。

④ 工具层：9 个原子工具

这是 GenericAgent 的核心创新——只定义 9 个原子工具，通过组合获得广泛能力：

工具 功能
code_run 执行任意代码（Python/PowerShell）
file_read 读取文件
file_write 写入/创建/覆盖文件
file_patch 补丁/修改文件
web_scan 感知网页内容
web_execute_js 控制浏览器行为
ask_user 人机协同确认
update_working_checkpoint （记忆）短期工作便签
start_long_term_update （记忆）提炼长期记忆

通过 code_run，GenericAgent 可以动态安装依赖包、编写新脚本、调用外部 API，将临时能力固化为永久工具。

⑤ 记忆层：四层记忆系统

这是 GenericAgent 与其他框架最大的区别：

层级 名称 描述
L0 元规则 核心行为规则和系统约束
L1 洞察索引 最小记忆索引，用于快速路由和回忆
L2 全局事实 长期运行中积累的稳定知识
L3 任务技能/SOP 可复用的工作流
L4 会话归档 从已完成会话中提炼的任务记录

自我进化循环：

1
[新任务] → [自主探索] → [结晶为技能] → [下次相似任务直接调用]

每次完成新任务，GenericAgent 都会自动将执行路径结晶为可复用的 Skill。用得越久，技能树越丰富。

⑥ 治理层：上下文治理

  • 工具结果截断：控制输出长度
  • 标签级压缩：智能压缩上下文
  • FIFO 淘汰：按先进先出淘汰旧信息
  • 有限 Token 预算：严格控制上下文大小（<30K）
  • 检查点保护：关键信息不丢失
  • 验证后再写入长期记忆

设计取舍

优势 局限
极简代码（~3K 行），易于理解和修改 生态和文档不如商业框架成熟
自我进化能力独一无二 主要面向 Python 环境
四层记忆系统，越用越聪明 安全控制相对基础
Token 消耗极低（<30K） 不适合需要复杂权限控制的场景
9 个原子工具，组合灵活 模型支持不如 Pi Agent 丰富

3.5 Hermes Agent —— 跨端运行与闭环学习

hermes agent.png

设计哲学：多个入口共享同一 AIAgent；窄核心通过工具注册表连接多种执行后端；会话、记忆与 Skills 构成可持续改进的闭环。

架构亮点

① 入口层：跨端统一

Hermes Agent 的入口方式最为广泛：

  • CLI / TUI：终端交互
  • Desktop：桌面应用
  • 消息网关：Telegram、Discord、Slack、WhatsApp、Signal
  • ACP / API Server：程序化调用
  • Batch Runner：批量自动化任务
  • Python Library：代码集成
  • 本地/远程执行环境：灵活部署

② 提示与模型层：多提供商解析

Hermes 的模型管理非常强大：

  • Prompt Builder：系统提示/人格/Skills 构建
  • MEMORY.md / USER.md：长期记忆和用户模型
  • Provider Resolution：支持多种 API 模式
    • Chat Completions（OpenAI 兼容）
    • Codex Responses（OpenAI Codex）
    • Anthropic Messages
  • 提示缓存 + 上下文压缩
  • 统一内部消息格式

③ 核心循环：AIAgent Loop

1
接收任务/恢复会话 → 构建或复用系统提示 → 压缩前检查 → 选择提供商/API模式 → 可中断模型调用 → 解析文本与工具调用 → 顺序/并发执行工具 → 追加结果并判断继续

特色机制：

  • 可中断模型调用：支持中途取消
  • F allback 提供商：主模型失败时自动切换
  • 迭代预算：控制推理轮次

④ 工具层：注册表 + 多后端

Hermes 的工具系统是其架构亮点：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Tool Registry（工具注册表）
├── Toolsets / 平台预设
├── 工具发现 · Schema 收集 · 调度
├── Terminal / Process（本地终端）
├── Browser / Computer Use（浏览器控制）
├── Web / 文件 / Vision（网页/文件/视觉）
├── MCP 动态工具
├── Memory / Session Search（记忆/搜索）
└── Skill Manage / Delegate Task / Cronjob

执行后端（运行环境）
├── 本地
├── Docker
├── SSH
├── Singularity
├── Modal（Serverless）
└── Daytona（Serverless）

这意味着 Hermes 可以在本地、Docker、远程 SSH、Serverless 平台等多种环境中运行，且切换透明。

⑤ 记忆层：持久化状态 + 闭环学习

组件 功能
SQLite 会话存储 完整的会话持久化
FTS5 历史搜索 全文检索历史会话
会话摘要/恢复 跨会话记忆
MEMORY.md 长期事实存储
USER.md 用户模型

学习与改进闭环：

1
复杂任务执行 → 经验与轨迹 → 技能创建 → 后续任务复用 → 使用中改进

与 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 Code 7 步 权限审批 + 计划调整 高（含人机协同）
Codex 8 步 并行探索 + 验证闭环 高（含 Subagent 委派）
Pi Agent 8 步 流式响应 + 事件驱动 中（轻量循环）
GenericAgent 8 步 记忆检索 + 自我进化 低（~100 行代码）
Hermes Agent 8 步 可中断 + Fallback + 预算控制 中（多提供商支持）

4.3 工具系统设计对比

框架 工具数量 扩展方式 特色
Claude Code 40+ Skills / Hooks / MCP 最丰富的内置工具集
Codex 20+ Skills / Subagents / MCP 受控执行 + 测试验证
Pi Agent 4 基础 + 自定义 插件 / 自定义工具 极简 + 事件驱动
GenericAgent 9 原子工具 代码运行动态创建 组合获得广泛能力
Hermes Agent 动态注册 工具注册表 + 多后端 跨环境执行能力最强

4.4 记忆系统设计对比

框架 记忆类型 跨会话 自我进化
Claude Code 会话持久化 ✅ 有限
Codex 会话轨迹 ✅ 有限 ❌
Pi Agent 会话存储 ✅ ❌
GenericAgent 四层记忆（L0-L4） ✅ 完整 ✅ 技能结晶
Hermes Agent SQLite + FTS5 + MEMORY.md ✅ 完整 ✅ 闭环学习

4.5 模型支持对比

框架 模型支持 切换方式
Claude Code Claude 系列 固定（Anthropic）
Codex GPT / o-series 固定（OpenAI）
Pi Agent OpenAI / Anthropic / Google / … 统一 API 切换
GenericAgent Claude / Gemini / Kimi / MiniMax / … 配置文件切换
Hermes Agent Nous / OpenRouter / OpenAI / Anthropic / … hermes model 命令

4.6 安全治理对比

框架 权限控制 沙箱 网络控制 错误恢复
Claude Code 多级权限 + 信任边界 项目级 ✅ ✅
Codex 权限模式 + 用户审批 文件系统沙箱 ✅ ✅
Pi Agent 无内置（需外部容器化） 需外部 ❌ ✅
GenericAgent ask_user + 检查点 ❌ ❌ ✅
Hermes Agent 迭代预算 + 状态回调 多后端隔离 ✅ ✅

五、如何选择？

按使用场景推荐

场景 推荐框架 理由
日常编码辅助 Claude Code IDE 集成好，权限控制强，Skills 扩展丰富
企业级代码审查 Codex 沙箱安全，变更可验证，测试集成
多模型实验 Pi Agent 切换模型零成本，模块化设计灵活
自动化复杂任务 GenericAgent 自我进化，记忆积累，Token 消耗低
7×24 无人值守 Hermes Agent 跨平台部署，cron 调度，持久记忆
想自己改源码 GenericAgent ~3K 行代码，100 行 Agent Loop，最易理解
需要浏览器自动化 GenericAgent 真实浏览器会话保持，支持 ADB
Telegram/Discord 机器人 Hermes Agent 原生多平台消息网关
追求极致安全 Codex 文件系统沙箱 + 网络控制 + 验证闭环
快速原型开发 Pi Agent 模块化组合，npm 安装即用

按技术背景推荐

技术背景 推荐框架 理由
前端/全栈开发者 Claude Code TypeScript 源码，VS Code 集成
Rust 开发者 Codex Rust 实现，性能优异
Python 开发者 GenericAgent Python 实现，代码极简
DevOps/运维 Hermes Agent 多后端部署，Serverless 支持
AI 研究者 GenericAgent 自我进化机制有研究价值
想学 Agent 原理 GenericAgent 100 行 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 到消息平台到 API，Agent 的入口正在多元化。Hermes Agent 在这方面走得最远，支持 Telegram/Discord/Slack/WhatsApp/Signal。

七、总结

五大 Agent 框架虽然共享相同的基础范式（LLM推理 + 工具调用 + 环境观察 + 状态更新 + 反馈闭环），但在设计哲学、架构选择和工程取舍上各有特色：

Claude Code Codex Pi Agent GenericAgent Hermes Agent
语言 TypeScript Rust TypeScript Python Python
核心代码量 大 大 中 ~3K 行 中
Agent Loop 复杂 复杂 中等 ~100 行 中等
最大特色 扩展系统 安全沙箱 多模型支持 自我进化 跨端部署
适合谁 专业开发者 企业团队 实验者 自动化爱好者 运维/全栈

选择框架的本质是选择设计哲学的取舍——没有最好的框架，只有最适合你场景的框架。

参考资源

AI
#AI Agent #架构分析 #Claude Code #Codex #GenericAgent #Hermes Agent #Pi Agent
主流 Agent 架构分析指南
https://tingfeng347.github.io/2026/07/31/主流agent架构分析指南/
作者
Tingfeng
发布于
2026年7月31日
许可协议