代理控制器

相关源文件

• openhands/controller/agent_controller.py
• openhands/core/setup.py
• openhands/server/session/agent_session.py
• openhands/server/session/conversation_init_data.py
• openhands/server/session/session.py
• openhands/utils/http_session.py
• tests/unit/test_agent_controller.py

Agent Controller 是 OpenHands 中负责管理 AI Agent 生命周期、协调事件驱动的对话以及控制资源使用的核心编排组件。它充当高级会话管理与实际 AI Agent 之间的桥梁，处理状态转换、行动-观测循环和多 Agent 委托工作流。

有关更广泛的 Agent 系统架构的信息，请参阅 Agent System。有关特定 Agent 实现的详细信息，请参阅 CodeAct Agent。

核心架构

AgentController 类是主要编排器，负责管理对话会话中单个 Agent 的执行。它在多个子系统之间进行协调，以实现交互式 AI Agent 工作流。

Agent Controller 架构

Controller 维护几个关键关系

• Agent 管理：控制 Agent 生命周期和步骤执行
• 事件编排：通过 EventStream 订阅和发布事件
• 状态跟踪：维护对话状态、指标和迭代次数
• 资源控制：强制执行迭代次数和预算限制

来源：openhands/controller/agent_controller.py84-98 openhands/controller/agent_controller.py99-181

初始化和配置

Controller 在初始化过程中会自动设置事件订阅、历史过滤和系统消息注入。

参数	目的	默认
agent	要控制的 AI Agent 实例	必填
event_stream	事件通信通道	必填
max_iterations	允许的最大 Agent 步骤数	必填
max_budget_per_task	美元预算上限	None
confirmation_mode	要求用户确认操作	否
agent_to_llm_config	用于委托的 LLM 配置	{}
agent_configs	用于委托的 Agent 配置	{}
headless_mode	无 UI 交互运行	True

Controller 在初始化过程中会自动设置事件订阅、历史过滤和系统消息注入。

来源：openhands/controller/agent_controller.py99-181 openhands/controller/agent_controller.py182-207

Agent 状态管理

Controller 通过一个明确的状态机来管理 Agent 的状态，该状态机跟踪 Agent 的当前状态并处理转换。

Agent 状态转换图

状态转换通过 set_agent_state_to() 进行管理，该方法处理指标聚合、事件发布和资源清理等副作用。

来源：openhands/controller/agent_controller.py592-659 openhands/core/schema.py

事件处理和行动-观测循环

Controller 实现了一个事件驱动的架构，其中 Agent 对事件做出响应并生成产生观测的行动。

事件处理流程

Controller 通过专门的处理程序处理不同的事件类型

• Actions：_handle_action() 用于 Agent 行动和用户消息
• Observations：_handle_observation() 用于运行时结果和反馈
• State Changes：基于事件内容自动进行状态转换

来源：openhands/controller/agent_controller.py383-438 openhands/controller/agent_controller.py439-465 openhands/controller/agent_controller.py466-501

多 Agent 委托

Controller 通过委托系统支持分层多 Agent 工作流，在此系统中 Agent 可以生成子 Agent 来处理专门的任务。

多 Agent 委托架构

关键委托机制

• Agent 创建：start_delegate() 创建专门的 Agent Controller
• 事件转发：父 Agent 将事件转发给活动的委托 Agent
• 资源共享：指标和迭代次数在层级结构中共享
• 结果集成：end_delegate() 将委托 Agent 的结果集成回父 Agent

来源：openhands/controller/agent_controller.py669-720 openhands/controller/agent_controller.py721-777 openhands/controller/agent_controller.py389-408

流量控制和资源管理

Controller 通过一个流量控制系统来强制执行资源限制，以防止 Agent 失控。

流量控制状态管理

系统根据执行模式提供不同的行为

• Headless 模式：超出限制时自动进入错误状态
• Interactive 模式：用户可以选择继续使用扩展限制
• Budget Control：跟踪 LLM API 成本并强制执行支出限制
• Iteration Control：通过计数步骤来防止无限循环

来源：openhands/controller/agent_controller.py804-817 openhands/controller/agent_controller.py518-531 openhands/controller/agent_controller.py612-635

错误处理和弹性

Controller 实现了对 LLM 故障、运行时问题和系统异常的全面错误处理。

错误类型	处理器	恢复策略
AuthenticationError	_react_to_exception()	设置 ERROR 状态，通知用户
RateLimitError	_react_to_exception()	设置 RATE_LIMITED 状态，稍后重试
ContextWindowExceededError	_handle_long_context_error()	触发压缩，继续
AgentStuckInLoopError	检测 _is_stuck()	设置 ERROR 状态，停止执行
ContentPolicyViolationError	_react_to_exception()	设置 ERROR 状态，内容被阻止

Controller 还会在重置期间处理待定操作的清理，并为各种故障场景提供优雅降级。

来源：openhands/controller/agent_controller.py267-309 openhands/controller/agent_controller.py559-590 openhands/controller/agent_controller.py819-823

与会话管理集成

AgentController 与更高级别的会话管理组件集成，以提供完整的对话处理。

会话集成架构

集成提供了

• 生命周期管理：AgentSession 创建和销毁 Controller
• 事件路由：会话将 WebSocket 事件路由到 Controller
• 状态报告：Controller 通过回调报告状态
• 状态持久化：Controller 状态在会话之间保存/恢复

来源： openhands/server/session/agent_session.py389-443 openhands/server/session/session.py90-227 openhands/controller/agent_controller.py208-244