name: openhands-api description: 使用OpenHands REST API (V0) 以编程方式创建和管理代理对话。包含scripts/下的最小Python和TypeScript客户端。 triggers:

openhands-api-v0
openhands-cloud-v0
oh-cloud-v0

此技能提供了一个最小化、易于复制的OpenHands API客户端，用于启动和监控对话。

它故意设计得小而专注：

默认使用OpenHands Cloud (https://app.all-hands.dev)。
针对在OpenHands/OpenHands下openhands/server/routes/中实现的遗留V0 REST API路由。
仅实现少数核心端点，以便AI代理能快速适应/扩展它。

快速开始 (Python)

from scripts.openhands_api import OpenHandsAPI

api = OpenHandsAPI(api_key="...")  # 或设置OPENHANDS_API_KEY

conv = api.create_conversation(
    initial_user_msg="请审计此仓库的脆弱测试并打开一个PR修复它们。",
    repository="owner/repo",
    selected_branch="main",
)
conversation_id = conv["conversation_id"]

final = api.poll_until_terminal(conversation_id, timeout_s=1800, poll_interval_s=30)
print(final["status"], final.get("url"))

快速开始 (TypeScript)

import { OpenHandsAPI } from "./scripts/openhands_api";

const api = new OpenHandsAPI({ apiKey: process.env.OPENHANDS_API_KEY! });

const conv = await api.createConversation({
  initialUserMsg: "运行依赖升级并打开一个PR。",
  repository: "owner/repo",
  selectedBranch: "main",
});

const final = await api.pollUntilTerminal(conv.conversation_id, {
  timeoutMs: 30 * 60_000,
  pollIntervalMs: 30_000,
});

console.log(final.status, final.url);

示例 (基于enyst/playground#105建模)

以下示例展示了一个简单的自动化模式：

使用提示模板启动对话
打印对话URL供人类查看
可选地轮询直到完成

export OPENHANDS_API_KEY="..."
python skills/openhands_api/scripts/openhands_api.py \
  new-conversation \
  --prompt-file skills/openhands_api/references/example_prompt.md \
  --repo owner/repo \
  --branch main \
  --poll

AI代理扩展此客户端的注意事项

服务器期望Bearer令牌 (Authorization: Bearer <OPENHANDS_API_KEY>)。
最重要的端点是 POST /api/conversations。
如果需要流式传输/日志，V0服务器暴露 GET /api/conversations/{conversation_id}/events。
如果需要一次性获取完整事件历史，使用 GET /api/conversations/{conversation_id}/trajectory。

另见：

skills/openhands_api/references/README.md (API文档指针)
skills/openhands_api/scripts/openhands_api.py 和 skills/openhands_api/scripts/openhands_api.ts