#Events

Events are the durable interface for a session. Send user input as events, then list or stream events to observe status, agent output, tool calls, and errors.

Official references:

• Claude Managed Agents events and streaming
• Claude Managed Agents event types

Send User Input#

typescript
await client.beta.sessions.events.send(session.id, {
    events: [{
        type: "user.message",
        content: [{ type: "text", text: "Inspect the test failure and propose a fix." }],
    }],
});

List Events#

typescript
for await (const event of client.beta.sessions.events.list(session.id, {
    order: "asc",
    limit: 100,
    types: ["agent.message", "session.status_idle"],
})) {
    console.log(event.type);
}

Direct HTTP callers can also filter by types[] or types, plus created_at[gt], created_at[gte], created_at[lt], and created_at[lte].

Stream Events#

typescript
const stream = await client.beta.sessions.events.stream(session.id);

for await (const event of stream) {
    if (event.type === "agent.message") {
        console.log(event.content);
    }
    if (event.type === "session.status_idle") {
        break;
    }
}

Supported Event Types#

Claude Managed Agents groups events into five domains: user, agent, session, span, and system events. Sandbox0 tracks the current official event shape for capabilities implemented by Sandbox0.

Outcome events are not supported because Sandbox0 does not implement Managed Agents outcomes. Memory has no standalone memory.* event family in the official event catalog, and Sandbox0 does not implement Managed Agents memory.

User Events#

session_thread_id is accepted on interrupt, tool confirmation, and tool-result events for SDK compatibility. Sandbox0 does not emit multi-agent thread events from its own backend today.

Agent Events#

Session Events#

Span Events#

System Events#

Treat session.status_idle with stop_reason.type = "end_turn" as a normal turn completion. If the stop reason is requires_action, send the required confirmation or custom tool result before expecting the run to continue.

system.message follows the official request ordering rule: at most one per request, it must be the final event, and it must immediately follow user.message, user.tool_result, or user.custom_tool_result.

Action Resolution#

When a tool needs application input, the session emits session.status_idle with stop_reason.type = "requires_action" and one or more event ids.

Tool result content supports text, image, document, and search_result blocks for tool-result events. search_result is not accepted in user.message content.

Session Update Events#

UpdateSession appends session.updated when a supported field actually changes. The event includes only changed official fields. Sandbox0 vault_ids updates refresh runtime credential state but are not emitted as non-official session.updated fields.

Retry Events#

Sandbox0 exposes automatic model retries through the normal event stream:

Do not send duplicate user input when a session is rescheduling. Wait for either session.status_running, session.status_idle, or session.status_terminated.

File-Backed Input#

Uploaded files can be referenced from message content. See Files for upload, session-scoped copies, and output files.

typescript
await client.beta.sessions.events.send(session.id, {
    events: [{
        type: "user.message",
        content: [
            { type: "text", text: "Summarize this document." },
            {
                type: "document",
                source: { type: "file", file_id: uploaded.id },
                title: "input",
                citations: { enabled: true },
            },
        ],
    }],
});

Sandbox0 Notes#

• Event history is stored outside the sandbox.
• Runtime callbacks are signed before being appended to the session log.
• Event streaming is compatible with the SDK surface and backed by Sandbox0 session events.

Next Steps#