AI Agent框架探秘：拆解 OpenHands（1）--- 核心理念

[AI Agent框架探秘：拆解 OpenHands（1）--- 核心理念](#AI Agent框架探秘：拆解 OpenHands（1）--- 核心理念)
- [0x00 摘要](#0x00 摘要)
- [0x01 背景](#0x01 背景)
  - [1.1 什么是Agent](#1.1 什么是Agent)
  - [1.2 Agent工程的重要性](#1.2 Agent工程的重要性)
  - [1.3 架构才是竞争优势](#1.3 架构才是竞争优势)
- [0x02 AI Agent 系统](#0x02 AI Agent 系统)
  - [2.1 架构设计的难点](#2.1 架构设计的难点)
  - [2.2 核心组件](#2.2 核心组件)
  - [2.3 Devin & OpenHands（原OpenDevin）](#2.3 Devin & OpenHands（原OpenDevin）)
- [0x03 OpenHands 架构概念图谱](#0x03 OpenHands 架构概念图谱)
  - [3.1 系统架构](#3.1 系统架构)
  - [3.2 代码库目录结构](#3.2 代码库目录结构)
  - [3.3 核心组件](#3.3 核心组件)
- [0xFF 参考](#0xFF 参考)

自本文起，我们将开启一个新的系列，以OpenHands（原 OpenDevin）为例，深入剖析Agent框架。

写这个系列的原因，是因为和几个同学讨论Agent系统，但是总觉得自己讲得浮于表面，兄弟们好像也没有很理解。因此决定再系统梳理一下。

因为本系列借鉴的文章过多，可能在参考文献中有遗漏的文章，如果有，还请大家指出。

0x00 摘要

掌握Agent的底层逻辑，不仅是熟练使用的基础，更是设计、评估和扩展的关键。对于产品经理、人工智能工程师和技术决策者来说，只有深入理解Agent的技术蓝图，才能在AI应用的落地过程中做出精准布局，抓住未来的机遇。我们希望从技术底层出发，深入探讨以下关键问题：

构建一个实用的AI Agent需要哪些核心技术模块的支持？
这些核心模块如何协同工作，形成完整的任务执行闭环？
AI Agent系统在落地过程中会面临哪些关键挑战，OpenHands如何解决这些工程化难题？

我们希望通过这一场深入的"拆解"之旅，超越表层功能的演示，直接触及其架构的基石。

之所以分析OpenHands，是因为OpenHands（前身为 OpenDevin）作为开源的 AI 软件开发代理框架，在功能、架构和兼容性等方面均具备鲜明特色，且从入门难度、学习价值和实践场景来看，它十分适合用来学习 Agent 框架。具体特色如下：

入门门槛低，上手难度小：支持自然语言交互，开发者无需复杂编码即可下达开发任务，降低初期学习成本。同时提供 GUI 和 CLI 等友好界面，还有详尽的实战案例和清晰的文档，便于理解 Agent 与工具、LLM 的协同逻辑。且基于 MIT 许可完全开源，可自由查看 Agent 调度、任务编排等核心源码。
覆盖 Agent 核心知识体系：学习它能掌握多 Agent 协作、任务拆解、工具调用、沙盒安全控制等 Agent 框架的核心技术点。其与网页交互、API 集成、代码处理等实战场景结合紧密，能帮助学习者理解 Agent 在真实开发流程中的落地逻辑。
兼具学习与落地价值：既能用于简单的 Agent 原型搭建，快速验证想法；也能支撑大规模Agent的可靠部署，适配从学习测试到生产应用的全流程。此外，与主流 Agent SDK 相比，其独特的沙盒化生产服务器、远程执行等特性，能让学习者接触到更全面的 Agent 进阶能力，提升技术竞争力。

0x01 背景

当我们讨论AI Agent系统的技术时，需要先理解一个关键问题：真正让系统有竞争力的，是那些一眼能看到的"智能功能"，还是背后支撑一切平稳运行的"工作流架构"？这个答案不仅决定了该先研发什么，更关乎系统能不能打造出别人抄不走的长期优势。

1.1 什么是Agent

Agent的定义具有多元视角：

有人将其界定为可长期自主运行、借助各类工具完成复杂任务的独立系统；
有人认为Agent是可以在最小人工干预下完成「感知 → 规划 → 行动 → 反馈」闭环的Agent，既能解析自然语言目标，又能调用搜索引擎、数据库等外部工具。
有人则将其理解为遵循预设工作流程的规范化实现方案。

Anthropic 将这些不同形态的系统统一归为 "Agent系统（agentic systems）"，同时从架构层面明确区分了 "工作流程（Workflows）" 与 "Agent" 这两个核心概念。具体来看：

工作流是编码"如何做"：工作流程类系统如同按照固定剧本演出的舞台剧，大语言模型（LLMs）与各类工具的协作完全遵循预先编写的代码路径推进；
Agent是编码"做什么"：Agent系统则更像拥有自主决策能力的项目经理，由大语言模型动态主导流程走向与工具调用，全程掌控任务的执行方式。

随着大语言模型在四大关键能力上的日趋成熟 ------ 包括复杂输入理解、逻辑推理与任务规划、可靠工具调用以及错误恢复能力，Agent已在生产场景中逐步落地应用。其工作流程通常始于人类用户的指令或交互式沟通，待任务目标明确后，便自主开展规划与执行操作，过程中若需补充信息或寻求判断，会主动向人类用户发起请求。在每一步执行环节，Agent必须从环境中获取 "真实数据（Ground Truth）"------ 比如工具调用返回结果或代码运行输出 ------ 以此评估任务进展。当抵达预设检查点或遭遇执行阻碍时，Agent可暂停操作以获取人类反馈。任务一般在完成后终止，同时也会设置停止条件（如最大迭代次数）来确保过程可控。

1.2 Agent工程的重要性

Agent的实现逻辑相对简洁，本质上是大语言模型在 "环境反馈 - 工具调用" 的循环中持续运作。Agent系统的核心构建模块是一个增强功能的大语言模型（LLM），它能够主动地利用检索、工具和记忆等能力来优化其功能。对于绝大部分应用程序来说，通过检索（RAG）和在 prompt 中添加上下文示例（Prompt Engineering）来优化单个 LLM 调用通常就足够了。

虽然只要提供一堆工具和prompt，agent就可以自行探索-分析-决策-执行直到解决任务。从宏观角度上来说这样并没有错，但让LLM控制一切的结果就是，不完善的prompt和tools带来了无限循环和放飞自我。因此，尽管AI模型是Agent的"大脑"，但要实现生产级的落地，Agent工程才是关键支撑。Rakesh Gohel发布的"AI Agent冰山模型"指出：构建一个真正可用的Agent，90%的工作是软件工程，仅10%是AI技术：

"10% AI"：AI模型只是Agent的"大脑"：理解任务、规划步骤、生成内容。
"90% Engineering"：工程是支撑Agent的整个"身体和神经系统"，包括用户交互、权限控制、任务编排、工具调用、日志、异常回滚等。

在这背后，一整套系统化的Agent架构，正悄然决定着这些Agent的效率、扩展性和演化方向。如果将大语言模型（LLM）比作AI的发动机，那么"Agent架构"就是决定AI能走多远的底盘和驾驶系统。

1.3 架构才是竞争优势

AI Agent不是一款单一产品，而是一种全新的软件形态------它不是"更聪明的机器人"，而是"能自主协作的数字个体"。其技术难点不在于"想象力"，而在于"工程落地能力"。未来，真正引领Agent发展的，必然是那些既懂AI技术，又精通系统架构的"Agent工匠"。Agent架构，已成为下一代AI应用的核心竞争赛道。能否理解"Memory-Plan-Tool-Reflection"的协同逻辑，能否构建"透明、可控、可扩展"的任务系统，决定了一个团队是否具备打造实用Agent应用的核心能力。

拿browerAgent来说，它们能生成代码、跟网页互动，看着很厉害，但这些能力其实靠三个外部条件撑着 ------ 而这三个条件现在行业里正变得越来越通用。

基础模型能力人人能用。未来大语言模型能力越来越强，AI Agent能做的功能会越来越容易实现，慢慢变成行业标配。这么一来，不同系统在 "智能" 上的差距越来越小。
提示词技巧容易复制。没法成为独家优势。
工具调用越来越标准化。Agent 调用工具的能力，本质就是用别人的 API 接口。任何团队都能直接集成现成工具，补全自己的功能短板，这方面的竞争慢慢变得千篇一律。

真正的技术壁垒，从来都是打造一个稳定、能控制、能监控、能扩展的底层运行环境。这需要团队有深厚的技术积累、能搞定复杂系统，还得一直迭代应对新问题。这些问题是AI跟现实世界互动时天生就有的，不会因为模型变强就自动消失，反而会决定系统稳不稳定、靠不靠谱。谁能解决状态管理、工具容错、计划可控、行为透明这些"系统级痛点"，谁就能在Agent技术革命中占据主动。

未来AI Agent系统的竞争，会从"谁能做什么"的功能比拼，变成"谁能做得更稳、更好、更长久"的工程实力较量------说白了，工程实力才决定长期竞争力。

0x02 AI Agent 系统

构建一套成熟的 AI Agent Framework，本质是打造一个能支撑Agent自主感知、环境感知、决策制定、动作执行、自我进化的 "数字生命体" 基础设施。其核心在于拆解Agent的核心能力模块，明确各组件的职责边界与协作逻辑，同时攻克系统稳定性、灵活性与实用性的关键瓶颈。Agent系统核心涵盖四大能力：

通过 Function Call、MCP 协议等工具调用实现环境交互感知；
借助 ReAct、Reflexion 等方法完成自主推理决策；
采用短期记忆（依托 Prompt / 上下文窗口）与长期记忆（通过 RAG 和向量数据库管理）的范式进行知识管理；
通过 A2A、ACP、ANP 等协议达成多Agent间的通信协作。

2.1 架构设计的难点

大模型本质是概率输出，这种"概率本性"带来的三位一体风险

不一致性：同一输入多次采样结果发散。
不真实性：幻觉导致事实错误。
不及时性：静态训练数据过期。

这样导致 Agent 带来的的四大硬核卡点为：

记忆断片。单纯的Agent缺少专门的任务状态感知机制，仅靠上下文拼接无法稳定跟踪长流程任务。比如，多步任务里， "中间态"只躺在 LLM 的上下文窗口里，既没有结构化存储，也没有显式语义索引。
一错就躺。单纯的Agent 缺乏工具调用的异常感知与容错机制，
黑箱拆包。LLM 直接吐出自然语言计划，开发者无法插拔，更无法验证，只能在执行末端才发现。
审计黑洞。Agent 调了谁、取了什么字段、基于哪句用户提示做决策，全程无留痕，企业合规无从谈起。

因此，Agent 的竞争正离开"谁能调用更多 API"，转向"谁能把不确定的模型封装成确定性的系统"。把概率装进状态机，把幻觉关进审计笼，把成本压进预算表------这才是Agent 系统的真正门槛。

2.2 核心组件

Agent绝非单一语言模型的增强版，LLM仅相当于其 "认知中枢"，真正支撑其完整功能的是一套协同运作的多模块架构，成熟可落地的Agent系统至少包含几大核心模块，各模块如同精密团队中的不同角色，各司其职又紧密配合。

规划与决策引擎（Planner / Policy）。LLM 作为 "认知中枢"，就像团队里的 "智囊团"，核心负责解析用户任务意图、把用户的"复杂终极目标"切成"可执行的子任务序列"，拆解复杂任务为子任务、明确子任务的依赖关系、生成代码、报告等输出内容。即支持一次性静态计划、也支持 ReAct / CodeAct 这种逐步展开，即支持动态计划调整：根据工具调用结果、环境变化或用户反馈，实时修正子任务流程，避免计划与实际执行脱节。
Memory 模块是 "上下文延续器"，负责存储对话上下文、任务执行关键节点与进度、历史经验等信息，保障任务执行的连贯性。用于存储对话历史、中间结果和长期记忆。这样，通过在Prompt中引入对前文的总结或关键数据，Agent能"记住"先前步骤的结果，确保状态的一致性和跨步骤的上下文衔接。
Planner 模块扮演 "行动路线图" 的角色。其实现机制包括基于规则的固定流程（适用于标准化任务）、依托 LLM 推理能力的动态生成（适用于灵活需求），以及结合二者优势的混合型调度（如基于 LangGraph 构建有向图任务流）。
Tool-use 模块是Agent的 "手脚"，让模型"看到"工具，而不是"摸黑"调用，打破了仅输出文本的局限，通过调用第三方 API、检索外部知识库、读写本地文件等方式连接外部资源，完成实际操作。
Reflection 模块赋予Agent "元认知能力"，如同团队的 "复盘专员"，在任务失败或受阻时，对比执行结果与预期，评估执行效果、定位问题原因并调整策略。

这几大模块相辅相成，构成 "状态驱动 + 意图分解 + 工具调用 + 自我学习" 的有机整体，而非简单叠加。

另外，在具体实现中，通常也会有如下组件：

事件总线（Event Bus）：用于解耦，将用户消息、工具返回、状态变更、异常报告都序列化为事件，广播给订阅者。
运行时沙箱（Runtime Sandbox）：给模型提供"动手"空间------文件系统、网络、Shell、Python 解释器、第三方库。
观测与遥测（Observability）：提供可视化的任务执行界面，展示任务流程、子任务进度、模块交互日志，支持开发者实时监控，让运维者看到「黑盒」------每次调用链、token 消耗、异常栈、决策理由全部落盘。
配置与存储模块（Config & Storage）：管理框架的全局配置，如 LLM 参数、任务预算（最大迭代次数、成本上限）、存储路径、工具列表等，支持动态配置更新。实现数据持久化，包括任务状态、执行轨迹、记忆数据、配置信息等，确保系统重启后可恢复。

2.3 Devin & OpenHands（原OpenDevin）

‌Devin是由Cognition AI开发的全球首个AI程序员，具备全栈开发能力，能自主完成代码编写、调试、部署及AI模型训练等任务‌。Devin 代表了一种先进的自主Agent，旨在应对软件工程的复杂性。它利用了诸如 shell、代码编辑器和网络浏览器等工具的组合，展示了 LLM 在软件开发中未被充分利用的潜力。

OpenDevin 项目诞生于复制、增强并创新原始 Devin 模型的愿望。OpenDevin 的目标是探索并扩展 Devin 的能力，识别其优势和改进领域，以指导开放代码模型的进展。通过吸引开源社区的参与，OpenDevin 旨在应对 Code LLM 在实际场景中面临的挑战，产出对社区有重大贡献的作品，并为未来的进步铺平道路。

OpenHands 目前 GitHub 星标数已超 6.5 万。

OpenHands 的网址为：https://docs.openhands.dev/

github 链接为：https://github.com/OpenHands/OpenHands

Software Agent SDK: https://github.com/OpenHands/software-agent-sdk

Benchmarks: https://github.com/OpenHands/benchmarks

最新的OpenHands论文如下：The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents 2511.03690v1

0x03 OpenHands 架构概念图谱

为精准解锁 OpenHands 源码的深层逻辑，我们需要构建一幅清晰的架构概念图谱，将分散的核心组件与设计理念串联成有机整体。这一图谱的每一环都承载着关键使命，共同构筑起 AI Agent高效运行的基础。

3.1 系统架构

下图是OpenHands 系统架构的高级概览。系统分为两个主要部分：前端和后端。前端负责处理用户交互并展示结果。后端负责处理业务逻辑并执行Agent操作。这种架构的关键优势在于其灵活性和可扩展性：新的Agent类型、行动类型或运行时环境可以轻松集成到现有系统中。

后端架构如下：

3.2 代码库目录结构

OpenHands的代码库组织清晰，以下是最主要的目录：

Agent中心（agenthub）：这是Agent的核心区域，负责代码生成和执行相关的逻辑，是平台的核心能力载体。它包含专注于代码生成与执行的Agent逻辑，是平台的核心能力所在。此外，还包括负责浏览器交互的Agent实现。
事件系统（events） ：这是事件驱动架构的核心目录，定义了系统的"通信语言"。它包含封装任务执行结果等反馈类事件的observation/，以及定义Agent可执行的各类动作指令的action/。stream.py实现了事件流的管理机制，负责事件的分发、存储与订阅，是组件协同工作的关键枢纽。
运行时环境（runtime/） ：提供Agent执行的底层环境支持。impl/目录包含Docker容器、本地环境等不同运行时的具体实现；plugins/支持通过插件扩展运行时功能，提升系统的灵活性。
记忆管理（memory/） ：负责管理Agent的历史数据与记忆。conversation_memory.py处理对话历史的存储与检索；condenser/实现历史记录的压缩逻辑，解决LLM上下文窗口有限的问题，保障长周期任务的连贯性。
语言模型集成（llm/）：实现与各类大型语言模型的集成。
控制器（controller/）：系统的"指挥中心"，负责Agent的调度与管理。

这种结构反映了OpenHands的模块化设计，各组件之间有明确的职责划分，便于维护和扩展。这些目录之间的逻辑结构大致如下：

3.3 核心组件

OpenHands采用了一种基于事件的架构，将Agent、运行时环境和用户界面解耦，实现灵活的交互模式。OpenHands 的关键类包括：

LLM：负责与大型语言模型的所有交互。由于 LiteLLM 的支持，它可以与任何底层完成模型一起工作。
Agent：负责查看当前状态，并产生一个动作，使目标更进一步接近最终目标。
AgentController：初始化 Agent，管理状态，并驱动主要循环，一步步推动 Agent 前进。
State：代表 Agent 任务的当前状态。包括当前步骤、最近事件的历史记录、Agent的长期计划等。State 模块就像 Agent 的 "记忆大脑"，不仅能记下任务执行中的各种状态数据，还支持断点恢复，长周期任务就算中断了，也能接着之前的进度继续做，不用从头再来。
EventStream ：事件的中心枢纽，任何组件都可以发布事件，或监听其他组件发布的事件。
- Event ：动作或观察
  - Action：代表一个请求，例如编辑文件、运行命令或发送消息。
  - Observation：代表从环境中收集的信息，例如文件内容或命令输出。
- Action 和 Observation 相当于组件间的 "通用语言"------Action 带着要执行的指令，Observation 传回执行的结果，俩者配合到位，信息传递才顺畅不卡壳。这些模块不是各干各的，而是靠 Event Stream 这个 "核心枢纽" 连在一起协同工作 ------ 各种事件都在这里汇聚、分发，推着任务按计划一步步走，最终让 AI Agent有能力处理复杂任务。
- ReAct 范式就像是 Agent 的 "行为准则"，定下了 "先思考、再行动、收反馈" 的核心逻辑，确保它做决策时有条理、不混乱。事件驱动模型则搭起了系统的 "骨架"，所有交互都靠事件流转来推进，各个模块不用硬绑在一起，能灵活应对各种情况。
Runtime ：负责执行动作，并发送回观察结果。
- Sandbox：运行命令的运行时环境部分，例如在 Docker 内部。
- Runtime 和 Memory 这些组件是系统的关键 "器官"：Runtime 会提供一个隔离的执行环境，保证代码运行时安全又稳定，不会搞乱其他部分；Memory 则把历史数据管得明明白白，给 Agent 做决策提供过往经验。
Server ：通过 HTTP 管理 OpenHands 会话，例如驱动前端。
- Session：保存单个 EventStream、单个 AgentController 和单个 Runtime。通常代表一个单一任务（但可能包括几个用户提示）。
- ConversationManager：维护一个活动会话列表，并确保请求被路由到正确的会话。