mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 04:03:31 +00:00
130 lines
2.8 KiB
Text
130 lines
2.8 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 daemon. It provides a typed
|
|
client for sessions, events, and agent operations.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install sandbox-agent
|
|
```
|
|
|
|
## Create a client
|
|
|
|
```ts
|
|
import { SandboxDaemonClient } from "sandbox-agent";
|
|
|
|
const client = new SandboxDaemonClient({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
token: process.env.SANDBOX_TOKEN,
|
|
});
|
|
```
|
|
|
|
Or with the factory helper:
|
|
|
|
```ts
|
|
import { createSandboxDaemonClient } from "sandbox-agent";
|
|
|
|
const client = createSandboxDaemonClient({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
});
|
|
```
|
|
|
|
## Autospawn (Node only)
|
|
|
|
If you run locally, the SDK can launch the daemon for you.
|
|
|
|
```ts
|
|
import { connectSandboxDaemonClient } from "sandbox-agent";
|
|
|
|
const client = await connectSandboxDaemonClient({
|
|
spawn: { enabled: true },
|
|
});
|
|
|
|
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",
|
|
agent_mode: "default",
|
|
permission_mode: "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,
|
|
include_raw: false,
|
|
});
|
|
|
|
for (const event of events.events) {
|
|
console.log(event.event_type, event.data);
|
|
}
|
|
```
|
|
|
|
## Stream events (SSE)
|
|
|
|
```ts
|
|
for await (const event of client.streamEvents("demo-session", {
|
|
offset: 0,
|
|
include_raw: false,
|
|
})) {
|
|
console.log(event.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 `include_raw: 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 `SandboxDaemonError`:
|
|
|
|
```ts
|
|
import { SandboxDaemonError } from "sandbox-agent";
|
|
|
|
try {
|
|
await client.postMessage("missing-session", { message: "Hi" });
|
|
} catch (error) {
|
|
if (error instanceof SandboxDaemonError) {
|
|
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.
|