主流 Agent 架构分析

📅 2026/8/1 3:50:45 👁️ 阅读次数 📝 编程学习
主流 Agent 架构分析

主流 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 Loop)Agent 的推理-执行-观察循环
工具与执行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/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会话归档从已完成会话中提炼的任务记录

自我进化循环

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

每次完成新任务,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、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

接收任务/恢复会话 → 构建或复用系统提示 → 压缩前检查 → 选择提供商/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 ├── Modal(Serverless) └── Daytona(Serverless)

这意味着 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 Code40+Skills / Hooks / MCP最丰富的内置工具集
Codex20+Skills / 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 系列固定(Anthropic)
CodexGPT / o-series固定(OpenAI)
Pi 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真实浏览器会话保持,支持 ADB
Telegram/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 到消息平台到 API,Agent 的入口正在多元化。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 教程(Datawhale)
  • Hermes Agent 文档
  • 一文读懂 OpenAI Codex 源码