论文档案

这篇论文的价值不在发明单一算法

OpenHands 把许多已有思想整合为工程平台：CodeAct 的代码动作、SWE-agent 的 ACI、BrowserGym 的浏览器动作、Docker 沙箱、多 Agent 委派和统一评测。论文贡献更接近系统设计与公共基础设施，而不是一个孤立的新推理算法。

截至论文版本，项目有 188 位以上贡献者、2,100 多次贡献，并集成 10 多种 Agent 和 15 个 benchmark。数字会随项目变化；本文只按论文固定版本解释架构。

三层核心架构

Agent / UI
    │ 产生 Action、接收 Observation
    ▼
Event Stream + State
    │ 保存顺序、成本、用户消息、委派关系
    ▼
Runtime
    │ REST action execution API
    ▼
Docker sandbox：Shell + IPython + Chromium/Playwright + Workspace

State 与 Event Stream

State 保存 Agent 执行所需信息，其中核心是按时间排列的 action/observation event stream。它还保存累计模型成本、多 Agent 委派元数据和执行参数。

事件流的意义是解耦：Agent 只要读取 state 并在 step 中返回一个 Action；Runtime 消费 Action、执行后产生 Observation；前端也读取同一事件流展示过程和插入用户反馈。

这比让 Agent 直接调用 Shell 更容易实现回放、UI、成本跟踪和多种 Runtime，但事件流本身仍需事件 schema 版本、幂等与持久化策略。

通用动作集合

OpenHands 选择少量高表达力动作：

• CmdRunAction：在沙箱执行 Bash；
• IPythonRunCellAction：在持久 IPython 会话运行 Python；
• BrowserInteractiveAction：使用 BrowserGym 风格 DSL 操作浏览器；
• 消息类动作：与用户交流；
• AgentDelegateAction：把明确子任务交给另一个 Agent。

这延续 CodeAct 思路：不用为每个任务堆大量窄工具，而是提供接近开发者工作方式的 shell、代码和浏览器接口。

Docker Runtime

每个会话启动隔离容器，容器内部的 REST API 接收动作并返回观察。Runtime 维持：

• 一个有状态 shell；
• 一个 Jupyter/IPython server；
• 一个基于 Playwright 的 Chromium；
• 可挂载的 workspace；
• 对任意用户 Docker image 注入 action execution API 的构建机制。

浏览器观察可包括 HTML、DOM、accessibility tree、截图和 tab。任意镜像支持对 SWE-bench 一类依赖各异的任务尤其重要。

Agent Skills 与 ACI

OpenHands 把面向模型的接口称为 Agent Skills。技能可以提供文件编辑、代码搜索、网页交互等能力及使用说明。默认 CodeActAgent 每步可选择自然语言交流，或执行 Bash、Python、浏览器动作。

“micro agent”则复用通用 Agent 实现，只用专门 prompt 和配置适配任务。这降低扩展门槛，但也提醒我们：技能文本、工具实现和运行权限是三类不同资产，不能只靠 prompt 声称限制能力。

多 Agent 委派

父 Agent 用 AgentDelegateAction 把子任务交给专门 Agent，例如让 BrowsingAgent 完成复杂网页操作，再把结果返回给 CodeActAgent。

委派需要 Harness 管理：

• 子任务描述和可见上下文；
• 子 Agent 的工具权限与预算；
• workspace 是否共享；
• 返回结果结构；
• 取消、超时和异常传播；
• 父子事件的因果关系。

论文证明平台支持委派，但没有证明更多 Agent 一定更好。协调开销、信息丢失和权限扩散都需要单独消融。

统一评测覆盖

OpenHands 接入 15 个 benchmark：

同一个 CodeActAgent 不按 benchmark 手改 system prompt，目的是考察 generalist，而许多对照系统是领域 specialist。因此表中数字更适合判断“一个统一平台能跑到哪里”，不适合简单宣称每个任务都是 SOTA。

代表性结果

跨 benchmark 的模型、Agent 版本和 protocol 不完全相同。论文自己的目标是展示通用性和基础设施复用，不应把这些数字合并成一个“OpenHands 得分”。

为什么 Event Stream 值得单独学习

一个可靠事件至少应包含：

event_id: ...
parent_event_id: ...
actor: user | agent | runtime | evaluator
kind: action | observation | message | policy_decision
payload_schema_version: 2
timestamp: ...
cost: ...
artifact_refs: [...]

事件流提供审计基线，却不自动等于可重放。模型 API 可能漂移，网页和包源会变化，执行还依赖镜像、秘密、网络和随机性。要复现还需记录模型快照、镜像 digest、依赖锁、环境初态和策略版本。

沙箱的正确理解

Docker 显著降低任意代码执行风险，但不能被称为绝对安全边界：挂载的 workspace 可能包含敏感文件，容器可能有网络和凭据，内核漏洞或错误配置仍可造成逃逸。生产部署应叠加：

• rootless/低权限运行；
• 最小挂载与只读目录；
• 默认禁网或域名 allowlist；
• 无长期云凭据；
• CPU、内存、磁盘、进程和时间限额；
• 敏感外部动作走独立工具与审批；
• 会话结束后清理环境。

论文说的 safe sandbox 是工程目标，不是形式化安全证明。

平台工程的隐藏难题

评测回归很贵

论文附录指出，用 GPT-4o 完整跑一次 SWE-bench Lite 约需 600 美元。OpenHands 因此建设分层测试：mock 模型做确定性单测，集成测试覆盖 prompt、消息、动作和沙箱，多平台测试再验证 Linux/Mac、本地/SSH/exec runtime。

这是一条重要经验：不能把昂贵 benchmark 当作每次代码改动的唯一 CI。

通用性会牺牲专项最优

统一 CodeActAgent 在多类任务上有竞争力，但 WebArena 仍落后于专门优化系统。平台需要同时支持稳定通用基线与可插拔 specialist，不能用“一个 Agent 解决所有事”抹平领域差异。

UI 中的人类介入要进入状态机

用户可以观察、打断和补充反馈。中断不是一条普通聊天消息：Harness 要定义暂停时正在运行的动作怎样取消，恢复时环境是否仍一致，审批结果对哪些动作有效。

适合复现的路径

1. 先实现只支持 shell 的最小 Agent，通过 event stream 连接 runtime；
2. 加 IPython，验证会话状态和执行隔离；
3. 加浏览器动作，统一 action/observation schema；
4. 为每类动作写 mock runtime 单测；
5. 选 SWE-bench Lite、MiniWoB++ 和 AgentBench OS 各少量任务做烟测；
6. 记录每项成本、镜像 digest 与所有事件；
7. 最后加入委派，并与相同总预算的单 Agent 做对照。

局限

• 论文是快速演化开源项目的快照，接口与结果可能很快变化；
• 许多评测使用不同模型与 Agent 版本，横向归因有限；
• 平台集成 15 个基准不等于统一了所有环境语义；
• Docker 隔离不是绝对安全，生产权限治理仍需额外设计；
• 多 Agent 支持缺少系统的收益/成本消融；
• 多模态、自动 workflow 优化和更强安全在论文中仍属未来方向；
• generalist 的公平对照很难，specialist 可能使用更多任务特定优化。

OpenHands 的最大贡献，是把 Agent Harness 从论文伪代码推进到完整软件系统：事件流连接策略与执行，沙箱承载真实工具，前端允许人类介入，评测框架保持可比较性。它也同时证明，运行时本身会成为需要测试、版本化和持续维护的大型产品。

延伸阅读

• 返回论文谱系与单篇索引
• CodeAct：通用动作空间的来源
• SWE-agent：ACI 设计原则
• BrowserGym：浏览器环境与实验管理