mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 20:03:11 +00:00
6a42f06342
- Add built-in sandbox providers (local, docker, e2b, daytona, vercel, cloudflare) to the TypeScript SDK so users import directly instead of passing client instances - Restructure docs: rename architecture to orchestration-architecture, add new architecture page for server overview, improve getting started flow - Rewrite quickstart to be TypeScript-first with provider CodeGroup and custom provider accordion - Update all examples to use new provider APIs - Update persist drivers and foundry for new SDK surface Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
166 lines
3.8 KiB
Text
166 lines
3.8 KiB
Text
---
|
|
title: "Agent Sessions"
|
|
description: "Create sessions, prompt agents, and inspect event history."
|
|
sidebarTitle: "Sessions"
|
|
icon: "comments"
|
|
---
|
|
|
|
Sessions are the unit of interaction with an agent. Create one session per task, send prompts, and consume event history.
|
|
|
|
For SDK-based flows, sessions can be restored after runtime/session loss when persistence is enabled.
|
|
See [Session Restoration](/session-restoration).
|
|
|
|
## Create a session
|
|
|
|
```ts
|
|
import { SandboxAgent } from "sandbox-agent";
|
|
|
|
const sdk = await SandboxAgent.connect({
|
|
baseUrl: "http://127.0.0.1:2468",
|
|
});
|
|
|
|
const session = await sdk.createSession({
|
|
agent: "codex",
|
|
cwd: "/",
|
|
});
|
|
|
|
console.log(session.id, session.agentSessionId);
|
|
```
|
|
|
|
## Send a prompt
|
|
|
|
```ts
|
|
const response = await session.prompt([
|
|
{ type: "text", text: "Summarize the repository structure." },
|
|
]);
|
|
|
|
console.log(response.stopReason);
|
|
```
|
|
|
|
## Subscribe to live events
|
|
|
|
```ts
|
|
const unsubscribe = session.onEvent((event) => {
|
|
console.log(event.eventIndex, event.sender, event.payload);
|
|
});
|
|
|
|
await session.prompt([
|
|
{ type: "text", text: "Explain the main entrypoints." },
|
|
]);
|
|
|
|
unsubscribe();
|
|
```
|
|
|
|
## Fetch persisted event history
|
|
|
|
```ts
|
|
const page = await sdk.getEvents({
|
|
sessionId: session.id,
|
|
limit: 50,
|
|
});
|
|
|
|
for (const event of page.items) {
|
|
console.log(event.id, event.createdAt, event.sender);
|
|
}
|
|
```
|
|
|
|
## List and load sessions
|
|
|
|
```ts
|
|
const sessions = await sdk.listSessions({ limit: 20 });
|
|
|
|
for (const item of sessions.items) {
|
|
console.log(item.id, item.agent, item.createdAt);
|
|
}
|
|
|
|
if (sessions.items.length > 0) {
|
|
const loaded = await sdk.resumeSession(sessions.items[0]!.id);
|
|
await loaded.prompt([{ type: "text", text: "Continue." }]);
|
|
}
|
|
```
|
|
|
|
## Configure model, mode, and thought level
|
|
|
|
Set the model, mode, or thought level on a session at creation time or after:
|
|
|
|
```ts
|
|
// At creation time
|
|
const session = await sdk.createSession({
|
|
agent: "codex",
|
|
model: "gpt-5.3-codex",
|
|
mode: "auto",
|
|
thoughtLevel: "high",
|
|
});
|
|
```
|
|
|
|
```ts
|
|
// After creation
|
|
await session.setModel("gpt-5.2-codex");
|
|
await session.setMode("full-access");
|
|
await session.setThoughtLevel("medium");
|
|
```
|
|
|
|
Query available modes:
|
|
|
|
```ts
|
|
const modes = await session.getModes();
|
|
console.log(modes?.currentModeId, modes?.availableModes);
|
|
```
|
|
|
|
### Advanced config options
|
|
|
|
For config options beyond model, mode, and thought level, use `getConfigOptions` to discover what the agent supports and `setConfigOption` to set any option by ID:
|
|
|
|
```ts
|
|
const options = await session.getConfigOptions();
|
|
for (const opt of options) {
|
|
console.log(opt.id, opt.category, opt.type);
|
|
}
|
|
```
|
|
|
|
```ts
|
|
await session.setConfigOption("some-agent-option", "value");
|
|
```
|
|
|
|
## Handle permission requests
|
|
|
|
For agents that request tool-use permissions, register a permission listener and reply with `once`, `always`, or `reject`:
|
|
|
|
```ts
|
|
const session = await sdk.createSession({
|
|
agent: "claude",
|
|
mode: "default",
|
|
});
|
|
|
|
session.onPermissionRequest((request) => {
|
|
console.log(request.toolCall.title, request.availableReplies);
|
|
void session.respondPermission(request.id, "once");
|
|
});
|
|
|
|
await session.prompt([
|
|
{ type: "text", text: "Create ./permission-example.txt with the text hello." },
|
|
]);
|
|
```
|
|
|
|
|
|
### Auto-approving permissions
|
|
|
|
To auto-approve all permission requests, respond with `"once"` or `"always"` in your listener:
|
|
|
|
```ts
|
|
session.onPermissionRequest((request) => {
|
|
void session.respondPermission(request.id, "always");
|
|
});
|
|
```
|
|
|
|
See `examples/permissions/src/index.ts` for a complete permissions example that works with Claude and Codex.
|
|
|
|
<Info>
|
|
Some agents like Claude allow configuring permission behavior through modes (e.g. `bypassPermissions`, `acceptEdits`). We recommend leaving the mode as `default` and handling permission decisions explicitly in `onPermissionRequest` instead.
|
|
</Info>
|
|
|
|
## Destroy a session
|
|
|
|
```ts
|
|
await sdk.destroySession(session.id);
|
|
```
|