sandbox-agent/docs/agent-sessions.mdx

---
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",
  sessionInit: {
    cwd: "/",
    mcpServers: [],
  },
});

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
// Claude permission modes are exposed as a first-class helper.
const claude = await sdk.createSession({
  agent: "claude",
  permissionMode: "default",
});
```

```ts
// After creation
await session.setModel("gpt-5.2-codex");
await session.setMode("full-access");
await session.setThoughtLevel("medium");
```

```ts
await claude.setPermissionMode("acceptEdits");
```

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 use ACP `session/request_permission` (for example Claude in `default` mode), register a permission listener and reply with `once`, `always`, or `reject`:

```ts
const claude = await sdk.createSession({
  agent: "claude",
  permissionMode: "default",
});

claude.onPermissionRequest((request) => {
  console.log(request.toolCall.title, request.availableReplies);
  void claude.replyPermission(request.id, "once");
});

await claude.prompt([
  { type: "text", text: "Create ./permission-example.txt with the text hello." },
]);
```

See `examples/permissions/src/index.ts` for a complete permissions example that works with Claude and Codex.

## Destroy a session

```ts
await sdk.destroySession(session.id);
```