OpenHands Software Agent SDK

OpenHands Software Agent SDK 是一套用于**构建代码交互智能体（Agents）**的 Python 和 REST API 工具集。

你可以使用 OpenHands Software Agent SDK 来处理：

• 一次性任务，例如为你的代码仓库编写 README
• 日常维护任务，例如更新依赖项
• 涉及多个智能体的复杂任务，例如代码重构与重写

值得注意的是，智能体既可以使用本地机器作为工作空间，也可以通过 Agent Server 在临时工作空间（如 Docker 或 Kubernetes）中运行。

你甚至可以使用该 SDK 构建全新的开发者体验：它是 OpenHands CLI 和 OpenHands Cloud 背后的核心引擎。

请查看 示例项目 或 阅读文档 以了解更多信息。

快速入门

使用 SDK 构建智能体的代码示例如下：

import os

from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool


llm = LLM(
    model="anthropic/claude-sonnet-4-5-20250929",
    api_key=os.getenv("LLM_API_KEY"),
)

agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")

有关安装说明和详细设置，请参阅 入门指南。

文档

如需详细的文档、教程和 API 参考，请访问：

https://docs.openhands.dev/sdk

文档内容包括：

• 入门指南 - 安装与设置
• 架构与核心概念 - 智能体、工具、工作空间等
• 指南 - Hello World、自定义工具、MCP、技能等
• API 参考 - Agent Server REST API 文档

示例

examples/ 目录下包含了全面的使用示例：

• 独立 SDK (examples/01_standalone_sdk/) - 基础智能体用法、自定义工具和技能
• 远程 Agent Server (examples/02_remote_agent_server/) - 客户端-服务器架构与 WebSocket 连接
• GitHub 工作流 (examples/03_github_workflows/) - CI/CD 集成与自动化工作流

现代包管理工具的技能支持

如果你通过 AgentContext(load_public_skills=True) 启用了公共技能，默认的 OpenHands/extensions 市场将包含例如 uv 和 deno 的技能。智能体可以自动识别并获取项目中使用的包管理指南，例如匹配 uv.lock、deno.json、deno.jsonc 或 deno.lock 等文件。

请参阅 examples/01_standalone_sdk/03_activate_skill.py 获取启用公共技能加载的最小示例。

贡献

有关开发环境设置、测试和贡献指南，请参阅 DEVELOPMENT.md。

社区

• 加入 Slack - 与 OpenHands 社区互动
• GitHub 仓库 - 源代码与 Issue 反馈
• 文档 - 完整文档

引用

@misc{wang2025openhandssoftwareagentsdk,
      title={The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents}, 
      author={Xingyao Wang and Simon Rosenberg and Juan Michelini and Calvin Smith and Hoang Tran and Engel Nyst and Rohit Malhotra and Xuhui Zhou and Valerie Chen and Robert Brennan and Graham Neubig},
      year={2025},
      eprint={2511.03690},
      archivePrefix={arXiv},
      primaryClass={cs.SE},
      url={https://arxiv.org/abs/2511.03690}, 
}