OpenHands Software Agent SDK核心概念全解析:Agent、Tool、Conversation与Workspace四大基石
OpenHands Software Agent SDK核心概念全解析:Agent、Tool、Conversation与Workspace四大基石
想看懂 OpenHands Software Agent SDK?只需掌握 Agent、Tool、Conversation、Workspace 四大核心概念即可。本文带你用最短时间理清这套"AI 智能体 SDK"的设计思路:Agent 是大脑、Tool 是手脚、Conversation 是任务引擎、Workspace 是操作沙箱,四者如何协作完成一个真实编码任务,一文讲透。
30秒速览:OpenHands SDK 是什么?
OpenHands Software Agent SDK 是一个用于构建 AI 编码智能体的模块化 SDK,提供 Python、TypeScript 和 REST 三套 API。官方 README 中给出的定位很清晰:
- 一次性任务:比如为仓库生成 README
- 例行维护:比如更新依赖
- 大型多智能体任务:比如重构、重写代码
它既能驱动本地代码库,也能通过 Agent Server 把智能体放进 Docker、Kubernetes 等临时沙箱里跑——它正是 OpenHands CLI 和 OpenHands Cloud 背后的引擎。
四大基石一图流(概念地图):
| 概念 | 角色比喻 | 源码位置 |
|---|---|---|
| Agent | 大脑:LLM + 工具集 + 系统提示词 | agent/agent.py |
| Tool | 手脚:执行具体动作的能力单元 | tool/tool.py |
| Conversation | 引擎:驱动"发消息→推理→执行"的闭环 | conversation/conversation.py |
| Workspace | 沙箱:Agent 实际操作的目录/容器 | workspace/workspace.py |
基石一:Agent——AI 智能体的"大脑"
Agent 是 SDK 中最核心的配置对象,它本质上是一份不可变的配置:绑定一个 LLM、一组 Tool,以及系统提示词。你可以把它理解为"人格 + 能力清单 + 工作指令"的打包。
Agent 的关键字段(定义于 agent/base.py 的 AgentBase):
llm:语言模型配置(模型名、API Key、base_url)tools:交给智能体使用的工具列表mcp_config:可选的 MCP 服务器,自动暴露为工具agent_context:附加技能(Skills)、系统消息后缀等上下文persona:替换默认"人格"的文本,改变智能体的说话风格和行为倾向
几个值得注意的设计:
- 无状态(Stateless):Agent 本身不保存运行状态,完全由配置定义,可以放心复用和序列化。
- 默认自带工具:每个 Agent 默认附带
FinishTool(声明任务完成)和ThinkTool(内部思考),见 tool/builtins/__init__.py。 - 系统提示词可定制:可以整体替换,也可以只换 persona 部分,安全策略和模型适配指导仍然保留。
💡 一个记忆点:Agent ≠ 会自己"跑起来"的东西。它必须被放进 Conversation 里才会工作。
基石二:Tool——让智能体真正动手的"手脚"
LLM 只会输出文字,Tool 把这些文字变成真实世界的操作。SDK 中所有工具都继承自 ToolDefinition(ToolDefinition),核心设计是"动作-观察"对:
- Action:智能体要执行的动作(含输入参数的 JSON Schema)
- Observation:执行后返回的观察结果,会反馈给 LLM 继续推理
- Executor:真正执行逻辑的代码,运行在 Workspace 中
工具生态分两层:
- SDK 内置工具(不依赖环境):
FinishTool、ThinkTool、SwitchLLMTool、InvokeSkillTool等,注册表见 BUILT_IN_TOOL_CLASSES - 环境交互工具(独立
openhands-tools包):TerminalTool(执行命令)、FileEditorTool(编辑文件)、TaskTrackerTool(任务清单)、BrowserUseTool(浏览器操作)等,入口在 openhands-tools/openhands/tools/__init__.py
工具命名会自动从类名生成(如 TerminalTool → terminal),使用时只需 Tool(name="terminal") 一行即可挂载。工具还支持并行执行(由 ParallelToolExecutor 管理并发上限),这也是提升智能体效率的关键设计。
🛠️ 想扩展能力?除了自己写工具类,还可以接入任意 MCP 服务器,用
mcp_config一行配置把外部工具"借"进来。
基石三:Conversation——驱动任务闭环的"引擎"
如果说 Agent 是配置、Tool 是能力,那 Conversation 就是让它们运转起来的执行引擎。它在 conversation/conversation.py 中以工厂形式提供:
- 传本地路径 → 自动创建
LocalConversation(本机执行) - 传远程 Workspace → 自动创建
RemoteConversation(连接 Agent Server 执行)
一次典型的交互循环长这样:
用户消息 → Agent 推理(LLM 调用)→ 发出 Action(工具调用)
→ Tool 在 Workspace 执行 → 返回 Observation
→ 继续推理 … → FinishTool 宣告完成
Conversation 还负责这些"运维级"细节:
- 事件流(Event Stream):每次 LLM 调用、每次工具执行都是一条 Event,可回放、可持久化(事件溯源)
- 卡死检测(stuck detection):自动识别智能体原地打转
- 确认策略(confirmation policy):高风险操作可要求用户确认
- 安全分析器:对危险命令做静态分析 + LLM 风险评估
- Hooks 与回调:在关键节点插入自定义逻辑
对应的实现类在 conversation/impl/local_conversation.py 与 remote_conversation.py。
基石四:Workspace——智能体操作的世界
Workspace 定义了 Agent 在哪里干活。它是一组抽象接口:执行命令(execute_command)、上传/下载文件、读取 Git 变更与 diff,全部定义在 workspace/base.py 的 BaseWorkspace 中。
工厂类 Workspace 让你用一行代码切换执行环境:
Workspace(working_dir=...)→LocalWorkspace:直接在你本机的目录上操作Workspace(working_dir=..., host="http://...")→RemoteWorkspace:操作远端 Agent Server 的容器环境
远端沙箱的具体实现由独立的 openhands-workspace 包提供,支持多种底座(见 openhands-workspace/openhands/workspace/):
- Docker:本地 Docker 容器沙箱
- Apptainer:面向 HPC 环境的容器方案
- Agent Sandbox:基于 Kubernetes 的弹性沙箱池
- Cloud:托管云工作区
容器类 Workspace 还支持 pause()/resume() 暂停与恢复——长时间任务中途挂起、省资源、随时续上。
四大基石如何协作:Hello World 全流程
把四个概念串起来,就是 examples/01_standalone_sdk/01_hello_world.py 的完整流程:
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.terminal import TerminalTool
# 1. 大脑:LLM 配置
llm = LLM(model="gpt-5.5", api_key=os.getenv("LLM_API_KEY"))
# 2. 手脚:挂载终端和文件编辑工具
agent = Agent(
llm=llm,
tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)],
)
# 3. 引擎 + 沙箱:以当前目录为工作区
conversation = Conversation(agent=agent, workspace=os.getcwd())
# 4. 启动闭环
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
四行核心代码背后的分工一目了然:Conversation 建立事件循环 → Agent 根据消息选择 Tool → Tool 在 Workspace 中执行 → 结果回流推理,直到 FinishTool 收尾。
🎯 新手建议:先用
workspace=os.getcwd()在本地跑通,再换RemoteWorkspace体验沙箱,成本最低。
上手路线:从示例到实战
仓库的 examples/ 目录是最好的学习路径,按场景组织:
- 01_standalone_sdk:独立 SDK 用法——自定义工具、确认模式、LLM 路由、持久化等 50+ 示例,从 01_hello_world.py 开始
- 02_remote_agent_server:客户端-服务端架构、Docker 沙箱、WebSocket 连接
- 03_github_workflows:CI/CD 集成与自动化工作流
- 05_skills_and_plugins:AgentSkills、插件与 Marketplace
克隆仓库动手实践:
git clone https://gitcode.com/gh_mirrors/so/software-agent-sdk
cd software-agent-sdk
make build
总结:一张表记住四大基石
| 概念 | 一句话定义 | 关键问题 |
|---|---|---|
| Agent | LLM + 工具 + 提示词的不可变配置 | "它是谁,会做什么" |
| Tool | Action/Observation 结构的能力单元 | "它能怎么动手" |
| Conversation | 事件驱动的任务执行引擎 | "任务如何一步步跑完" |
| Workspace | 本地或沙箱中的操作环境 | "在哪里动手" |
理解了这四者的关系,你就掌握了 OpenHands Software Agent SDK 的骨架。剩下的 Skills、Plugins、Hooks、Security Policy 等特性,都是在这四根支柱上的扩展。下一步,不妨打开 examples/01_standalone_sdk/02_custom_tools.py 写一个自己的第一个自定义工具——动手一次,胜过看十遍文档。