Skip to main content
The Agent module lets you start and manage Claude Agent SDK sessions that run inside the sandbox. The agent has full access to the sandbox filesystem and shell. Access it via sandbox.agent.

​
Starting an agent session

const session = await sandbox.agent.start({
  prompt: "Set up a React project with TypeScript and Tailwind CSS",
  onEvent: (event) => {
    switch (event.type) {
      case "assistant":
        console.log(event.content);
        break;
      case "tool_use_summary":
        console.log(`Tool: ${event.tool} — ${event.summary}`);
        break;
      case "result":
        console.log("Done:", event.result);
        break;
      case "error":
        console.error("Error:", event.error);
        break;
    }
  },
});

const exitCode = await session.done;

​
sandbox.agent.start(opts?)

Starts a new agent session inside the sandbox.
​
prompt
string
The task for the agent to perform.
​
model
string
Claude model to use (e.g. "claude-sonnet-4-20250514").
​
systemPrompt
string
Custom system prompt for the agent.
​
allowedTools
string[]
List of tools the agent is allowed to use.
​
permissionMode
string
Permission mode for the agent session.
​
maxTurns
number
Maximum number of turns before the agent stops.
​
cwd
string
Working directory for the agent.
​
mcpServers
Record<string, McpServerConfig>
MCP servers to make available to the agent.
​
onEvent
(event: AgentEvent) => void
Callback for agent events (assistant messages, tool use, results, errors).
​
onError
(data: string) => void
Callback for stderr output from the agent process.
​
onExit
(exitCode: number) => void
Callback when the agent process exits.
Returns: Promise<AgentSession>

​
AgentSession

The object returned by sandbox.agent.start().
Property / MethodTypeDescription
sessionIdstringUnique session identifier
donePromise<number>Resolves with the exit code when the agent finishes
sendPrompt(text)(text: string) => voidSend a follow-up prompt to the agent
interrupt()() => voidInterrupt the agent’s current turn
configure(config)(config: AgentConfig) => voidUpdate agent configuration mid-session
kill(signal?)(signal?: number) => Promise<void>Kill the agent process
close()() => voidClose the WebSocket connection

​
Agent events

Events are delivered via the onEvent callback. Each event has a type field:
Event typeDescription
readyAgent process is ready
configuredConfiguration has been applied
assistantAssistant message (text output from the agent)
tool_use_summarySummary of a tool the agent used
resultFinal result from the agent
turn_completeA single turn has completed
interruptedAgent was interrupted
errorAn error occurred

​
Examples

​
Send follow-up prompts

const session = await sandbox.agent.start({
  prompt: "Create a Node.js REST API with Express",
  onEvent: (event) => {
    if (event.type === "assistant") console.log(event.content);
  },
});

// Wait for the first task, then send a follow-up
await session.done;

const session2 = await sandbox.agent.start({
  prompt: "Now add tests using Jest for the API you just created",
  onEvent: (event) => {
    if (event.type === "assistant") console.log(event.content);
  },
});

await session2.done;

​
Configure MCP servers

const session = await sandbox.agent.start({
  prompt: "Use the database tool to query all users",
  mcpServers: {
    database: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-sqlite", "/data/app.db"],
    },
  },
  onEvent: (event) => {
    if (event.type === "assistant") console.log(event.content);
  },
});

​
List active agent sessions

const sessions = await sandbox.agent.list();
for (const s of sessions) {
  console.log(`${s.sessionID} — running: ${s.running}`);
}

​
Attach to an existing session

Reconnect to a running agent session by its ID: 
const session = await sandbox.agent.attach("session-id", {
  onEvent: (event) => {
    if (event.type === "assistant") console.log(event.content);
  },
});

await session.done;