OpenHands 软件代理 SDK

Deutsch | Español | français | 日本語 | 한국어 | Português | Русский | 中文

---

OpenHands 软件代理 SDK 是一套用于 构建与代码协作的代理 的 Python 和 REST API。

您可以使用 OpenHands 软件代理 SDK 来完成以下任务：

• 一次性任务，例如为您的仓库生成 README 文件
• 日常维护任务，例如更新依赖项
• 涉及多个代理的重大任务，例如重构和重写

重要的是，代理可以选择将本地机器作为工作空间，也可以在临时工作空间中运行（例如在 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("将当前项目的 3 条事实写入 FACTS.txt 文件。")
conversation.run()
print("完成！")

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

文档

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

https://docs.openhands.dev/sdk

文档包括：

• 入门指南 - 安装和设置
• 架构与核心概念 - 代理、工具、工作空间等
• 指南 - Hello World、自定义工具、MCP、技能等
• API 参考 - 代理服务器 REST API 文档

示例

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

• 独立 SDK (examples/01_standalone_sdk/) - 基本代理使用、自定义工具和技能
• 远程代理服务器 (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 仓库 - 源代码和问题
• 文档 - 完整的文档

引用

@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}, 
}

感谢我们的贡献者

受到以下公司工程师的信赖：

OpenHands Software Agent SDK 快速上手指南

OpenHands Software Agent SDK 是一套用于**构建代码工作智能体（Agents）**的 Python 和 REST API 工具集。它支持从简单的单次任务（如生成 README）到复杂的多智能体重构任务，并支持本地或容器化（Docker/K8s）工作空间。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：Python 3.10 或更高版本
• 依赖项：
  • pip (Python 包管理工具)
  • 有效的 LLM API Key (例如 Anthropic, OpenAI 等)
• 可选：Docker (如果您计划使用临时隔离的工作空间)

安装步骤

推荐使用 pip 进行安装。国内开发者若遇到网络延迟，可配置国内镜像源加速下载。

1. 创建虚拟环境（推荐）

python -m venv openhands-env
source openhands-env/bin/activate  # Windows 用户请使用: openhands-env\Scripts\activate

2. 安装 SDK

标准安装：

pip install openhands-sdk

使用国内镜像源加速安装（推荐）：

pip install openhands-sdk -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装常用工具包

SDK 核心库通常不包含所有具体工具的实现，根据示例代码，您可能需要安装相关的工具包（如文件编辑、终端操作等）：

pip install openhands-tools -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是一个最小化的示例，展示如何初始化一个大语言模型（LLM），配置工具（终端、文件编辑、任务追踪），并让智能体在当前目录下执行写入文件的操作。

代码示例

创建一个名为 hello_agent.py 的文件，并填入以下内容：

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


# 1. 初始化 LLM
# 请确保环境变量中已设置 LLM_API_KEY，或者在此处直接传入
llm = LLM(
    model="anthropic/claude-sonnet-4-5-20250929",
    api_key=os.getenv("LLM_API_KEY"),
)

# 2. 定义智能体及其可用工具
agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

# 3. 创建会话，指定工作空间为当前目录
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

# 4. 发送指令并运行
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()

print("All done!")

运行步骤

1. 设置 API Key：在终端中导出您的 LLM API 密钥。

   export LLM_API_KEY="your_anthropic_or_other_api_key_here"
   

   (Windows PowerShell: $env:LLM_API_KEY="your_key_here")

2. 执行脚本：

   python hello_agent.py
   

智能体将自动分析当前项目，编写三个事实，并将其保存到当前目录下的 FACTS.txt 文件中。

下一步学习：

• 查看完整文档：https://docs.openhands.dev/sdk
• 探索更多示例代码：访问项目根目录下的 examples/ 文件夹。