OpenHands Software Agent SDK Agent Server详解:REST与WebSocket远程调用指南
OpenHands Software Agent SDK Agent Server详解:REST与WebSocket远程调用指南
OpenHands Software Agent SDK 的 Agent Server 是官方提供的远程执行服务,基于 FastAPI 构建,通过 REST API 和 WebSocket 两种协议与 AI Agent 交互。它把会话、事件和工作区文件存储在本地文件系统,天然适合开发调试与轻量部署,是远程调用 OpenHands Agent 的完整方案。本文将带你快速掌握 Agent Server 的启动方法、REST 端点、WebSocket 实时事件流和官方客户端用法。
一、Agent Server 是什么?
Agent Server 位于 openhands-agent-server/ 目录,是 SDK 生态中负责"托管运行 Agent"的服务端组件。它的核心能力包括:
- REST API:对会话(Conversation)和事件(Event)的完整增删改查
- WebSocket 支持:与 Agent 的实时双向通信
- 本地存储:以文件形式存储会话、事件和工作区数据
- 认证与 CORS:可选的 API Key 认证和跨域配置
- Webhooks:可配置的事件通知推送
服务端入口在 api.py,它把所有路由模块统一挂载到 /api 前缀下,包括会话路由 conversation_router.py、事件路由 event_router.py 和 WebSocket 路由 sockets.py。
会话数据会按如下结构落盘,方便排查与备份:
workspace/
├── openhands_agent_server_config.json # 配置文件
├── conversations/ # 会话存储
│ └── {conversation_id}/
│ ├── metadata.json # 会话元数据
│ └── events.jsonl # 事件日志
└── project/ # Agent 工作区
二、一键启动:如何运行 Agent Server
启动前先用 make build 构建项目并安装依赖,然后一条命令即可启动:
# 默认监听 0.0.0.0:8000
uv run python -m openhands.agent_server
# 自定义地址与端口
uv run python -m openhands.agent_server --host localhost --port 3000
# 开发模式:代码变更自动重载
uv run python -m openhands.agent_server --reload
启动后,访问 http://localhost:8000/docs 即可打开交互式 OpenAPI 文档,所有端点、请求/响应结构都能直接在浏览器里测试。
服务端行为通过环境变量或 JSON 配置文件控制(详见 config.py),最常用的几项:
| 变量 | 作用 | 默认值 |
|---|---|---|
OPENHANDS_AGENT_SERVER_CONFIG_PATH |
JSON 配置文件路径 | workspace/openhands_agent_server_config.json |
SESSION_API_KEY |
认证用 API Key(可选) | 无 |
OH_SECRET_KEY |
加密持久化密钥,重启后保留 LLM API Key 必配 | 无 |
OH_ALLOW_CORS_ORIGIN_REGEX |
额外允许的 CORS 来源正则 | 无 |
💡 生产环境务必设置
OH_SECRET_KEY,否则 LLM API Key 等机密在服务器重启后会丢失(详见 README.md)。
三、REST API 远程调用核心端点
所有 REST 端点统一挂在 /api 前缀下。若配置了 session_api_key,请求需携带 Authorization: Bearer <key> 头(认证逻辑见 dependencies.py)。
会话管理(Conversations)
| 端点 | 方法 | 说明 |
|---|---|---|
/api/conversations |
POST | 创建并启动新会话 |
/api/conversations/search |
GET | 搜索/列出会话 |
/api/conversations/count |
GET | 统计会话数量 |
/api/conversations/{id} |
GET / DELETE | 获取详情 / 删除会话 |
/api/conversations/{id}/pause |
POST | 暂停会话(可恢复) |
/api/conversations/{id}/interrupt |
POST | 立即中断运行中的会话 |
事件读写(Events)
| 端点 | 方法 | 说明 |
|---|---|---|
/api/conversations/{id}/events |
GET | 批量获取会话事件 |
/api/conversations/{id}/events/search |
GET | 按 kind、source、时间范围过滤事件 |
/api/conversations/{id}/events/{event_id} |
GET | 获取单个事件 |
/api/conversations/{id}/events |
POST | 发送消息给 Agent |
/api/conversations/{id}/events/respond_to_confirmation |
POST | 响应用户确认请求 |
⚠️ 事件响应使用可扩展的判别联合(discriminated union)。自建客户端时,请对未知的
kind变体做跳过处理,而不是假定当前集合是完整的,这样才能向前兼容未来新增的事件类型。
一次最简的远程调用流程(先建会话、再发消息、最后轮询事件):
curl -X POST http://localhost:8000/api/conversations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{...创建会话参数...}'
curl -X POST http://localhost:8000/api/conversations/<id>/events \
-H "Content-Type: application/json" \
-d '{"message": "帮我写一个 hello world 脚本"}'
更多端点(文件、Git、Bash、LLM、MCP、Skills 等)可直接在 /docs 页面中探索。
四、WebSocket 实时事件流
轮询 REST 接口虽然简单,但延迟高。WebSocket 端点(定义于 sockets.py)能让你实时接收 Agent 的每一步事件:
| 端点 | 用途 |
|---|---|
/api/sockets/events/{conversation_id} |
订阅指定会话的实时事件流 |
/api/sockets/bash-events |
订阅 Bash 终端事件 |
认证方式:请求头 X-Session-API-Key,或查询参数 ?session_api_key=<key>(WebSocket 无法自定义请求头时可用,见 session_socket.py)。认证失败会收到 4001 关闭码。
浏览器端接入示例:
const ws = new WebSocket(
'ws://localhost:8000/api/sockets/events/<conversation_id>?session_api_key=<key>'
);
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received event:', data);
};
前端连接实现可参考 TypeScript 客户端的 conversation-event-stream.ts。
五、官方客户端:简化远程调用
手搓 HTTP 请求容易出错,官方提供了两套客户端库,覆盖 90% 的场景。
Python SDK:RemoteConversation
Python 侧通过 RemoteConversation + Workspace 即可把本地代码无缝指向远程服务器:
from openhands.sdk import LLM, Conversation, Workspace
workspace = Workspace(host="http://localhost:8000", working_dir="/path/to/dir")
conversation = Conversation(agent=agent, workspace=workspace)
conversation.send_message("创建一个 hello.py 文件")
conversation.run()
完整示例见 examples/02_remote_agent_server/01_convo_with_local_agent_server.py,同目录还有 Docker 沙箱(02)、API 沙箱(04)、云工作区(07)等多种部署形态的实战代码。
TypeScript 客户端:浏览器友好
clients/typescript/ 提供 npm 包 @openhands/typescript-client,完全兼容浏览器、无 Node.js 依赖,文件操作使用 Blob、FormData 等原生 API,非常适合 React 等 Web 应用直接嵌入 Agent 对话界面。包内按领域拆分为 conversation-client.ts、bash-client.ts、file-client.ts 等模块,且会对照 Agent Server 的 OpenAPI 契约做静态校验,保证前后端类型一致。
六、配置与安全最佳实践
通过 JSON 配置文件(路径由 OPENHANDS_AGENT_SERVER_CONFIG_PATH 指定)可以更精细地控制服务端:
{
"session_api_key": "your-secret-api-key",
"allow_cors_origins": ["https://your-frontend.com"],
"conversations_path": "workspace/conversations",
"webhooks": [
{
"webhook_url": "https://your-webhook-endpoint.com/events",
"method": "POST",
"num_retries": 3,
"retry_delay": 5
}
]
}
安全清单:
- ✅ 生产环境必须启用
session_api_key - ✅ 设置
OH_SECRET_KEY(建议openssl rand -hex 32生成),否则机密不会跨重启保留 - ✅ 按需配置
allow_cors_origins,localhost 始终被允许 - ⚠️ 服务默认绑定
0.0.0.0,公网暴露前务必限制访问来源
七、REST 与 WebSocket 如何选择?
| 场景 | 推荐方案 |
|---|---|
| 创建/删除会话、查询历史事件、发送指令 | REST API(幂等、简单、易调试) |
| 实时展示 Agent 输出、工具调用过程 | WebSocket 事件流 |
| 长任务进度监控、中断/暂停控制 | REST 控制 + WebSocket 感知结合 |
| 第三方系统集成、CI 自动化 | REST + Webhooks 通知 |
最佳实践:用 REST 完成"命令"类操作,用 WebSocket 承担"感知"类需求,两者互补。
八、常见问题排查
- 端口被占用:用
--port更换端口 - 权限被拒绝:确认运行用户对
workspace/目录有写权限 - 找不到配置文件:检查
OPENHANDS_AGENT_SERVER_CONFIG_PATH环境变量 - CORS 报错:把前端域名加入
allow_cors_origins - 重启后 LLM API Key 变 None:未设置
OH_SECRET_KEY或换过密钥,旧密钥加密的数据无法解密
更多排错信息见 README.md 的 Troubleshooting 章节,服务端测试套件位于 tests/agent_server/ 可作行为参考。
下一步:从 examples/02_remote_agent_server/ 目录挑一个示例跑起来,再结合 /docs 的 OpenAPI 页面,你就掌握了 OpenHands Agent Server 全部核心能力——无论是本地开发还是容器化部署,REST 与 WebSocket 双通道都能让远程调用 AI Agent 变得简单可靠。