List managed agents (summaries: id, name, model, description, metadata).

Find an agent_* to run (unless the user gave one). Read each agent's name/description/metadata to understand what it does — that determines which environment, vault(s), and memory store(s) it needs. Use agent_get for full config before starting. Page via the returned next_page token.

Get one agent's full configuration by agent_* id.

Read this BEFORE starting a session: the agent's description, metadata, model, system prompt, tools, mcp_servers, and skills tell you what it does — and therefore which environment, vault(s), and memory store(s) you must attach at session_start for it to work. Then match those against environment_list / vault_list / memory_store_list.

List sandbox environments (summaries: id, name, description, metadata).

Starting a session needs an env_*. Don't just grab the first — pick the environment that fits THIS agent by matching its name/description/metadata to the agent (e.g. metadata.agent_name, or a shared naming convention). The wrong environment gives the agent the wrong tools/packages. Page via next_page.

Get one environment's full configuration by env_* id (packages, networking).

List credential vaults (summaries: id, display_name, metadata).

An agent whose MCP servers need auth must start with the vlt_* vault that BELONGS to it (session_start(vault_ids=[…])), or those servers fail to connect. Identify the right vault by matching its display_name/metadata to the agent — commonly metadata.agent_name=<agent> or a name like "-vault". Attaching the wrong vault, or none, breaks the agent's tools. Page via next_page.

Get one vault's details by vlt_* id (display name, metadata, timestamps).

Secret values are never returned — Anthropic stores and injects them. This is metadata only, to confirm the vault is the one you want before attaching it.

List memory stores (summaries: id, name, description, metadata).

memstore_* stores are the agent's persistent memory, mounted as a directory. Attach the store that BELONGS to THIS agent at session_start(memory_store_ids=[…]) — match its name/description/metadata to the agent (commonly metadata.agent_name=<agent> or a name like "-memory"). The wrong store, or none, means the agent loses its history/context. Page via next_page.

Get one memory store's details by memstore_* id (name, description, timestamps).

Start a managed-agent session — with the RIGHT resources attached for THIS agent.

Do NOT start bare or with mismatched resources. An agent only behaves well when its OWN environment, vault(s), and memory store(s) are attached; the wrong or missing ones cause failed tool authentication, lost memory/context, and bad outcomes.

Before calling, assemble the resources for this agent:

1. agent_get(agent_id) — read its description, metadata, mcp_servers, skills.

2. Choose environment_id + vault_ids + memory_store_ids that BELONG to this agent by matching each resource's name/description/metadata (often metadata.agent_name=<agent>, or "-vault" / "-memory"). Use environment_list / vault_list / memory_store_list (and *_get when unsure). If you can't confidently match a resource, ask the user — don't guess or skip it.

Then:

• vault_ids — vlt_* credential vaults (else MCP servers needing auth fail).

• memory_store_ids — memstore_* persistent memory mounted in the sandbox.

• message — sent as the first instruction now (omit to only provision).

• agent_version — pin a version (default: latest).

Returns the session_id. After starting, OBSERVE by polling session_get/session_events until status is "idle".

Get a session's current status and token usage.

Status is one of: idle (waiting for input — done with its turn), running (working), rescheduling (retrying), terminated (ended on error). When idle with a stop_reason of requires_action, the agent is waiting on a tool confirmation — use session_respond.

List sessions, optionally filtered to one agent_id and/or statuses.

statuses filters by session status (e.g. ["running", "idle"]). Returns id + status each; page with the returned next_page token when has_more is true.

Read a session's events — the agent's output and activity. POLL this to observe.

To observe new output as the agent works, poll: pass the returned next_since back as since on the next call to fetch only events recorded after the last batch (events are returned oldest-first). Filter with types (e.g. ["agent.message"] for just the agent's text, or ["agent.tool_use", "agent.tool_result"] for tool activity). When has_more is true within a batch, pass the returned next_page token as page. Large payloads truncated.

Common types: agent.message (text), agent.thinking, agent.tool_use / agent.tool_result, agent.mcp_tool_use, session.status_idle (with stop_reason).

Send a user message to the agent — start work, reply, or continue a turn.

Use to give the agent a new instruction or to resume an idle session. After sending, OBSERVE by polling session_events.

Interrupt a running agent, optionally redirecting it with a new instruction.

Sends a user.interrupt; if then_message is given, it follows immediately so the agent stops what it's doing and takes the new direction.

Approve or deny a tool call the agent is waiting on (a permission policy gate).

When session_get shows status "idle" with stop_reason requires_action, the agent paused for confirmation. The blocking event ids are in stop_reason.event_ids. Call this with tool_use_id = the blocking event id and result = "allow" or "deny" (add deny_message to explain a denial).

Archive a session: stop accepting new events but keep its history. Reversible-ish.

Permanently delete a session (history + sandbox). Cannot delete a running session.