Agents reference: prompts, sessions and interactive control

Every member for running a coding agent in a sandbox: one-shot prompts, streams, durable sessions, human answers, the agent’s own terminal UI, and several agents side by side.

import { Sandbox } from "@tangle-network/sandbox";
 
const client = new Sandbox({
  apiKey: process.env.TANGLE_API_KEY!,
  baseUrl: "https://sandbox.tangle.tools",
});
 
const box = await client.create({
  git: { url: "https://github.com/tangle-network/sandbox-demo" },
  backend: { type: "claude-code" },
});
try {
  const result = await box.prompt("Explain what this repository does in three sentences.", {
    sessionId: "explain",
  });
  if (!result.success) throw new Error(`${result.errorCode}: ${result.error}`);
  console.log(result.response);
} finally {
  await box.delete();
}

Choose the coding agent

backend on create, or per prompt, selects the coding agent:

backend: {
  type: "claude-code",
  profile: agentProfile,
  model: { model, provider, apiKey, baseUrl, apiKeyEnv, cliAuth, authMode, authFiles },
  interactions: { permission, question, plan },
}

Prompt and wait: box.prompt

prompt(message, options?): Promise<PromptResult>. message is a string or a list of input parts. Route: POST /v1/sandboxes/{id}/runtime/agents/run/stream.

prompt never throws for a failed run; check result.success.

Stream: box.streamPrompt

streamPrompt(message, options?): AsyncGenerator<SandboxEvent>. Each event is { type, data, id }. Breaking out of the loop before the final event cancels the run unless detach: true. A lost connection yields an error event with STREAM_INTERRUPTED; rejoin with executionId and lastEventId. See Streaming.

Dispatch: box.dispatchPrompt

dispatchPrompt(message, { sessionId?, keepEvents?, ...promptOptions }) returns once the run is admitted:

Read the result later with box.session(sessionId).result({ executionId }).

Retry-safe turns

Sessions

SandboxSession members:

SandboxTaskSession adds changes(), the files the task changed, and commit().

Answer the agent

When interactions asks for it, the agent pauses for you.

Interactive sessions

box.session(id).interactive(options?) runs the coding agent’s own terminal UI instead of a headless turn.

BrowserInteractiveSessionController from @tangle-network/sandbox/interactive-control does the same from a browser with a scoped token. See Interactive mode.

Several agents: box.agents

box.agents exists after import "@tangle-network/sandbox/agent".

import "@tangle-network/sandbox/agent";
 
const reviewer = await box.agents.start({ id: "reviewer", backend: { type: "claude-code" } });
const fixer = await box.agents.start({
  id: "fixer",
  backend: { type: "codex" },
  workspace: { mode: "isolated" },
});

Different ids run in parallel; turns in one agent run one at a time. See Run several agents.

Tools for your own agent

@tangle-network/sandbox/agent also gives an agent you run elsewhere the sandbox as tools: sandbox_exec, sandbox_run_code, sandbox_read, sandbox_write, sandbox_list and sandbox_search.

See OpenAI, Anthropic, Vercel AI, Mastra and MCP.

Python and REST

Python has box.prompt(...) and box.stream_prompt(...). It has no sessions, dispatch, interactions, interactive sessions or agents. Call session routes through client.fetch, which returns the raw response and does not raise on an error status:

client.fetch("GET", f"/v1/sandboxes/{box.id}/runtime/agents/sessions")

Next

• Coding agents in the cloud
• Keep conversations across turns and processes
• Resources reference