Skip to main content
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

MemberTypeDescription
session_idstrSession ID
sandbox_idstrSandbox ID
send_prompt(text)methodSend follow-up prompt
interrupt()methodInterrupt current turn
configure(...)methodUpdate model, tools, cwd
await kill(signal=9)methodKill agent process
await close()methodClose 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

@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

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