#Sessions

A session is the durable unit of agent work. It binds one agent snapshot, one environment, optional resources, and one or more vaults.

Official reference: Claude Managed Agents sessions.

Create A Session#

typescript
const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    title: "Triage failing tests",
    vault_ids: [llmVault.id],
    resources: [{
        type: "github_repository",
        url: "https://github.com/anthropics/anthropic-sdk-typescript",
        checkout: { type: "branch", name: "main" },
    }],
    metadata: {
        workflow: "test-triage",
    },
});

Agent Snapshot#

The agent field can reference the latest agent:

typescript
const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [llmVault.id],
});

It can also pin a specific version:

typescript
const session = await client.beta.sessions.create({
    agent: {
        type: "agent",
        id: agent.id,
        version: 1,
    },
    environment_id: environment.id,
    vault_ids: [llmVault.id],
});

Resources#

Resources are materialized into the session workspace.

Repository authorization tokens are accepted on create or update, but are not returned in responses.

Lifecycle#

Sandbox0 keeps session state and event history outside the sandbox. The sandbox and workspace volume are runtime attachments for the session.

rescheduling is transient. It is emitted as session.status_rescheduled after a session.error whose error.retry_status.type is retrying. When the same run resumes and produces more output, Sandbox0 emits session.status_running again. If the retry budget is exhausted, the run returns to idle with stop_reason.type = "retries_exhausted"; terminal non-retryable failures move the session to terminated.

Sandbox0 Runtime Behavior#

• Creating or resuming work ensures a sandbox exists for the session.
• The workspace is backed by a Sandbox0 volume mounted at /workspace.
• The runtime sandbox uses auto-resume.
• Runtime sandbox lifetime is managed by the Managed Agents deployment.
• The selected agent engine is resolved from the attached LLM vault; if no engine is selected, the default is claude.
• claude and codex run the agent process inside the sandbox.
• openai-agents runs the agent loop in a resident runtime and uses Sandbox0 as a sandbox tool.
• All supported engines map observable automatic retry attempts to the same session state sequence: running, rescheduling, running, then either idle or terminated.

Next Steps#