SDKと実例

OmniScout Cloud向けPython・TypeScript SDKとcurlについて説明します。

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 APIなしでセッションをテストするにはFLY_SPRITES_MOCK=1を設定し、OMNISCOUT_BASE_URL=http://localhost:3001とします。