From 783ea1086ac3fced11d6f6ec77ea2e6b7a05f600 Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Thu, 12 Feb 2026 15:11:17 -0800 Subject: [PATCH] chore: remove old sdk docs --- docs/sdks/python.mdx | 41 ------ docs/sdks/typescript.mdx | 267 --------------------------------------- 2 files changed, 308 deletions(-) delete mode 100644 docs/sdks/python.mdx delete mode 100644 docs/sdks/typescript.mdx diff --git a/docs/sdks/python.mdx b/docs/sdks/python.mdx deleted file mode 100644 index 80f667a..0000000 --- a/docs/sdks/python.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Python" -description: "Python client for managing sessions and streaming events." -icon: "python" -tag: "Coming Soon" ---- - -The Python SDK is on our roadmap. It will provide a typed client for managing sessions and streaming events, similar to the TypeScript SDK. - -In the meantime, you can use the [HTTP API](/http-api) directly with any HTTP client like `requests` or `httpx`. - -```python -import httpx - -base_url = "http://127.0.0.1:2468" -headers = {"Authorization": f"Bearer {token}"} - -# Create a session -httpx.post( - f"{base_url}/v1/sessions/my-session", - headers=headers, - json={"agent": "claude", "permissionMode": "default"} -) - -# Send a message -httpx.post( - f"{base_url}/v1/sessions/my-session/messages", - headers=headers, - json={"message": "Hello from Python"} -) - -# Get events -response = httpx.get( - f"{base_url}/v1/sessions/my-session/events", - headers=headers, - params={"offset": 0, "limit": 50} -) -events = response.json()["events"] -``` - -Want the Python SDK sooner? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues) to let us know. diff --git a/docs/sdks/typescript.mdx b/docs/sdks/typescript.mdx deleted file mode 100644 index dccc773..0000000 --- a/docs/sdks/typescript.mdx +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: "TypeScript" -description: "Use the TypeScript SDK to manage ACP sessions and Sandbox Agent HTTP APIs." -icon: "js" ---- - -The TypeScript SDK is centered on `sandbox-agent` and its `SandboxAgentClient`, which provides a Sandbox-facing API for session flows, ACP extensions, and binary HTTP filesystem helpers. - -## Install - - - - ```bash - npm install sandbox-agent - ``` - - - ```bash - bun add sandbox-agent - # Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()). - bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64 - ``` - - - -## Create a client - -```ts -import { SandboxAgentClient } from "sandbox-agent"; - -const client = new SandboxAgentClient({ - baseUrl: "http://127.0.0.1:2468", - token: process.env.SANDBOX_TOKEN, - agent: "mock", -}); -``` - -`SandboxAgentClient` is the canonical API. By default it auto-connects (`autoConnect: true`), so provide `agent` in the constructor. Use the instance method `client.connect()` only when you explicitly set `autoConnect: false`. - -## Autospawn (Node only) - -If you run locally, the SDK can launch the server for you. - -```ts -import { SandboxAgent } from "sandbox-agent"; - -const client = await SandboxAgent.start({ - agent: "mock", -}); - -await client.dispose(); -``` - -Autospawn uses the local `sandbox-agent` binary. Install `@sandbox-agent/cli` (recommended) or set -`SANDBOX_AGENT_BIN` to a custom path. - -## Connect lifecycle - -Use manual mode when you want explicit ACP session lifecycle control. - -```ts -import { - AlreadyConnectedError, - NotConnectedError, - SandboxAgentClient, -} from "sandbox-agent"; - -const client = new SandboxAgentClient({ - baseUrl: "http://127.0.0.1:2468", - token: process.env.SANDBOX_TOKEN, - agent: "mock", - autoConnect: false, -}); - -await client.connect(); - -try { - await client.connect(); -} catch (error) { - if (error instanceof AlreadyConnectedError) { - console.error("already connected"); - } -} - -await client.disconnect(); - -try { - await client.prompt({ sessionId: "s", prompt: [{ type: "text", text: "hi" }] }); -} catch (error) { - if (error instanceof NotConnectedError) { - console.error("connect first"); - } -} -``` - -## Session flow - -```ts -const session = await client.newSession({ - cwd: "/", - mcpServers: [], - metadata: { - agent: "mock", - title: "Demo Session", - variant: "high", - permissionMode: "ask", - }, -}); - -const result = await client.prompt({ - sessionId: session.sessionId, - prompt: [{ type: "text", text: "Summarize this repository." }], -}); - -console.log(result.stopReason); -``` - -Load, cancel, and runtime settings use ACP-aligned method names: - -```ts -await client.loadSession({ sessionId: session.sessionId, cwd: "/", mcpServers: [] }); -await client.cancel({ sessionId: session.sessionId }); -await client.setSessionMode({ sessionId: session.sessionId, modeId: "default" }); -await client.setSessionConfigOption({ - sessionId: session.sessionId, - configId: "config-id-from-session", - value: "config-value-id", -}); -``` - -## Extension helpers - -Sandbox extensions are exposed as first-class methods: - -```ts -const models = await client.listModels({ sessionId: session.sessionId }); -console.log(models.currentModelId, models.availableModels.length); - -await client.setMetadata(session.sessionId, { - title: "Renamed Session", - model: "mock", - permissionMode: "ask", -}); - -await client.detachSession(session.sessionId); -await client.terminateSession(session.sessionId); -``` - -## Event handling - -Use `onEvent` to consume converted SDK events. - -```ts -import { SandboxAgentClient, type AgentEvent } from "sandbox-agent"; - -const events: AgentEvent[] = []; - -const client = new SandboxAgentClient({ - baseUrl: "http://127.0.0.1:2468", - token: process.env.SANDBOX_TOKEN, - agent: "mock", - onEvent: (event) => { - events.push(event); - - if (event.type === "sessionEnded") { - console.log("ended", event.notification.params.sessionId ?? event.notification.params.session_id); - } - - if (event.type === "agentUnparsed") { - console.warn("unparsed", event.notification.params); - } - }, -}); -``` - -You can also handle raw session update notifications directly: - -```ts -const client = new SandboxAgentClient({ - baseUrl: "http://127.0.0.1:2468", - token: process.env.SANDBOX_TOKEN, - agent: "mock", - onSessionUpdate: (notification) => { - console.log(notification.update.sessionUpdate); - }, -}); -``` - -## Control + HTTP helpers - -Agent/session and non-binary filesystem control helpers use ACP extension methods over `/v2/rpc`: - -```ts -const health = await client.getHealth(); -const agents = await client.listAgents(); -await client.installAgent("codex", { reinstall: true }); - -const sessions = await client.listSessions(); -const sessionInfo = await client.getSession(sessions.sessions[0].session_id); -``` - -These methods require an active ACP connection and throw `NotConnectedError` when disconnected. - -Binary filesystem transfer intentionally remains HTTP: - -- `readFsFile` -> `GET /v2/fs/file` -- `writeFsFile` -> `PUT /v2/fs/file` -- `uploadFsBatch` -> `POST /v2/fs/upload-batch` - -Reason: these are Sandbox Agent host/runtime filesystem operations (not agent-specific ACP behavior), intentionally separate from ACP native `fs/read_text_file` / `fs/write_text_file`, and they may require streaming very large binary payloads that ACP JSON-RPC is not suited to transport efficiently. - -ACP extension variants can exist in parallel for compatibility, but `SandboxAgentClient` should prefer the HTTP endpoints above by default. - -## Error handling - -All HTTP errors throw `SandboxAgentError`: - -```ts -import { SandboxAgentError } from "sandbox-agent"; - -try { - await client.listAgents(); -} catch (error) { - if (error instanceof SandboxAgentError) { - console.error(error.status, error.problem); - } -} -``` - -## Inspector URL - -Build a URL to open the sandbox-agent Inspector UI with pre-filled connection settings: - -```ts -import { buildInspectorUrl } from "sandbox-agent"; - -const url = buildInspectorUrl({ - baseUrl: "https://your-sandbox-agent.example.com", - token: "optional-bearer-token", - headers: { "X-Custom-Header": "value" }, -}); - -console.log(url); -// https://your-sandbox-agent.example.com/ui/?token=...&headers=... -``` - -Parameters: -- `baseUrl` (required): The sandbox-agent server URL -- `token` (optional): Bearer token for authentication -- `headers` (optional): Extra headers to pass to the server (JSON-encoded in the URL) - -## Types - -The SDK exports typed events and responses for the Sandbox layer: - -```ts -import type { - AgentEvent, - AgentInfo, - HealthResponse, - SessionInfo, - SessionListResponse, - SessionTerminateResponse, -} from "sandbox-agent"; -``` - -For low-level protocol transport details, see [ACP HTTP Client](/advanced/acp-http-client).