Agent

Accessed via sandbox.agent.

`await sandbox.agent.start(...)`

Start an agent session. HTTP API →

prompt

str

Initial prompt

model

str

Claude model

system_prompt

str

System prompt

allowed_tools

list[str]

Restrict tools

permission_mode

str

Permission mode

max_turns

int

default:"50"

Max turns

cwd

str

Working directory

mcp_servers

dict[str, Any]

MCP server configuration

on_event

Callable[[AgentEvent], None]

Event callback

on_error

Callable[[str], None]

Stderr callback

Returns: AgentSession

session = await sandbox.agent.start(
    prompt="Build a todo app",
    on_event=lambda e: print(e.type),
)

resume, on_exit, and on_scrollback_end are not available in the Python SDK.

`await sandbox.agent.attach(session_id, ...)`

Reconnect to a running agent session. Accepts on_event and on_error. Returns: AgentSession

`await sandbox.agent.list()`

List all agent sessions. HTTP API → Returns: list[AgentSessionInfo]

AgentSession

Member	Type	Description
`session_id`	`str`	Session ID
`sandbox_id`	`str`	Sandbox ID
`send_prompt(text)`	method	Send follow-up prompt
`interrupt()`	method	Interrupt current turn
`configure(...)`	method	Update model, tools, cwd
`await kill(signal=9)`	method	Kill agent process
`await close()`	method	Close WebSocket

`await session.collect_events()`

Collect all events until the agent process exits. Python-unique alternative to callbacks. Returns: list[AgentEvent]

session = await sandbox.agent.start(prompt="Fix the tests")
events = await session.collect_events()
for event in events:
    if event.type == "result":
        print(event.data)

`await session.wait()`

Wait for the agent to finish. Returns: int (exit code)

Types

AgentEvent

@dataclass
class AgentEvent:
    type: str
    data: dict[str, Any]

# Usage:
event["message"]      # dict-like access
event.get("message")  # safe access with default
event.type            # attribute access

AgentSessionInfo

@dataclass
class AgentSessionInfo:
    session_id: str
    sandbox_id: str
    running: bool
    started_at: str

Getting Started

Sandboxes

Reserved Capacity

Agent SDK

Hosted Agents

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

`await sandbox.agent.start(...)`

`await sandbox.agent.attach(session_id, ...)`

`await sandbox.agent.list()`

AgentSession

`await session.collect_events()`

`await session.wait()`

Types

​await sandbox.agent.start(...)

​await sandbox.agent.attach(session_id, ...)

​await sandbox.agent.list()

​AgentSession

​await session.collect_events()

​await session.wait()

​Types

`await sandbox.agent.start(...)`

`await sandbox.agent.attach(session_id, ...)`

`await sandbox.agent.list()`

AgentSession

`await session.collect_events()`

`await session.wait()`

Types