OpenHands Software Agent SDK Agent Server详解:REST与WebSocket远程调用指南

原创2026-10-13 15:24:082,322 阅读

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
    }
  ]
}

安全清单:

  1. ✅ 生产环境必须启用 session_api_key
  2. ✅ 设置 OH_SECRET_KEY(建议 openssl rand -hex 32 生成),否则机密不会跨重启保留
  3. ✅ 按需配置 allow_cors_origins,localhost 始终被允许
  4. ⚠️ 服务默认绑定 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 变得简单可靠。

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