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. prefix(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을 쓰세요.