mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 03:00:48 +00:00
118 lines
2.5 KiB
Text
118 lines
2.5 KiB
Text
---
|
|
title: "TypeScript SDK"
|
|
description: "Use the generated client to manage sessions and stream events."
|
|
---
|
|
|
|
The TypeScript SDK is generated from the OpenAPI spec that ships with the server. It provides a typed
|
|
client for sessions, events, and agent operations.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install sandbox-agent
|
|
```
|
|
|
|
## Create a client
|
|
|
|
```ts
|
|
import { SandboxAgent } from "sandbox-agent";
|
|
|
|
const client = await SandboxAgent.connect({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
token: process.env.SANDBOX_TOKEN,
|
|
});
|
|
```
|
|
|
|
## 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();
|
|
|
|
await client.dispose();
|
|
```
|
|
|
|
Autospawn uses the local `sandbox-agent` binary. Install `@sandbox-agent/cli` (recommended) or set
|
|
`SANDBOX_AGENT_BIN` to a custom path.
|
|
|
|
## Sessions and messages
|
|
|
|
```ts
|
|
await client.createSession("demo-session", {
|
|
agent: "codex",
|
|
agentMode: "default",
|
|
permissionMode: "plan",
|
|
});
|
|
|
|
await client.postMessage("demo-session", { message: "Hello" });
|
|
```
|
|
|
|
List agents and pick a compatible one:
|
|
|
|
```ts
|
|
const agents = await client.listAgents();
|
|
const codex = agents.agents.find((agent) => agent.id === "codex");
|
|
console.log(codex?.capabilities);
|
|
```
|
|
|
|
## Poll events
|
|
|
|
```ts
|
|
const events = await client.getEvents("demo-session", {
|
|
offset: 0,
|
|
limit: 200,
|
|
includeRaw: false,
|
|
});
|
|
|
|
for (const event of events.events) {
|
|
console.log(event.type, event.data);
|
|
}
|
|
```
|
|
|
|
## Stream events (SSE)
|
|
|
|
```ts
|
|
for await (const event of client.streamEvents("demo-session", {
|
|
offset: 0,
|
|
includeRaw: false,
|
|
})) {
|
|
console.log(event.type, event.data);
|
|
}
|
|
```
|
|
|
|
The SDK parses `text/event-stream` into `UniversalEvent` objects. If you want full control, use
|
|
`getEventsSse()` and parse the stream yourself.
|
|
|
|
## Optional raw payloads
|
|
|
|
Set `includeRaw: true` on `getEvents` or `streamEvents` to include the raw provider payload in
|
|
`event.raw`. This is useful for debugging and conversion analysis.
|
|
|
|
## Error handling
|
|
|
|
All HTTP errors throw `SandboxAgentError`:
|
|
|
|
```ts
|
|
import { SandboxAgentError } from "sandbox-agent";
|
|
|
|
try {
|
|
await client.postMessage("missing-session", { message: "Hi" });
|
|
} catch (error) {
|
|
if (error instanceof SandboxAgentError) {
|
|
console.error(error.status, error.problem);
|
|
}
|
|
}
|
|
```
|
|
|
|
## Types
|
|
|
|
The SDK exports OpenAPI-derived types for events, items, and capabilities:
|
|
|
|
```ts
|
|
import type { UniversalEvent, UniversalItem, AgentCapabilities } from "sandbox-agent";
|
|
```
|
|
|
|
See `docs/universal-api.mdx` for the universal schema fields and semantics.
|