OpenHands Software Agent SDK：OpenHands V1 底层那套事件溯源、从本机到远端的基础架构
— 次浏览
一套干净、模块化的 Python/REST SDK，用来构建代码 agent — 它是 OpenHands V1、CLI 与 OpenHands Cloud 背后的引擎。事件溯源状态、本机优先并可按需开沙箱、MCP 工具。v1.26.0 于 2026 年 6 月 5 日推出。
pip install -U openhands-sdk openhands-tools它是什么
OpenHands Software Agent SDK 是一组 Python 与 REST API，用来构建处理代码的 agent。它是 OpenHands V1 的核心 — 一次彻底的重新设计，把 agent 核心与构建在其上的应用程序拆开（OpenHands CLI 与 OpenHands Cloud 都跑在这套 SDK 上）。此 repo 采用 MIT 许可，迭代很快：最新的 tag v1.26.0 在 2026 年 6 月 5 日落地，紧接在 v1.25.0（6 月 4 日）与 v1.24.0（5 月 27 日）之后。
它的卖点是：同一份 agent 定义应该能在你的笔记本上做原型开发，也能在生产环境的容器化沙箱里运行，几乎不需要改动代码。你组合一个 LLM、一份带类型的 Tool 列表，以及一个绑定到工作区的 Conversation，然后用消息来驱动它。
为什么这套架构值得关注
随附的论文（arXiv 2511.03690，同时是 MLSys 2026 口头报告）提出四项设计原则，就算你永远不采用这套 SDK，也值得借鉴：
- 可选的隔离 — 本机优先、按需开沙箱。只有在你真的需要隔离时，才付出 Docker/Kubernetes 的代价。
- 无状态组件，搭配不可变配置与事件溯源状态，让你能对一次运行做确定性重放。
- agent 核心与消费它的应用程序之间严格分离。
- 跨四个软件包 — SDK、Tools、Workspace、Server — 的双层可组合性，组件带类型、可替换，并集成 MCP。
事件溯源加上不可变配置，是低调的重点。如果每一次状态转换都是一笔追加的事件，你就能确定性地重放一次失败的 agent 运行，而不必试着从日志重现一个非确定性的循环。
安装与运行
pip install -U openhands-sdk openhands-tools文档明确指出 openhands-sdk 与 openhands-tools 是一组搭配软件包 — 用一条命令一起安装并升级，让版本保持对齐。若要使用沙箱化的工作区与随附的服务器，再加上 openhands-workspace openhands-agent-server。
| 软件包 | 角色 |
|---|---|
| openhands-sdk | 核心 agent/conversation/LLM API |
| openhands-tools | 内置的终端、文件编辑器、任务追踪工具 |
| openhands-workspace | Docker / 远端沙箱化工作区 |
| openhands-agent-server | REST/WebSocket agent 服务器 |
一次极简的运行会把终端、文件编辑器与任务追踪器接进同一个 agent，把它指向当前目录，然后发出一条指令 — agent 自行规划、调用工具，并自己停下来。
实践者笔记
把这四个软件包的拆分当成真正的产品，而不是样板。先只用 openhands-sdk + openhands-tools 对着本机工作区去感受那个循环，等到你需要在隔离环境里运行不受信任的编辑时，再去动用 openhands-workspace。因为工具带类型、可替换并支持 MCP，你可以塞进自己的工具而不必 fork 核心 — 这正是「一个你拿来扩展的库」与「一个你拿来对抗的框架」之间的差别。
被低估的角度
大多数「agent SDK」的报道都紧盯它调用哪个模型。这里更耐久的赌注是事件溯源的状态模型：确定性重放把不稳定的 agent 运行，变成可以 diff、审计并做回归测试的可重现产物。这把 agent 从一段聊天会话，重新框定成更接近一条构建流水线的东西 — 而这正是团队在敢于信任它去重构真正的代码之前所需要的。