SDK и примеры

SDK оборачивают REST API из Endpoints: жизненный цикл сессий, действия, файлы, поиск, ответы и использование. Исходники живут в 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

Он создаёт сессию, ждёт готовности, выполняет terminal.exec и уничтожает сессию. Расширьте его любым действием из Endpoints — действия браузера используют голые имена (navigate, screenshot), действия computer — префикс 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.