智能体系统

架构概述

Agent System 在会话管理、Agent 编排和执行环境之间进行协调。它由会话管理组件、核心 AgentController 编排层和 Agent 实现组成。

核心 Agent 系统架构

关键组件

Session 和 AgentSession - 会话管理和生命周期
AgentController - 核心编排和状态管理
Agent 抽象类和实现 - AI Agent 逻辑
EventStream - 事件驱动通信系统
State - Agent 执行状态跟踪

来源

关键组件

会话管理

Session 层通过 Session 和 AgentSession 类管理 Agent 实例及其生命周期。

会话管理类

会话管理系统处理

通过 Session.sio 与前端进行 WebSocket 通信
通过 Session.initialize_agent() 初始化 Agent
通过 AgentSession._create_runtime() 创建运行时环境
通过 AgentSession._create_controller() 实例化 Controller

Agent 基类

Agent 抽象类定义了所有 Agent 实现的接口。

智能体类结构

Agent 抽象类提供

通过 Agent._registry 和 Agent.get_cls() 进行注册机制
通过 step()、reset() 和 get_system_message() 的标准接口
通过 Agent.llm 进行 LLM 集成
通过 Agent.sandbox_plugins 提供插件系统

来源

代理控制器

AgentController 类负责编排 Agent 执行、管理状态转换以及与事件系统协调通信。

AgentController 类结构

核心职责

状态管理：通过 set_agent_state_to() 在 RUNNING、PAUSED、ERROR、FINISHED 状态之间进行转换
执行控制：通过 step() → _step() 进行异步步进，并进行迭代和预算限制
事件处理：通过 on_event() → _handle_action() / _handle_observation() 处理事件
委托：通过 start_delegate() 创建委托 Controller，并通过 end_delegate() 管理清理
生命周期管理：在 __init__() 中初始化，在 close() 中清理

关键状态转换

RUNNING → AWAITING_USER_INPUT 当 Agent 请求用户输入时
RUNNING → PAUSED 当达到迭代/预算限制时
RUNNING → ERROR 发生异常或检测到卡顿时
RUNNING → FINISHED 当收到 AgentFinishAction 时

来源

状态管理

State 类在 Agent 的整个生命周期中跟踪 Agent 的执行状态、资源使用情况和对话历史。

Agent 状态机

状态属性

state.agent_state：当前的 AgentState 枚举值
state.iteration / state.local_iteration：全局和局部步数计数器
state.max_iterations：执行限制强制执行
state.metrics：LLM 成本和 token 使用情况跟踪
state.history：Event 对象列表（动作和观察）
state.traffic_control_state：用于资源管理的 NORMAL、THROTTLING、PAUSED
state.last_error：当 agent_state == ERROR 时的错误消息

来源

事件系统

Agent System 通过 EventStream 进行通信，该流在组件之间传输事件。主要有两种类型的事件：

Actions：由 Agent 或用户发起的用于执行操作的事件
Observations：包含操作反馈或结果的事件

事件系统提供

组件之间的结构化通信机制
动作和观察的历史记录
支持不同类型的操作（消息传递、命令执行、文件操作等）

来源

执行流程

Agent 执行遵循事件驱动模式，具有异步步进和状态管理。

主要执行顺序

关键执行方法

AgentController.step()：通过 _step_with_exception_handling() 创建异步任务
AgentController._step()：核心步进逻辑，包含限制检查和卡死检测
AgentController.should_step()：判断事件是否应该触发 Agent 执行
Agent.step()：Agent 特定逻辑，返回下一个 Action

步进触发器

用户发送的 MessageAction (source=EventSource.USER)
运行时发送的 Observation 事件（不包括 NullObservation）
用于委托的 AgentDelegateAction
用于内存管理的 CondensationAction

状态更新

update_state_before_step()：增加 state.iteration 和 state.local_iteration
update_state_after_step()：合并来自 agent.llm.metrics 的 LLM 指标

来源

Agent 委托

Agent System 支持委托，其中 Agent 可以使用 AgentDelegateAction 为特定任务生成专门的子 Agent。

委托架构

委托实现

启动委托（start_delegate()）

事件路由

父 Controller 通过 on_event() 将事件转发给活动的委托 Agent
委托 Agent 继承父 Agent 的 max_iterations 和 max_budget_per_task
共享的 EventStream 维护统一的事件历史记录

完成处理（end_delegate()）

创建 AgentDelegateObservation 并包含委托 Agent 的输出
通过 tool_call_metadata 将观察结果与原始 AgentDelegateAction 相关联
父 Controller 恢复正常操作

关键委托属性

state.delegate_level：跟踪委托的深度
controller.delegate：指向活动委托 Controller 的引用
controller.parent：指向父 Controller 的引用（如果是委托 Agent）
共享指标：state.metrics 在委托层级结构之间合并

来源

CodeAct Agent 实现

The CodeActAgent 是主要的代理实现，将 LLM 操作整合到统一的代码操作空间中，并支持函数调用功能。

CodeActAgent 架构

关键实现细节

Step 方法 (step())

工具配置

通过 config.enable_cmd、config.enable_jupyter 等条件性启用工具
为具有令牌限制的模型（GPT、O1、O3）提供简短的工具描述
通过工厂函数（如 create_cmd_run_tool()）创建工具

内存管理

ConversationMemory 将事件处理为 LLM 兼容的消息
Condenser 管理长对话历史
通过 llm.is_caching_prompt_active() 支持提示缓存

函数调用

工具定义为 ChatCompletionToolParam 对象
通过 codeact_function_calling.response_to_actions() 处理响应
支持 MCP（模型上下文协议）工具

来源

内存和对话管理

代理系统通过 ConversationMemory 和 Condenser 组件提供复杂的内存管理，用于将事件历史处理为 LLM 兼容的格式。

内存系统架构

ConversationMemory 处理

事件到消息的转换

关键处理步骤

首先查找并处理 SystemMessageAction
将 MessageAction 事件转换为用户/助手消息
处理函数调用工具响应
管理角色轮换（防止连续出现相同角色的消息）
通过 max_message_chars 应用内容截断

Condenser 系统

Condenser.condensed_history() 返回 View 或 Condensation
View：用于即时处理的过滤事件
Condensation：返回 CondensationAction 来总结/遗忘事件
通过 Condenser.from_config() 支持各种压缩器类型

提示缓存

当 llm.is_caching_prompt_active() 返回 True 时应用
系统消息标记为 cache_prompt=True
最后一条用户消息标记为缓存断点
通过优化具有相似上下文的重复 LLM 调用

来源

代理配置

OpenHands 中的代理系统通过 AgentConfig 提供广泛的配置，用于自定义代理功能和行为。

AgentConfig 结构

配置类别

工具启用

配置选项	目的	默认
`enable_cmd`	通过 `CmdRunAction` 执行 Bash 命令	`True`
`enable_jupyter`	通过 `IPythonRunCellAction` 执行 Python	`True`
`enable_browsing`	网页浏览功能	`True`
`enable_editor`	文件编辑工具	`True`
`enable_llm_editor`	基于 LLM 的文件编辑	`否`
`enable_mcp`	模型上下文协议工具	`True`

内存管理

condenser：用于历史压缩的 CondenserConfig
enable_history_truncation：自动上下文窗口管理
disabled_microagents：要排除的微代理名称列表

在 CodeActAgent 中的用法

来源

总结

OpenHands 中的代理系统通过几个关键层提供了全面的 AI 代理编排框架

会话管理： Session 和 AgentSession 类处理 WebSocket 通信、代理初始化和生命周期管理。

代理编排： AgentController 作为中央编排器，通过异步步进模式管理状态转换、事件处理和执行流程。

代理实现： 抽象的 Agent 类定义了接口，其中 CodeActAgent 是支持函数调用和代码执行的主要实现。

事件系统： 操作和观察流经 EventStream，以在代理、运行时环境和用户界面之间进行协调。

内存管理： ConversationMemory 和 Condenser 组件处理事件历史，将其转换为 LLM 兼容的格式，并支持提示缓存和历史压缩。

委托： 分层代理委托允许专门的子代理处理特定任务，同时保持统一的状态和事件管理。

该系统通过 AgentConfig 支持广泛的配置，根据部署需求启用/禁用命令执行、Jupyter Notebooks、Web 浏览和文件编辑等工具。

来源

总结

OpenHands 中的代理系统提供了一个全面的框架来创建、配置和编排 AI 代理。它管理代理执行，促进组件之间的通信，并提供委托和专业化的机制。通过事件系统，代理可以与环境交互并响应用户输入，而控制器则确保正确的状态管理和执行流程。