OpenHands Software Agent SDK核心概念全解析:Agent、Tool、Conversation与Workspace四大基石

原创2026-10-13 09:02:351,754 阅读

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:替换默认"人格"的文本,改变智能体的说话风格和行为倾向

几个值得注意的设计:

  1. 无状态(Stateless):Agent 本身不保存运行状态,完全由配置定义,可以放心复用和序列化。
  2. 默认自带工具:每个 Agent 默认附带 FinishTool(声明任务完成)和 ThinkTool(内部思考),见 tool/builtins/__init__.py。
  3. 系统提示词可定制:可以整体替换,也可以只换 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 写一个自己的第一个自定义工具——动手一次,胜过看十遍文档。

登录后查看全文
software-agent-sdk