SDK 与示例

SDK 封装了端点的 REST API：会话生命周期、操作、文件、搜索、问答与用量。源码位于仓库的 cloud/sdk/。

Python

pip install omniscout-cloud  # from cloud/sdk/python

import os, time
from omniscout_cloud.client import OmniScoutCloud

client = OmniScoutCloud(
    api_key=os.environ["OMNISCOUT_API_KEY"],
    base_url=os.environ.get("OMNISCOUT_BASE_URL", "https://api.omniscout.xyz"),
)

created = client.create_session(type="computer")
session_id, secret = created["session_id"], created["session_secret"]

for _ in range(30):
    status = client.get_session(session_id)["status"]
    if status in {"ready", "active"}:
        break
    if status == "failed":
        raise RuntimeError("session failed to provision")
    time.sleep(2)

print(client.run_action(session_id, secret, "terminal.exec", {"command": "echo hello"}))
print(client.run_action(session_id, secret, "computer.screenshot", {"format": "url"}))
print(client.usage())

client.destroy_session(session_id)
client.close()

完整可运行脚本：cloud/examples/python/full_session.py。客户端方法：create_session、get_session、run_action、destroy_session、usage、close。

TypeScript

import { OmniScoutCloud } from "./sdk/typescript/src/client";

const client = new OmniScoutCloud({
  apiKey: process.env.OMNISCOUT_API_KEY!,
  baseUrl: process.env.OMNISCOUT_BASE_URL ?? "https://api.omniscout.xyz",
});

const created = await client.createSession("computer");
const sessionId = created.session_id as string;
const secret = created.session_secret as string;

for (let i = 0; i < 30; i++) {
  const { status } = await client.getSession(sessionId);
  if (status === "ready" || status === "active") break;
  if (status === "failed") throw new Error("session failed");
  await new Promise((r) => setTimeout(r, 2000));
}

await client.runAction(sessionId, secret, "terminal.exec", { command: "echo hello" });
await client.runAction(sessionId, secret, "computer.screenshot", { format: "url" });

await client.destroySession(sessionId);

完整可运行脚本：cloud/examples/typescript/full_session.ts（用 OMNISCOUT_API_KEY=os_live_... bun run cloud/examples/typescript/full_session.ts 运行）。

curl

bash 版完整生命周期 — cloud/examples/curl/session-lifecycle.sh：

export OMNISCOUT_API_KEY=os_live_...
export OMNISCOUT_BASE_URL=https://api.omniscout.xyz
bash cloud/examples/curl/session-lifecycle.sh

它创建会话、轮询到 ready、运行 terminal.exec 并销毁会话。用端点中的任意操作扩展 — 浏览器操作使用裸名（navigate、screenshot），桌面操作使用 computer. 前缀（computer.type、computer.screenshot）。

Sprite 上的文件

截图与 PDF 落在 Sprite 文件系统 — 通过文件路由下载：

# After a screenshot action returns a path:
curl "$OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID/files?path=/tmp/shot.png&format=base64" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET"

# Upload a file, then reference it in an upload action:
curl -X POST "$OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID/files" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -F "file=@./document.pdf"

本地测试

在本地运行平台并将 SDK 指向它：

cd cloud/platform
cp .env.local.example .env.local
bun install
bunx convex dev   # terminal 1
bun dev           # terminal 2 → http://localhost:3001

设置 FLY_SPRITES_MOCK=1 即可在无 Fly API 时测试会话，然后 OMNISCOUT_BASE_URL=http://localhost:3001。