OpenHands

AI驱动的软件开发代理 - 思维链路架构深度分析

架构概览

项目简介

OpenHands 是一个由 AI 驱动的软件开发代理平台，采用模块化的事件驱动架构设计。它能够像人类开发者一样修改代码、运行命令、浏览网页、调用API，甚至从StackOverflow复制代码片段。

graph TB User[用户] --> Frontend[前端界面] Frontend --> Server[Web服务器] Server --> ConversationManager[对话管理器] ConversationManager --> Session[会话] Session --> EventStream[事件流] Session --> AgentController[代理控制器] Session --> Runtime[运行时环境] AgentController --> Agent[智能代理] AgentController --> State[状态管理] Agent --> LLM[大语言模型] Agent --> PromptManager[提示管理器] Agent --> ConversationMemory[对话记忆] EventStream --> ActionObservation[Action/Observation] Runtime --> Sandbox[沙盒环境] State --> History[历史记录] State --> Metrics[性能指标] subgraph "核心思维循环" Agent --> Action[生成动作] Action --> Runtime Runtime --> Observation[环境反馈] Observation --> State State --> Agent end

模块化设计

清晰的组件分离和接口定义，支持灵活的功能扩展

事件驱动

异步、解耦的系统通信机制，高效处理复杂交互

安全隔离

Docker容器化的执行环境，确保系统安全性

核心组件

  • LLM: 代理所有与大语言模型的交互，支持多种模型后端
  • Agent: 负责观察当前状态并生成向目标前进的行动
  • AgentController: 初始化代理、管理状态、驱动主循环
  • State: 表示代理任务的当前状态，包括步骤、历史、计划等
  • EventStream: 事件中心，组件可发布事件或监听其他组件的事件
  • Runtime: 执行动作并返回观察结果
  • Server: 通过HTTP代理OpenHands会话，驱动前端

思维链路核心机制

核心思维循环

OpenHands 的思维链路基于一个简单而强大的循环模式：

while True:
  prompt = agent.generate_prompt(state)
  response = llm.completion(prompt)
  action = agent.parse_response(response)
  observation = runtime.run(action)
  state = state.update(action, observation)

CodeActAgent 实现

CodeActAgent 实现了 CodeAct 理念：将所有行为统一为代码执行

对话模式

与用户进行自然语言交流，理解需求和提供反馈

代码执行模式

执行 Bash 命令和 Python 代码，直接操作环境

思维步骤处理流程

flowchart TD Start[开始新的思维步骤] --> CheckPending{是否有待处理动作?} CheckPending -->|是| ReturnPending[返回待处理动作] CheckPending -->|否| CheckExit{用户输入/exit?} CheckExit -->|是| Finish[AgentFinishAction] CheckExit -->|否| Condense[压缩历史记录] Condense --> GetMessages[构建消息历史] GetMessages --> LLMCall[调用LLM] LLMCall --> ParseResponse[解析响应] ParseResponse --> FunctionCalling{函数调用模式?} FunctionCalling -->|是| ParseTools[解析工具调用] FunctionCalling -->|否| ParseText[解析文本响应] ParseTools --> CreateActions[创建动作列表] ParseText --> CreateActions CreateActions --> QueueActions[加入动作队列] QueueActions --> ReturnFirst[返回首个动作] ReturnFirst --> Execute[执行动作] Execute --> GetObservation[获取观察结果] GetObservation --> UpdateState[更新状态] UpdateState --> Start

事件驱动架构

EventStream 核心机制

EventStream 是整个系统的神经中枢，实现了发布-订阅模式：

  • 异步事件处理: 使用线程池处理事件回调
  • 订阅者管理: 支持多个组件订阅同一事件类型
  • 错误隔离: 单个回调失败不影响其他订阅者
  • 事件持久化: 所有事件都会被序列化存储
graph LR subgraph "事件生产者" Agent[代理] Runtime[运行时] User[用户] Frontend[前端] end subgraph "EventStream核心" Queue[事件队列] Dispatcher[事件分发器] Storage[事件存储] end subgraph "事件订阅者" AgentController[代理控制器] SecurityAnalyzer[安全分析器] Server[服务器] Memory[记忆系统] end Agent --> Queue Runtime --> Queue User --> Queue Frontend --> Queue Queue --> Dispatcher Dispatcher --> Storage Dispatcher --> AgentController Dispatcher --> SecurityAnalyzer Dispatcher --> Server Dispatcher --> Memory

Action-Observation 模式

Action 类型

  • CmdRunAction: 执行 Bash 命令
  • IPythonRunCellAction: 执行 Python 代码
  • FileEditAction: 文件编辑操作
  • MessageAction: 消息通信
  • AgentThinkAction: 记录思考过程
  • AgentFinishAction: 完成任务

Observation 类型

  • CmdOutputObservation: 命令执行结果
  • FileReadObservation: 文件内容
  • ErrorObservation: 错误信息
  • BrowserOutputObservation: 浏览器操作结果

状态管理与记忆系统

State 类设计

State 类是整个系统的核心数据结构，包含：

多代理状态管理

任务和子任务的层级结构、全局和本地迭代计数、代理委托层级管理

运行时状态

当前代理状态（加载中、运行中、暂停、等待用户输入）、流量控制状态、确认模式、最后遇到的错误

历史数据管理

事件历史记录的起始和结束 ID、序列化支持（pickle + base64）、会话保存和恢复

ConversationMemory 系统

ConversationMemory 负责将事件历史转换为 LLM 可理解的对话格式：

flowchart TD Events[事件列表] --> EnsureSystem[确保系统消息存在] EnsureSystem --> EnsureUser[确保初始用户消息] EnsureUser --> ProcessLoop[处理事件循环] ProcessLoop --> IsAction{是Action?} IsAction -->|是| ProcessAction[处理Action消息] IsAction -->|否| ProcessObservation[处理Observation消息] ProcessAction --> CheckToolCall{是否有工具调用?} CheckToolCall -->|是| AddToToolCall[添加到工具调用消息] CheckToolCall -->|否| AddRegularMsg[添加常规消息] ProcessObservation --> CheckToolResponse{是工具响应?} CheckToolResponse -->|是| AddToolResponse[添加工具响应] CheckToolResponse -->|否| AddObsMsg[添加观察消息] AddToToolCall --> CheckComplete{工具调用完整?} CheckComplete -->|是| FlushToolCall[输出完整工具调用] CheckComplete -->|否| Continue[继续] AddRegularMsg --> Continue AddToolResponse --> Continue AddObsMsg --> Continue FlushToolCall --> Continue Continue --> ProcessLoop ProcessLoop --> ApplyCache[应用提示缓存] ApplyCache --> ReturnMessages[返回消息列表]

核心功能

  1. 事件处理: 将 Action 和 Observation 转换为消息
  2. 工具调用管理: 在函数调用模式下跟踪工具调用和响应
  3. 消息角色管理: 确保正确的用户/助手/工具角色交替
  4. 缓存优化: 为特定 LLM 提供商应用提示缓存

提示工程与LLM交互

PromptManager 设计

PromptManager 使用 Jinja2 模板系统管理提示：

模板结构

  • system_prompt.j2: 系统级指令模板
  • user_prompt.j2: 用户示例消息模板
  • additional_info.j2: 工作区上下文信息
  • microagent_info.j2: 微代理信息模板

关键功能

  • 动态渲染提示模板
  • 集成微代理知识
  • 工作区上下文管理
  • 剩余轮次提醒

Function Calling 实现

CodeAct 代理支持两种交互模式：

函数调用模式

  • 将每种操作定义为工具/函数
  • LLM 通过函数调用表达意图
  • 严格的参数验证和错误处理

文本解析模式

  • LLM 以文本形式输出代码块
  • 通过正则表达式解析执行意图
  • 支持更灵活的自然语言交互

工具定义示例

# Bash 命令工具
create_cmd_run_tool() = {
    'type': 'function',
    'function': {
        'name': 'bash',
        'description': 'Execute bash command',
        'parameters': {
            'type': 'object',
            'properties': {
                'command': {'type': 'string'},
                'timeout': {'type': 'number', 'optional': True}
            }
        }
    }
}

运行时环境设计

Runtime 抽象层

Runtime 为代理提供与外部环境交互的统一接口：

  • 命令执行: 沙盒化的命令执行环境
  • 文件系统操作: 安全的文件读写操作
  • 浏览器交互: 网页自动化操作
  • 插件管理: 可扩展的功能插件系统
  • 环境变量管理: 动态配置管理

沙盒安全机制

Docker 容器隔离

  • 每个会话运行在独立容器中
  • 限制网络访问和资源使用
  • 支持自定义基础镜像
graph TB subgraph "OpenHands Backend" AgentController[代理控制器] EventStream[事件流] end subgraph "Docker Container" ActionExecutor[动作执行器] BashShell[Bash Shell] JupyterServer[Jupyter服务器] Browser[浏览器环境] FileSystem[文件系统] Plugins[插件系统] end AgentController --> EventStream EventStream -->|HTTP API| ActionExecutor ActionExecutor --> BashShell ActionExecutor --> JupyterServer ActionExecutor --> Browser ActionExecutor --> FileSystem ActionExecutor --> Plugins ActionExecutor -->|观察结果| EventStream

核心技术创新点

CodeAct 理念实现

统一动作空间，将所有代理行为归结为代码执行，简化推理复杂度

记忆压缩机制

智能历史压缩，基于重要性的事件过滤，支持上下文窗口管理

分层状态管理

全局任务状态和局部子任务状态，支持多代理协作和委托

设计模式应用

事件驱动架构

所有组件通过事件进行松耦合通信，支持异步处理和水平扩展

命令模式

Action 封装了所有可执行操作，支持撤销、重做和审计

策略模式

不同类型的 Agent 实现不同的推理策略，支持运行时切换

观察者模式

EventStream 实现发布-订阅机制，支持多个组件监听同一事件

完整的思维链路数据流

sequenceDiagram participant User as 用户 participant Frontend as 前端 participant Server as 服务器 participant AgentController as 代理控制器 participant Agent as 智能代理 participant LLM as 大语言模型 participant Runtime as 运行时 participant EventStream as 事件流 User->>Frontend: 输入任务 Frontend->>Server: WebSocket消息 Server->>EventStream: MessageAction EventStream->>AgentController: 事件通知 AgentController->>Agent: step(state) Agent->>Agent: 检查待处理动作 Agent->>Agent: 压缩历史记录 Agent->>Agent: 构建消息历史 Agent->>LLM: completion(messages, tools) LLM-->>Agent: ModelResponse Agent->>Agent: 解析响应为动作列表 Agent-->>AgentController: 返回动作 AgentController->>EventStream: 发布动作 EventStream->>Runtime: 动作执行请求 Runtime->>Runtime: 执行动作(命令/代码/文件操作) Runtime-->>EventStream: 观察结果 EventStream->>AgentController: 观察结果通知 AgentController->>AgentController: 更新状态 AgentController->>EventStream: 状态变更事件 EventStream->>Server: 事件通知 Server->>Frontend: WebSocket推送 Frontend->>User: 显示结果

总结

架构优势

5 核心架构优势
4 主要技术创新
7 核心组件
∞ 扩展可能性

架构优势

  • 模块化设计: 清晰的组件分离和接口定义
  • 事件驱动: 异步、解耦的系统通信机制
  • 安全隔离: Docker容器化的执行环境
  • 可扩展性: 插件系统和多代理支持
  • 状态管理: 完整的会话持久化和恢复机制

技术创新

  • CodeAct统一范式: 将复杂任务简化为代码执行
  • 智能记忆压缩: 高效的上下文窗口管理
  • 双模式LLM交互: 结构化工具调用+自然语言解析
  • 分层状态模型: 支持复杂的多级任务分解

实现质量

代码结构清晰

良好的抽象层次和设计模式运用

错误处理完善

多层级的异常捕获和恢复机制

性能优化

异步处理、事件缓存、智能压缩

测试覆盖

完整的单元测试和集成测试

结论

这个架构为构建可靠、安全、高效的AI代理系统提供了优秀的设计参考，特别是在处理复杂软件开发任务方面展现了强大的能力。OpenHands 将AI代理技术推向了一个新的高度，为未来的智能开发工具奠定了坚实的基础。