# Anthropic Managed Agents (beta)

Status: DOCUMENTED · BETA (anthropic-beta: managed-agents-2026-04-01) — live probe results are appended in section "Live verification" by the parent agent

Sources (all retrieved 2026-09-18, offline copies under `sources/anthropic/pages/managed-agents/**` and `sources/anthropic/pages/api/beta/**`):

- Guides: https://platform.claude.com/docs/en/managed-agents/overview · quickstart · agent-setup · sessions · session-operations · events-and-streaming · environments · cloud-sandboxes-reference · self-hosted-sandboxes · self-hosted-sandboxes-security · tools · mcp-connector · skills · memory · files · multiagent-orchestration · budgets · define-outcomes · permission-policies · vaults · scheduled-deployments · dreams · webhooks · github · migration · onboarding · reference (all under `https://platform.claude.com/docs/en/managed-agents/<slug>`)
- REST reference: `https://platform.claude.com/docs/en/api/beta/{agents,sessions,environments,deployments,deployment_runs,dreams,memory_stores,vaults,tunnels,user_profiles,webhooks}/**` (pre-parsed to `tmp/platform-anthropic/ref/*.json`)
- MCP tunnels: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/{overview,concepts,reference}
- Machine-readable twins produced with this page: `generated/fragments/streaming-events/anthropic-managed-agents.json` (88 event records), `tmp/platform-anthropic/objects-managed-agents.json` (37 object records), `tmp/platform-anthropic/examples-agents.json` + `examples/anthropic/agents/*`

Last verified: 2026-09-18 (documentation only; no live call was made while writing this page)

---

## 1. What Managed Agents is

Claude Managed Agents is a **pre-built, configurable agent harness that runs in Anthropic-managed infrastructure**. Instead of writing an agent loop against the Messages API (maintain history, iterate `tool_use` blocks, run tools, loop), you create an **Agent** (model + system prompt + tools + MCP servers + skills), an **Environment** (where the sandbox runs), start a **Session**, and exchange **Events** over REST + SSE. The harness provides prompt caching, context compaction, a Linux sandbox with pre-installed runtimes, server-side persisted history, budgets, outcomes/grading, multi-agent threads, memory stores, scheduled runs and webhooks.

| | Messages API | Claude Managed Agents |
|---|---|---|
| What it is | Direct model prompting access | Pre-built agent harness in managed infrastructure |
| Best for | Custom agent loops, fine-grained control | Long-running tasks, asynchronous work |
| Loop / tool execution | You | Anthropic (built-in tools in sandbox); you only handle `custom` tools |
| History | You pass `messages` every call | Persisted server-side; you send/receive events |
| End of work | You decide | `session.status_idle` event |

Relation to the **Claude Agent SDK** (from the migration guide): `ClaudeAgentOptions` → `POST /v1/agents` (persisted, versioned); `ClaudeSDKClient`/`query()` → `POST /v1/sessions` + events; `@tool` functions → `{"type":"custom",...}` on the agent + `agent.custom_tool_use` / `user.custom_tool_result` events; built-in tools → `agent_toolset_20260401` in the sandbox against `/workspace`; `cwd`/`add_dirs` → file / repo resources; `system_prompt` + `CLAUDE.md` → single `system` string (versioned); `mcp_servers` → declared on the agent, authenticated via a **Vault** on the session; `permission_mode`/`can_use_tool` → per-tool `permission_policy` (`always_allow` | `always_ask` | `auto`) + `user.tool_confirmation`. Things that move to your client: plan mode (run a planning session first), output styles / slash commands, `PreToolUse`/`PostToolUse` hooks (use `always_ask` or custom-tool handling), `max_turns` (count client-side).

**Beta access.** All Managed Agents endpoints require `anthropic-beta: managed-agents-2026-04-01` (SDKs set it). Enabled by default for all API accounts. Within the beta, **MCP tunnels** and **dreaming** are a more limited research preview (request access). Also available on Claude Platform on AWS with differences (self-hosted workers authenticate with IAM SigV4 / AWS-console API key; memory stores cannot be attached to self-hosted sessions there).

**Data retention.** Stateful by design (history, sandbox state, outputs stored server-side) → **not eligible for Zero Data Retention or HIPAA BAA**. You can delete sessions and uploaded files at any time.

Related but separate betas (do not mix headers where noted):

| Surface | Beta header | Notes |
|---|---|---|
| Managed Agents core (agents, sessions, environments, deployments, vaults, files scope filter, work queue) | `managed-agents-2026-04-01` | |
| Memory stores (`/v1/memory_stores/**`) | `agent-memory-2026-07-22` | Sending **both** headers on a memory-store call returns 400. Attaching a store to a session still uses `managed-agents-2026-04-01`. (The REST reference pages list only the generic `anthropic-beta` header.) |
| Dreams (`/v1/dreams/**`) | `managed-agents-2026-04-01,dreaming-2026-04-21` | Research preview; `dreaming-2026-04-21` required in addition |
| Tunnels API (`/v1/tunnels/**`) | `mcp-tunnels-2026-06-22` + WIF bearer with `workspace:manage_tunnels` | Research preview; Admin API keys not accepted; supersedes `/v1/organizations/tunnels` (`mcp-tunnels-2026-05-19`, `org:manage_tunnels`, deprecation notice) |
| User profiles (`/v1/user_profiles/**`) | `user-profiles-2026-09-04` (older `-03-24`, `-08-18`) | Not referenced by any Managed Agents guide; documented in §17 for completeness only |

---

## 2. Architecture

```mermaid
flowchart LR
  subgraph Client["Your application"]
    APP[REST client / SDK / ant CLI]
    WH[Webhook endpoint HTTPS:443]
    WK[Self-hosted worker\nEnvironmentWorker / ant beta:worker]
    CT[Custom tool executor]
  end

  subgraph Anthropic["Anthropic control plane (api.anthropic.com, beta managed-agents-2026-04-01)"]
    AG[Agent\n/v1/agents (versioned)]
    SS[Session\n/v1/sessions]
    TH[Session threads\n/threads (multiagent, advisor)]
    EV[(Event log\n/events · /events/stream SSE)]
    ENV[Environment\n/v1/environments]
    DEP[Deployment (cron)\n/v1/deployments → deployment_runs]
    VLT[Vault + credentials\n/v1/vaults]
    MEM[Memory stores\n/v1/memory_stores (+memories, versions)]
    DRM[Dream\n/v1/dreams]
    FILES[Files API\n/v1/files (scope_id=session)]
    SK[Skills\n/v1/skills + Anthropic skills]
    TUN[MCP tunnels\n/v1/tunnels + certificates + token]
    WQ[(Work queue\n/environments/{id}/work)]
  end

  subgraph Exec["Execution"]
    CS[Cloud sandbox\nUbuntu 24.04, 8 GB, 10 GB\n/workspace /mnt/session/uploads /mnt/session/outputs /mnt/memory]
    SH[Self-hosted sandbox\nyour infrastructure]
  end

  subgraph Ext["External"]
    MCP[Remote MCP servers\n(HTTP streamable / SSE fallback)]
    PMCP[Private MCP servers]
    GH[GitHub repos + GitHub MCP]
    WEB[web_search / web_fetch\n(run on Anthropic servers)]
  end

  APP -->|create/update/archive| AG
  APP -->|create/list/update/archive/delete| SS
  APP -->|send user.* / system.message| EV
  EV -->|SSE agent.* session.* span.* event_start/delta| APP
  SS --> TH --> EV
  SS -->|environment_id| ENV
  AG -->|snapshot at create| SS
  DEP -->|schedule / run now| SS
  SS -->|vault_ids| VLT
  SS -->|resources: file / github_repository / memory_store| FILES
  SS --> MEM
  SS --> GH
  AG -->|skills[]| SK
  ENV -->|type: cloud| CS
  ENV -->|type: self_hosted| WQ
  WQ -->|poll / ack / heartbeat / stop| WK --> SH
  WK -->|user.tool_result / custom tool results| EV
  CS -->|bash read write edit glob grep| CS
  CS --> WEB
  SS -->|mcp_servers + mcp_toolset| MCP
  MCP -.->|tunnel domain| TUN --> PMCP
  MEM --> DRM
  DRM -->|new output store| MEM
  EV -->|agent.custom_tool_use| CT -->|user.custom_tool_result| EV
  SS -->|session.* deployment.* vault.* agent.* environment.* memory_store.*| WH
```

Core concepts (overview):

| Concept | Description |
|---|---|
| **Agent** | Model, system prompt, tools, MCP servers, skills (+ `multiagent` roster). Versioned, reusable by ID |
| **Environment** | Where sessions run: Anthropic-managed **cloud** sandbox or **self_hosted** sandbox (your worker polls a work queue) |
| **Session** | A running agent instance in an environment; owns history, sandbox state, usage, budget, threads |
| **Events** | Messages exchanged with the agent (`user.*`/`system.message` in; `agent.*`, `session.*`, `span.*`, previews out) |

---

## 3. Session lifecycle

**Statuses** (`session.status`): `idle` (waiting for input; sessions created without `initial_events` start here) · `running` · `rescheduling` (transient error, retrying) · `terminated` (unrecoverable error or archived; a session that finishes work goes `idle`, not `terminated`). Thread statuses are the same set.

```mermaid
stateDiagram-v2
  [*] --> idle: POST /v1/sessions (no initial_events)
  [*] --> running: POST /v1/sessions with initial_events (max 50)
  idle --> running: user.message / user.define_outcome / settle events resolve requires_action / budget raised
  running --> idle: end_turn · requires_action (tool ask / custom tool) · retries_exhausted · budget_reached
  running --> rescheduling: transient error (session.status_rescheduled)
  rescheduling --> running: retry
  running --> terminated: terminal error
  idle --> terminated: POST /archive
  idle --> [*]: DELETE (session.deleted ends any stream)
```

Run loop per turn (from events-and-streaming, "Accumulate and reconcile"): `session.status_running` → (`session.thread_status_running`) → for each model request `span.model_request_start` → [`event_start` → `event_delta`* if previews on] → `agent.message` / `agent.thinking` / `agent.tool_use` + `agent.tool_result` / `agent.mcp_tool_use` + `agent.mcp_tool_result` / `agent.custom_tool_use` → `span.model_request_end` → … → `session.thread_status_idle` → **`session.usage`** (always immediately before idle) → `session.status_idle{stop_reason}`.

Key rules:

| Topic | Rule |
|---|---|
| Starting work | Creating a session registers it and starts provisioning the sandbox; work starts on the first `user.message`/`user.define_outcome` (or via `initial_events`) |
| `initial_events` | `user.message` and `user.define_outcome` only (max 50, ≤1 define_outcome, rubric required, ≤100 file-sourced `document` blocks, body ≤32 MB → 413). Validation all-or-nothing. Not echoed in the create response (list events to see them). Unlike deployments, sessions' `initial_events` do not accept `system.message` |
| Interrupt | `user.interrupt` (optionally `session_thread_id`) stops the model response immediately; tool calls may delay it; turn ends with `session.status_idle` `stop_reason.type = end_turn` (no interrupt-specific reason). Against a thread blocked on `requires_action`, pending tool calls are closed with an error tool result. No-op on an idle thread. Ignored while the whole session is paused at budget |
| requires_action | `stop_reason: {type:"requires_action", event_ids:[…]}`; resolve every id with `user.tool_confirmation` (tool_use_id), `user.custom_tool_result` (custom_tool_use_id) or `user.tool_result` (self-hosted). Resolving fewer than all re-emits `session.status_idle` with the remainder. The session waits indefinitely |
| Resume | Send another `user.message`; history persists until deletion. Sandbox state checkpointed on idle but **preserved only 30 days after sandbox creation** (not extended by activity) → write deliverables to `/mnt/session/outputs` |
| Update while running | Agent `tools`/`mcp_servers` and archive/delete require `idle`; send `user.interrupt` alone, wait for idle |
| Reconnect | Open a new stream, list `/events` to seed seen IDs, then tail; only events emitted after the stream opens are delivered (open the stream before sending) |
| Threads (multiagent) | Session-level stream = **primary thread** (condensed view + cross-posted blocking events). Each child thread has `/threads/{id}/events` and `/threads/{id}/stream`. Max **25 concurrent threads** (advisor threads exempt); archive idle threads to free slots |
| processed_at | Set when the event finishes processing; null while queued, except `user.define_outcome`, `user.custom_tool_result`, `user.tool_result` (processed on receipt) |
| Redacted blocks | Platform may emit `{"type":"redacted"}` (model policy). Clients cannot send one (400) |

---

## 4. Endpoint inventory (resource tree)

All paths relative to `https://api.anthropic.com`. Headers on every call: `x-api-key`, `anthropic-version: 2023-06-01`, `anthropic-beta: managed-agents-2026-04-01` (exceptions in §1 table), optional `anthropic-workspace-id`. Pagination on list endpoints: `limit`, opaque `page` cursor; responses carry `data[]`, `next_page`, `prev_page` (null at ends); `order` (`asc`|`desc`, default `desc` by creation time) where offered; a cursor encodes the `order` it was created with (changing it → 400). Rate limits (per organization): **create endpoints 300 req/min; read endpoints (retrieve, list, stream) 1,200 req/min**.

| Resource | Endpoints | Count |
|---|---|---|
| Agents | list, create, retrieve (`?version=`), update, archive, versions.list | 6 |
| Sessions | list, create, retrieve, update, archive, delete | 6 |
| Session events | list, send, stream | 3 |
| Session resources | list, add, retrieve, update, delete | 5 |
| Session threads | list, retrieve, archive, events.list, stream | 5 |
| Environments | list, create, retrieve, update, archive, delete | 6 |
| Environment work queue (self-hosted) | list, poll, stats, retrieve, update, ack, heartbeat, stop | 8 |
| Deployments | list, create, retrieve, update, archive, pause, unpause, run | 8 |
| Deployment runs | list, retrieve | 2 |
| Dreams | list, create, retrieve, archive, cancel | 5 |
| Memory stores | list, create, retrieve, update, archive, delete | 6 |
| Memories | list, create, retrieve, update, delete | 5 |
| Memory versions | list, retrieve, redact | 3 |
| Vaults | list, create, retrieve, update, archive, delete | 6 |
| Credentials | list, create, retrieve, update, archive, delete, mcp_oauth_validate | 7 |
| Tunnels (`/v1/tunnels`) | list, create, retrieve, archive, certificates.{list,create,retrieve,archive}, reveal_token, rotate_token | 10 |
| Org tunnels (legacy `/v1/organizations/tunnels`) | list, retrieve, archive, certificates.{list,create,retrieve,archive}, reveal_token, rotate_token | 9 |
| User profiles (separate beta) | list, create, retrieve, update, enrollment_url | 5 |
| **Total** | | **105** (96 excluding legacy org tunnels) |

Delete endpoints return `{type: "<x>_deleted"/…, id}` confirmation objects (`BetaManagedAgentsDeletedSession`, `BetaEnvironmentDeleteResponse`, `BetaManagedAgentsDeletedMemoryStore`, `BetaManagedAgentsDeletedMemory`, `BetaManagedAgentsDeletedVault`, `BetaManagedAgentsDeletedCredential`, `BetaManagedAgentsDeleteSessionResource`).

---

## 5. Agents

Guide: https://platform.claude.com/docs/en/managed-agents/agent-setup

| Method | Path | Title | Key params | Pagination | Status |
|---|---|---|---|---|---|
| GET | `/v1/agents` | List Agents | query `include_archived`, `created_at[gte]`, `created_at[lte]`, `limit`, `page` | cursor | DOCUMENTED, BETA |
| POST | `/v1/agents` | Create Agent | body `name`*, `model`*, `system`, `description`, `tools[]`, `mcp_servers[]`, `skills[]`, `multiagent`, `metadata` | — | DOCUMENTED, BETA |
| GET | `/v1/agents/{agent_id}` | Get Agent | query `version` (fetch a specific version) | — | DOCUMENTED, BETA |
| POST | `/v1/agents/{agent_id}` | Update Agent | body: any create field (nullable arrays) + optional `version` (optimistic concurrency → 409 on mismatch) | — | DOCUMENTED, BETA |
| POST | `/v1/agents/{agent_id}/archive` | Archive Agent | — (irreversible; read-only; existing sessions continue) | — | DOCUMENTED, BETA |
| GET | `/v1/agents/{agent_id}/versions` | List Agent Versions | `limit`, `page` | cursor | DOCUMENTED, BETA |

**Agent object** (`BetaManagedAgentsAgent`, `type: "agent"`):

| Field | Type | Notes |
|---|---|---|
| `id` | string (`agent_…`) | |
| `version` | integer | Starts at 1; increments on each update that changes configuration; no-op updates return the existing version |
| `name`* | string | Mandatory, not clearable |
| `model`* | `ModelConfig {id, effort, speed, inference_geo}` | Request accepts a model id string or object. `id` enum in reference (14 ids incl. `claude-fable-5-1`, `claude-fable-5`, `claude-sonnet-5`, `claude-opus-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`) or any string; Claude 4.5+ supported. `effort`: `low`|`medium`|`high`|`xhigh`|`max` (string or `{type}`); `speed`: `standard`|`fast` (fast mode: Opus 5 / Opus 4.8); `inference_geo`: `"us"`|`"global"` (validated against workspace `allowed_inference_geos` at save, session create and every turn) |
| `system` | string or null | ≤100,000 chars (per overrides docs) |
| `description`, `metadata` | string/null, map (≤16 pairs, keys ≤64, values ≤512) | metadata merges key-wise on update (`null` deletes a key) |
| `tools[]` | union `agent_toolset_20260401` \| `mcp_toolset` \| `custom` | ≤128 entries across toolsets; arrays are fully replaced on update |
| `mcp_servers[]` | `{type:"url", name (1–255, unique), url (≤2,048)}` | ≤20; every server must be referenced by an `mcp_toolset` and vice versa |
| `skills[]` | `{type:"anthropic"\|"custom", skill_id, version?}` | `version` defaults to `latest`; ≤500 skills per session (deduplicated across agents) |
| `multiagent` | `{type:"coordinator", agents[]}` or null | Roster of 1–20 entries: agent id string, `{type:"agent",id,version?}`, `{type:"self"}`, `{type:"advisor", model}` (max one). Pinned at coordinator save time |
| `created_at`, `updated_at`, `archived_at` | RFC 3339 | |

Update semantics: omitted fields preserved; scalars replaced (`system`/`description` clearable with null); within `model`, omitting `effort` keeps it when `id` unchanged, resets to default when `id` changes; supplying `model` without `inference_geo` clears the pin; arrays replaced wholesale (`null`/`[]` clears); `multiagent` replaced as a whole; coordinator rosters keep their pinned versions until the coordinator is updated. Archiving a deployment's agent archives the deployment.

---

## 6. Sessions

Guides: https://platform.claude.com/docs/en/managed-agents/sessions · https://platform.claude.com/docs/en/managed-agents/session-operations

| Method | Path | Title | Key params | Pagination | Status |
|---|---|---|---|---|---|
| GET | `/v1/sessions` | List Sessions | `agent_id`, `agent_version`, `deployment_id`, `memory_store_id`, `statuses[]` (rescheduling\|running\|idle\|terminated), `include_archived`, `created_at[gt\|gte\|lt\|lte]`, `order`, `limit`, `page` | cursor + `order` | DOCUMENTED, BETA |
| POST | `/v1/sessions` | Create Session | `agent`* (id string \| `{type:"agent",id,version}` \| `{type:"agent_with_overrides",id,version?,model?,system?,tools?,mcp_servers?,skills?}`), `environment_id`*, `title`, `metadata`, `resources[]`, `vault_ids[]`, `budget`, `initial_events[]` | — | DOCUMENTED, BETA |
| GET | `/v1/sessions/{session_id}` | Get Session | — | — | DOCUMENTED, BETA |
| POST | `/v1/sessions/{session_id}` | Update Session | `agent.{tools,mcp_servers}` (full replacement, session must be idle), `budget` (replace or `null`), `title`, `metadata` (patch), `vault_ids` (reserved: rejected) | — | DOCUMENTED, BETA |
| POST | `/v1/sessions/{session_id}/archive` | Archive Session | — (not while running) | — | DOCUMENTED, BETA |
| DELETE | `/v1/sessions/{session_id}` | Delete Session | — (not while running; removes record, events, sandbox and session-produced files) | — | DOCUMENTED, BETA |

**Session object** (`BetaManagedAgentsSession`, `type: "session"`):

| Field | Type | Notes |
|---|---|---|
| `id` | `sesn_…` | |
| `agent` | `SessionAgent` snapshot `{type:"agent", id, version, name, description, model, system, tools, mcp_servers, skills, multiagent}` | Configuration the session runs with (after overrides); `id`/`version` still identify the base agent |
| `environment_id` | string | |
| `status` | `idle`\|`running`\|`rescheduling`\|`terminated` | Aggregate of all threads |
| `title`, `metadata` | | |
| `budget` | `{type:"limit", max_list_cost:{amount (cents string), currency:"USD"}}` or null | See §13 |
| `resources[]` | `file` \| `github_repository` \| `memory_store` resource objects (each with `id` `sesrsc_…`) | memory_store resource echoes `mount_path`, `access`, `instructions`, snapshotted `name`/`description` |
| `vault_ids[]` | | Attached at creation |
| `outcome_evaluations[]` | `{type:"outcome_evaluation", outcome_id, description, iteration, result, explanation, completed_at}` | `result`: pending \| running \| evaluating \| satisfied \| needs_revision \| max_iterations_reached \| failed \| interrupted |
| `stats` | `{active_seconds, duration_seconds}` | active_seconds here sums per-thread activity |
| `usage` | `{input_tokens, output_tokens, cache_read_input_tokens, cache_creation{ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}, list_cost{amount,currency}, active_seconds, server_tool_use{web_search_requests, web_fetch_requests}}` | `usage.active_seconds` deduplicates overlapping threads and is what runtime cost is priced on; `web_fetch_requests` reads 0 (not metered) |
| `deployment_id` | string or null | Set when created by a deployment |
| `created_at`, `updated_at`, `archived_at` | | |

Override rules (`agent_with_overrides`): omit = inherit; `null`/`[]` = clear (except `model` never clearable → 400 `agent_model_required`; clearing `tools` fails while `skills` non-empty because skills need `read`; clearing `mcp_servers` fails while an `mcp_toolset` still references one); a value replaces in full (no merge). `effort` inside a `model` override is not applied (session runs at the model default). A `model` override also sets/clears `inference_geo`. Overrides never modify the agent resource; in multiagent sessions they apply to the coordinator and its `self` copies only.

### 6.1 Session resources

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/sessions/{session_id}/resources` | List Session Resources | `limit`, `page` | DOCUMENTED, BETA |
| POST | `/v1/sessions/{session_id}/resources` | Add Session Resource | body `{type:"file", file_id*, mount_path?}` (files only; repos and memory stores are creation-time only) | DOCUMENTED, BETA |
| GET | `/v1/sessions/{session_id}/resources/{resource_id}` | Get Session Resource | — | DOCUMENTED, BETA |
| POST | `/v1/sessions/{session_id}/resources/{resource_id}` | Update Session Resource | body `{authorization_token*}` (rotate a GitHub token) | DOCUMENTED, BETA |
| DELETE | `/v1/sessions/{session_id}/resources/{resource_id}` | Delete Session Resource | — (remove a file) | DOCUMENTED, BETA |

Resource variants: `file {file_id, mount_path}` (mounted read-only under `/mnt/session/uploads/<mount_path or file_id>`, ≤500 files/session; a new session-scoped `file_id` copy is created, not counted against storage limits), `github_repository {url (https://github.com/<owner>/<repo>, no .git), authorization_token (write-only), mount_path (default /workspace/<repo>), checkout {type:"branch",name} | {type:"commit",sha}}`, `memory_store {memory_store_id, access: read_write (default) | read_only, instructions (≤4,096)}` (≤8 stores/session; self-hosted environments accept **only** `memory_store` resources → file/repo → 400).

### 6.2 Session threads (multiagent)

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/sessions/{session_id}/threads` | List Session Threads | `limit`, `page` (includes primary; `parent_thread_id` null for primary) | DOCUMENTED, BETA |
| GET | `/v1/sessions/{session_id}/threads/{thread_id}` | Get Session Thread | — | DOCUMENTED, BETA |
| POST | `/v1/sessions/{session_id}/threads/{thread_id}/archive` | Archive Session Thread | thread must be idle (requires_action counts as idle) | DOCUMENTED, BETA |
| GET | `/v1/sessions/{session_id}/threads/{thread_id}/events` | List Session Thread Events | `limit`, `page` | DOCUMENTED, BETA |
| GET | `/v1/sessions/{session_id}/threads/{thread_id}/stream` | Stream Session Thread Events | `event_deltas[]` (SSE) — note path is `/threads/{id}/stream`, **not** `/events/stream` | DOCUMENTED, BETA |

**SessionThread** (`type: "session_thread"`): `id` (`sthr_…`), `session_id`, `parent_thread_id`, `agent` (`SessionThreadAgent` snapshot or `{type:"advisor", model}`), `status`, `stats {active_seconds, duration_seconds, startup_seconds}`, `usage` (same shape as session usage; per-thread `list_cost` excludes runtime cost and does not sum exactly to the session figure), timestamps.

---

## 7. Events (full catalogue)

Guide: https://platform.claude.com/docs/en/managed-agents/events-and-streaming · reference tabs: https://platform.claude.com/docs/en/managed-agents/reference#event-types · REST: `GET/POST /v1/sessions/{id}/events`, `GET /v1/sessions/{id}/events/stream`.

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/sessions/{session_id}/events` | List Events | `types[]` filter, `created_at[gt\|gte\|lt\|lte]`, `order`, `limit`, `page` → `data[]` of persisted events | DOCUMENTED, BETA |
| POST | `/v1/sessions/{session_id}/events` | Send Events | body `{events:[…]}` → `{data:[echoed events with ids]}`; returns as soon as queued | DOCUMENTED, BETA |
| GET | `/v1/sessions/{session_id}/events/stream` | Stream Events | SSE (`accept: text/event-stream`, `data: {json}` lines); query `event_deltas[]` ∈ {`agent.message`, `agent.thinking`} (≤100 values; other → 400) | DOCUMENTED, BETA |

Naming: persisted types follow `{domain}.{action}`; the stream-only previews `event_start`/`event_delta` are the exception. Every persisted event has `id` (`sevt_…`), `type`, `processed_at`.

### 7.1 Client → server (7 types; `POST …/events`, also `initial_events`)

| Event | Params | Notes |
|---|---|---|
| `user.message` | `content[]`: `text {text}`, `image {source: base64 \| url \| file}`, `document {source: base64 \| text \| url \| file, title?, context?}` (`redacted` blocks rejected) | Starts/continues work. Rejected with 400 while the session is at its budget |
| `user.interrupt` | `session_thread_id?` | Stops the agent; no stop reason of its own |
| `user.tool_confirmation` | `tool_use_id`* (1–128), `result`* `allow`\|`deny`, `deny_message?` (≤10,000, deny only) | For `agent.tool_use`/`agent.mcp_tool_use` with `evaluated_permission: "ask"`; several per request OK; server routes to the right thread |
| `user.custom_tool_result` | `custom_tool_use_id`*, `content[]` (`text`, `image`, `document`, `search_result {source,title,content[],citations{enabled}}`), `is_error?` | Answers `agent.custom_tool_use` |
| `user.define_outcome` | `description`*, `rubric`* `{type:"text",content}` \| `{type:"file",file_id}`, `max_iterations?` (default 3, max 20) | Agent starts immediately; echoed with `outcome_id` (`outc_…`); one outcome at a time (chain after terminal `span.outcome_evaluation_end`) |
| `user.tool_result` | `tool_use_id`*, `content[]`, `is_error?` | **Self-hosted environments only**: your worker returns agent-toolset results |
| `system.message` | `content[]` of `{type:"text", text}` (1–1000 items) | Appended as a `role:"system"` turn for this and later turns; at most one per request, must be last; while `requires_action`, only accepted trailing a tool-result event. Supported models: Claude Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5, Opus 4.8 — else 400 `model_does_not_support_mid_conversation_system`. Deployments' `initial_events` accept it; sessions' `initial_events` do not |

### 7.2 Server → client (37 variants in `BetaManagedAgentsStreamSessionEvents`; 35 persisted + 2 stream-only)

Echoes of the 7 client events above appear on the stream/history with server ids (`user.*`, `system.message`). The remaining server-originated types:

| Group | Event | Key fields | Description |
|---|---|---|---|
| agent | `agent.message` | `content[]` (`text` \| `redacted`) | Buffered response content; authoritative record for previews |
| agent | `agent.thinking` | — | Progress signal only (no thinking content) |
| agent | `agent.tool_use` | `name`, `input`, `evaluated_permission` (allow\|ask\|deny), `evaluation` (`{type:"always_allow"}` \| `{type:"always_ask"}` \| `{type:"auto", evaluated_permission:{type:allow\|ask\|deny, reason_code?}}`; absent when tool not enabled or on old events), `session_thread_id?` (cross-posted) | Pre-built tool call |
| agent | `agent.tool_result` | `tool_use_id`, `content[]`, `is_error` | e.g. `url_not_allowed` for blocked web_fetch; outputs >100,000 chars written to a sandbox file |
| agent | `agent.mcp_tool_use` | `mcp_server_name`, `name`, `input`, `evaluated_permission`, `evaluation`, `session_thread_id?` | |
| agent | `agent.mcp_tool_result` | `mcp_tool_use_id`, `content[]`, `is_error` | |
| agent | `agent.custom_tool_use` | `name`, `input`, `session_thread_id?` | Session idles with `requires_action` until `user.custom_tool_result`; no permission fields |
| agent | `agent.thread_context_compacted` | — | Context compaction happened |
| agent | `agent.thread_message_received` | `from_session_thread_id`, `from_agent_name?`, `content[]` | Message arrived from another thread (advice from `anthropic.advisor` arrives this way) |
| agent | `agent.thread_message_sent` | `to_session_thread_id`, `to_agent_name?`, `content[]` | This thread sent a message |
| session | `session.status_running` | — | Turn opens |
| session | `session.status_idle` | `stop_reason`: `{type:"end_turn"}` \| `{type:"requires_action", event_ids[]}` \| `{type:"retries_exhausted"}` \| `{type:"budget_reached"}` | |
| session | `session.status_rescheduled` | — | Transient error, retrying |
| session | `session.status_terminated` | — | Unrecoverable error or archived |
| session | `session.deleted` | — | Ends any stream |
| session | `session.updated` | `agent?`, `budget?`, `title?`, `metadata?` (only changed fields) | Applies from next turn |
| session | `session.error` | `error {type, message, retry_status {type: retrying\|exhausted\|terminal}, …}` | Types: `unknown_error`, `model_overloaded_error`, `model_rate_limited_error`, `model_request_failed_error`, `mcp_connection_failed_error {mcp_server_name}`, `mcp_authentication_failed_error {mcp_server_name}`, `billing_error`, `credential_host_unreachable_error {credential_id, vault_id}` |
| session | `session.usage` | `usage` (SessionUsageSnapshot), `budget` or null | Emitted immediately before every idle and when a thread pauses at budget |
| session | `session.thread_created` | `session_thread_id`, `agent_name` | |
| session | `session.thread_status_running` / `_idle {stop_reason}` / `_rescheduled` / `_terminated` | `session_thread_id`, `agent_name` | Emitted on the thread's own stream and cross-posted to the primary for child threads |
| span | `span.model_request_start` | — | |
| span | `span.model_request_end` | `model_request_start_id`, `is_error`, `model_usage {input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, speed}` | Also closes unreconciled previews |
| span | `span.outcome_evaluation_start` | `outcome_id`, `iteration` (0-indexed) | |
| span | `span.outcome_evaluation_ongoing` | `outcome_id`, `iteration` | Heartbeat |
| span | `span.outcome_evaluation_end` | `outcome_evaluation_start_id` (empty string if interrupted before start), `outcome_id`, `iteration`, `result` (satisfied \| needs_revision \| max_iterations_reached \| failed \| interrupted), `explanation`, `usage` | |
| preview | `event_start` | `event {type: agent.message \| agent.thinking, id}` | Stream-only, never persisted, no own id |
| preview | `event_delta` | `event_id`, `delta {type:"content_delta", index, content {type:"text", text}}` | Stream-only; only for `agent.message` (thinking previews are start-only) |

**Event deltas (previews)** — opt in per connection with `event_deltas[]=agent.message` (percent-encode `%5B%5D`). Sequence per model request: `span.model_request_start` → `event_start` → `event_delta`* → buffered `agent.message` (same `id`) → `span.model_request_end`. Accumulate keyed by `(event_id, index)`; the buffered event replaces the preview; close leftovers on `span.model_request_end`. Guarantees: concatenated deltas are a **prefix** of `content[index].text` (deltas may be shed under load); at most one `event_start` per id per connection. Limitations: best effort, no replay on reconnect, one thread and text only, never persisted. Wire format intentionally differs from Messages API streaming (no `content_block_start/stop`, delta type `content_delta` not `content_block_delta`).

Troubleshooting: no previews → connection didn't opt in or turn ran on another thread; 404 on stream → wrong path/id or missing beta header (thread endpoints are beta-gated); 400 naming `event_deltas` → only `agent.message`/`agent.thinking` accepted.

---

## 8. Environments (cloud sandboxes)

Guides: https://platform.claude.com/docs/en/managed-agents/environments · https://platform.claude.com/docs/en/managed-agents/cloud-sandboxes-reference

| Method | Path | Title | Key params | Pagination | Status |
|---|---|---|---|---|---|
| GET | `/v1/environments` | List Environments | `include_archived`, `limit`, `page` | cursor | DOCUMENTED, BETA |
| POST | `/v1/environments` | Create Environment | `name`*, `config` (`{type:"cloud", networking?, packages?}` \| `{type:"self_hosted"}` \| null), `description`, `metadata`, `scope` (`organization`\|`account`) | — | DOCUMENTED, BETA |
| GET | `/v1/environments/{environment_id}` | Get Environment | — | — | DOCUMENTED, BETA |
| POST | `/v1/environments/{environment_id}` | Update Environment | same fields; omitted config fields preserved; environments are **not versioned** | — | DOCUMENTED, BETA |
| POST | `/v1/environments/{environment_id}/archive` | Archive Environment | read-only; existing sessions continue; no new sessions | — | DOCUMENTED, BETA |
| DELETE | `/v1/environments/{environment_id}` | Delete Environment | only if no sessions reference it → `BetaEnvironmentDeleteResponse {type,id}` | — | DOCUMENTED, BETA |

**Environment object** (`BetaEnvironment`, `type: "environment"`): `id` (`env_…`), `name`, `description`, `metadata`, `scope`, `config`, `created_at`, `updated_at`, `archived_at`.

**Cloud config** (`BetaCloudConfig`):

| Field | Values | Notes |
|---|---|---|
| `networking.type` | `unrestricted` (default for API-created; general safety blocklist) \| `limited` | Controls sandbox egress only; **does not affect `web_search`/`web_fetch`** (Anthropic servers) — use per-tool `allowed_domains`/`blocked_domains`. Console-provisioned sandboxes default to `limited` |
| `networking.allowed_hosts[]` (limited) | bare hostnames or `*.example.com` wildcards; no scheme/port/path | |
| `networking.allow_mcp_servers` | bool, default false | egress to MCP servers declared on the agent |
| `networking.allow_package_managers` | bool, default false | egress to public registries; **required true when `packages` set** (else 400, even if registries listed) |
| `packages.{apt,cargo,gem,go,npm,pip}[]` | strings, optional version pins (`sqlalchemy==2.0.30`, `express@4.18.0`, `rails:7.1.0`, `hyperfine@1.18.0`, `…@latest`) | Installed before the agent starts, cached across sessions of the environment; managers run alphabetically (apt, cargo, gem, go, npm, pip) |

Sandbox spec: Ubuntu 24.04 LTS, x86_64, **up to 8 GB RAM, up to 10 GB disk**; each session gets a fresh isolated container (no shared filesystem between sessions). Pre-installed: Python 3.10–3.13 (pip/uv/poetry + NumPy, pandas, Matplotlib, openpyxl, python-docx, python-pptx, pypdf), Node 20/21/22 (npm/yarn/pnpm/bun), Go 1.24/1.25, Rust stable, OpenJDK 21, Ruby 3.1–3.3, PHP 8.3, GCC 13/Clang; PostgreSQL 16 and Redis 7 installed but not running; SQLite; git, curl, wget, jq, yq, tar/zip, tmux, make/cmake, docker (limited), ripgrep, vim/nano, ffmpeg, ImageMagick, pandoc, LibreOffice headless, Poppler + qpdf, tesseract (eng), TeX Live, Playwright (Python + Node) with Chromium at `/opt/pw-browsers` (`PLAYWRIGHT_BROWSERS_PATH` preset; no Firefox/WebKit). Paths: `/workspace` (default cwd, repos), `/mnt/session/uploads/` (mounted files, read-only), `/mnt/session/outputs/` (deliverables → Files API `scope_id=<session>`), `/mnt/memory/<slug>/` (memory stores).

---

## 9. Self-hosted sandboxes (work queue)

Guides: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes · https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security · reference "Self-hosted worker" CLI flags.

Model: orchestration and the model stay at Anthropic; tool execution (bash/read/write/edit/glob/grep, custom tools) runs on your host. A `self_hosted` environment is a **work queue**: each session assigned to it becomes a work item; your worker polls, claims, downloads skills to `<workdir>/skills/<name>/`, executes tool calls, posts results (`user.tool_result`) and stops. Workers authenticate with an **environment key** (`ANTHROPIC_ENVIRONMENT_KEY`, `sk-ant-oat01-…`, **generated in the Console only**), not your API key. Claimed work items may carry a per-session `secret` (required to mount memory stores; env key rejected by memory endpoints). Patterns: always-on poller (`ant beta:worker poll`, SDK `EnvironmentWorker.run()`), sandbox-per-session (`ant beta:worker poll --on-work spawn.sh` → `ant beta:worker run` or SDK `handle_item()`), webhook-triggered (wake on `session.status_run_started`).

| Method | Path | Title | Key params | Auth | Status |
|---|---|---|---|---|---|
| GET | `/v1/environments/{environment_id}/work` | List Work Items | `limit`, `page` → `{data[], next_page}` | API key or env key | DOCUMENTED, BETA |
| GET | `/v1/environments/{environment_id}/work/poll` | Poll for Work | `block_ms` (1–999; default non-blocking), `reclaim_older_than_ms` (default 5000); header `Anthropic-Worker-ID` (for `workers_polling`) → one `work` item | env key (worker) | DOCUMENTED, BETA |
| GET | `/v1/environments/{environment_id}/work/stats` | Get Queue Statistics | → `{type:"work_queue_stats", depth, pending, oldest_queued_at, workers_polling}` | API key (ops) | DOCUMENTED, BETA |
| GET | `/v1/environments/{environment_id}/work/{work_id}` | Get Work Item | — | | DOCUMENTED, BETA |
| POST | `/v1/environments/{environment_id}/work/{work_id}` | Update Work Item | body `metadata` patch (string upsert / null delete) | | DOCUMENTED, BETA |
| POST | `/v1/environments/{environment_id}/work/{work_id}/ack` | Acknowledge Work | queued → starting, removes from queue | env key | DOCUMENTED, BETA |
| POST | `/v1/environments/{environment_id}/work/{work_id}/heartbeat` | Record Heartbeat | query `desired_ttl_seconds`, `expected_last_heartbeat` (`NO_HEARTBEAT` for first; echo previous value; optimistic concurrency) → `{type:"work_heartbeat", last_heartbeat, lease_extended, state, ttl_seconds}` | env key | DOCUMENTED, BETA |
| POST | `/v1/environments/{environment_id}/work/{work_id}/stop` | Stop Work | body `force` (true = `stopped` immediately; default graceful → `stopping`, worker cancels in-flight tool call and confirms) | API key or env key | DOCUMENTED, BETA |

**WorkItem** (`BetaSelfHostedWork`, `type:"work"`): `id` (`work_…`), `environment_id`, `data {type:"session", id}`, `state` (`queued`\|`starting`\|`active`\|`stopping`\|`stopped`), `secret` (only populated on poll), `metadata`, `created_at`, `acknowledged_at`, `started_at`, `latest_heartbeat_at`, `stop_requested_at`, `stopped_at`.

CLI flags (`ant beta:worker`): `--environment-id`, `--environment-key`, `--workdir` (default `.`; system default `/workspace`), `--on-work <script>` (receives `ANTHROPIC_SESSION_ID`, `ANTHROPIC_WORK_ID`, `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_ENVIRONMENT_KEY`, optional `ANTHROPIC_BASE_URL`; work item JSON incl. `secret` on stdin), `--unrestricted-paths`, `--max-idle` (default 60s), `--log-format text|json`. SDK helpers: `EnvironmentWorker` (`run()`, `handle_item()`, `memory_sync_interval` default 15 s / min 5 s, `memory_sync_deletions` enabled|log_only|disabled), `work.poller()` (`drain`, `block_ms`, `reclaim_older_than_ms`, `auto_stop`), `client.beta.sessions.events.tool_runner()`, `AgentToolContext` (`allowed_roots`, `read_only_roots`) + `beta_agent_toolset_20260401(env)`. Host requirements: Linux with `/bin/bash`; TS SDK needs Node ≥22 + `unzip`/`tar`.

Differences vs cloud: no file/GitHub mounting (pass references in session `metadata`; the work item carries only the session id → `GET /v1/sessions/{id}`); outputs land in the working directory (no `/mnt/session/outputs` instruction); memory stores are downloaded to `/mnt/memory/<slug>` by the **SDK** worker (CLI worker does not mount them), synced every 15 s and at session end (store wins conflicts; marker file `.anthropic-memory-store`); `environment_variable` credentials not supported; web_search/web_fetch still run on Anthropic servers. Session stays `queued` (not failed) when no worker is connected. Custom tools can be served from the worker (`tools` factory) including wrapping a private MCP server as custom tools (declared, not discovered; names 1–128 chars, no `mcp__` prefix, no `$ref`/top-level `oneOf/anyOf/allOf` in schemas; permission policies do not apply).

Security (shared responsibility): Anthropic secures the control plane (queue integrity, multitenant isolation, context minimization). You own the sandbox image hardening, egress controls, environment-key storage/rotation (revocation validated on every request), per-session `secret` handling, tool blast radius, log retention, leftover memory copies, and read-only-store local integrity (bash can still modify the local copy). Anthropic cannot detect a leaked key, verify your image, isolate tools inside your sandbox, or enforce retention on your side.

---

## 10. Tools

Guide: https://platform.claude.com/docs/en/managed-agents/tools · https://platform.claude.com/docs/en/managed-agents/permission-policies

Tool config variants in `agent.tools[]`:

| `type` | Fields | Notes |
|---|---|---|
| `agent_toolset_20260401` | `default_config {enabled?, permission_policy?}`, `configs[]` per tool `{name, type?, enabled?, permission_policy?, …web settings}` | Enables the pre-built toolset; default policy `always_allow` |
| `mcp_toolset` | `mcp_server_name`*, `default_config {enabled?, permission_policy?}`, `configs[] {name, enabled?, permission_policy?}` (no `type`, no web settings) | Default policy `always_ask`; all server tools enabled by default |
| `custom` | `name`* (1–128; letters/digits/_/-; unique; not a built-in name; no `mcp__`), `description`* (non-empty), `input_schema`* `{type:"object", properties, required}` | Executed by your client via events |

Pre-built tools (`configs[].name`): `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Outputs >100,000 chars (~25k tokens) are written to a sandbox file with a truncated preview. `default_config.enabled=false` + per-tool `enabled:true` = allow-list.

Web tool settings (`web_search`/`web_fetch` entries): `allowed_domains` **or** `blocked_domains` (1–64 domains, 1–255 chars, plain ASCII hostnames, subdomains covered, no IPs/TLDs/localhost/`.local`/`.internal`, Punycode for IDN, `web_search` may carry a path suffix, `web_fetch` may not; duplicates rejected), `max_content_tokens` (web_fetch, positive int), `user_location` (web_search, `{type:"approximate", city?, region?, country?, timezone?}`). Not available vs Messages API: `max_uses`, `citations`, `cache_control`. Validated on agent create/update and session create/update (400 `invalid_request_error`), re-checked at first tool init (→ `session.error`, idle). Multiagent: allowlists intersect, blocklists union (roster agents can only narrow); grader runs without web tools; lists can be changed on an idle session via update.

Permission policies (`permission_policy.type`): `always_allow` · `always_ask` (pause, `session.status_idle` `requires_action`) · `auto` (server judges each call: run / deny with error tool result `Permission to use {tool} has been denied.` — client cannot override / ask). `user.message` content counts as your intent under `auto`; tool results, web pages, MCP responses and inter-thread messages do not. `auto` is not a human checkpoint. Confirming an event whose `evaluated_permission` is not `ask` → 400. Custom tools are never governed by policies. Running sessions keep the toolset they were created with (agent updates apply to new sessions; session-level update possible when idle).

---

## 11. MCP (connector and tunnels)

Guide: https://platform.claude.com/docs/en/managed-agents/mcp-connector · reference "Supported MCP server types" · tunnels: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/{overview,concepts,reference}

**Connector.** Declare servers on the agent (`mcp_servers[] {type:"url", name, url}`, ≤20) with a matching `mcp_toolset`; supply auth at session creation via `vault_ids` (credentials matched by normalized `mcp_server_url`: scheme/host lowercased, default ports and trailing slashes stripped; different path/subdomain/port ≠ match; no match → unauthenticated attempt; first vault with a match wins). Transport: streamable HTTP; deprecated SSE-only servers work through automatic fallback. Session creation does not validate connectivity — failures surface as `session.error` `mcp_connection_failed_error` / `mcp_authentication_failed_error` with `mcp_server_name` and `retry_status`; retried on the next idle→running transition. MCP tool outputs >100,000 chars → sandbox file.

**Tunnels** (research preview): a tunnel stack in your network (Cloudflare `cloudflared` outbound connector + Anthropic proxy terminating inner TLS and routing by hostname) exposes private MCP servers under `<sub>.<tunnel domain>`; Anthropic verifies the proxy's server certificate against a CA you register (≤2 non-archived certificates; PEM, exactly one X.509 cert, ≤8 KB). Credentials: tunnel token (connector) + server cert; programmatic (WIF, `workspace:manage_tunnels`) or manual (Console) provisioning. Self-hosting and tunnels are independent (cloud session can use a tunnel; self-hosted session can use public or tunneled servers).

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/tunnels` | List Tunnels | `include_archived`, `limit`, `page` | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/tunnels` | Create Tunnel | `display_name?` (1–255); allocates a fresh hostname (not idempotent); rejects traffic until a CA cert is added | DOCUMENTED, BETA, PREVIEW |
| GET | `/v1/tunnels/{tunnel_id}` | Get Tunnel | — | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/tunnels/{tunnel_id}/archive` | Archive Tunnel | irreversible; archives certs, retires hostname forever, invalidates token | DOCUMENTED, BETA, PREVIEW |
| GET | `/v1/tunnels/{tunnel_id}/certificates` | List Tunnel Certificates | `include_archived`, `limit`, `page` | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/tunnels/{tunnel_id}/certificates` | Create Tunnel Certificate | `ca_certificate_pem`* | DOCUMENTED, BETA, PREVIEW |
| GET | `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}` | Get Tunnel Certificate | — | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive` | Archive Tunnel Certificate | archiving the last cert is allowed (tunnel rejects traffic) | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/tunnels/{tunnel_id}/reveal_token` | Reveal Tunnel Token | POST so the token stays out of access logs; fetched live, not stored | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/tunnels/{tunnel_id}/rotate_token` | Rotate Tunnel Token | `reason?`; existing connections not severed | DOCUMENTED, BETA, PREVIEW |
| GET/POST | `/v1/organizations/tunnels[/{id}][/archive \| /certificates… \| /reveal_token \| /rotate_token]` | Admin API (legacy) | same shapes + `workspace_id` filter/field; beta `mcp-tunnels-2026-05-19`, scope `org:manage_tunnels` | DOCUMENTED, BETA, DEPRECATED (migration window) |

Objects: **Tunnel** `{type:"tunnel", id (tnl_…), domain (globally unique, never reused), display_name, created_at, archived_at}`; **TunnelCertificate** `{type:"tunnel_certificate", id (tcrt_…), tunnel_id, fingerprint (sha256 hex), expires_at, created_at, archived_at}`; **TunnelToken** `{type:"tunnel_token", id (changes on rotation), tunnel_token}`.

---

## 12. Skills

Guide: https://platform.claude.com/docs/en/managed-agents/skills

Two attachment paths: (1) `agent.skills[]` entries `{type:"anthropic", skill_id: "pptx"|"xlsx"|"docx"|"pdf"…, version?}` or `{type:"custom", skill_id:"skill_…", version?}` (custom skills uploaded once via `POST /v1/skills` multipart `files[]` — Skills API, not Files API; `display_name` ≤255 optional); (2) **repository skills**: a mounted `github_repository` is scanned once at session start for `.claude/skills/<name>/SKILL.md` (exactly one level deep at the repo root; requires the `read` tool; cloud sandboxes only). Limits: ≤500 skills per session (deduplicated across all agents); more skills = slower sandbox start and more context. Skills require the `read` tool (clearing `tools` while skills are set → 400). Executable bits in bundles are preserved by the CLI/SDK workers. Trust warning: repo skills are agent instructions loaded without review.

---

## 13. Budgets, outcomes and limits

Guides: https://platform.claude.com/docs/en/managed-agents/budgets · https://platform.claude.com/docs/en/managed-agents/define-outcomes

**Session budget** (`budget: {type:"limit", max_list_cost:{amount, currency}}`): hard ceiling on the session's **list cost** (everything priced at public list rates — model tokens at list price, **web searches $10 per 1,000**, **session running time $0.08 per hour**). `amount` = whole US cents as a string with no leading zeros (`"2500"` = $25.00; `"25.00"` rejected; >0); `USD` only. Enforced **between** model requests (the crossing request finishes → final cost may land a fraction past the cap; overshoot bounded by one request per thread). At cap: threads pause, stream shows `session.thread_status_idle{budget_reached}` per thread → `session.usage` → `session.status_idle{budget_reached}`; only settle events accepted (`user.tool_confirmation`, `user.tool_result`, `user.custom_tool_result`, `user.interrupt`), `user.message` → 400. A pending `requires_action` outranks `budget_reached` at session level. Resume by updating `budget` (new cap must be strictly greater than consumed list cost, base it on `usage.list_cost` + ≥1 cent) or `"budget": null` (one-way removal). Attach only at creation (400 to add later / re-add). Multiagent: one shared cap; advisor consultations count. Models without a public list price → 400 on budgeted create; if usage later includes one, the budget can no longer measure and must be removed. Reported `list_cost` is rounded to whole cents; enforcement uses the exact value. Distinct from Messages API task budgets (advisory, token-denominated). Deployment budgets copy onto each run and **can** be cleared and re-set.

Budget error table (400): work-starting event at cap · cap ≤ consumed · budget added/re-added · bad `amount`/`currency` · model with no list price.

**Outcomes** (`user.define_outcome`): the harness provisions a **grader** (separate context, no web tools) that scores the deliverable against the rubric (markdown text inline or Files API file) up to `max_iterations` (default 3, max 20) evaluate→revise cycles. Events `span.outcome_evaluation_start/ongoing/end`; `end.result` ∈ satisfied (→ idle) · needs_revision (new cycle) · max_iterations_reached (one acknowledgment turn then idle) · failed (rubric doesn't apply) · interrupted. Poll `GET /v1/sessions/{id}` `outcome_evaluations[].result` (pending → running → evaluating → terminal). Deliverables are written to `/mnt/session/outputs/` → `GET /v1/files?scope_id=<session_id>` (needs the managed-agents beta header) then `GET /v1/files/{file_id}/content`; files can appear a few seconds after idle.

**Documented limits (quoted):**

| Limit | Value |
|---|---|
| Create endpoints rate limit | 300 requests/min per organization |
| Read endpoints rate limit | 1,200 requests/min per organization |
| `initial_events` per session / deployment | 50 |
| Files per session | 500 (resources per deployment also max 500) |
| Memory stores per session | 8 |
| Skills per session | 500 (deduplicated) |
| Tools per agent | 128 across toolsets |
| MCP servers per agent | 20 |
| Multiagent roster | 20 unique agents; 25 concurrent threads (advisor exempt); one delegation level |
| Custom tool name | 1–128 chars; property names 1–64 |
| Domain lists | 1–64 domains per list, each 1–255 chars |
| `system` override | ≤100,000 chars |
| Tool output inline | 100,000 chars, then written to file |
| Request body (create with initial_events) | 32 MB → 413 |
| Sandbox | 8 GB RAM, 10 GB disk, state retained 30 days after creation |
| Scheduled deployments per org | 1,000 |
| Deployment `vault_ids` | 50 |
| Credentials per vault | 20 |
| Memory: memory size / memories per store / path / instructions | 100 kB / 10,000 / 1,024 bytes / 4,096 chars; versions retained 30 days (head versions kept) |
| Dreams | 100 sessions per dream; `instructions` 4,096 chars |
| Metadata maps | 16 pairs, keys ≤64, values ≤512 |
| `system.message` content | 1–1000 text items |
| Webhook payload freshness | 5 minutes; ≤3 delivery attempts, 5–120 s backoff |

---

## 14. Vaults and credentials

Guide: https://platform.claude.com/docs/en/managed-agents/vaults

Workspace-scoped stores of per-end-user credentials referenced by `vault_ids` at session/deployment creation. Secret fields (`token`, `access_token`, `refresh_token`, `client_secret`, `secret_value`) are write-only.

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/vaults` | List Vaults | `include_archived`, `limit`, `page` (newest first) | DOCUMENTED, BETA |
| POST | `/v1/vaults` | Create Vault | `display_name`*, `metadata` | DOCUMENTED, BETA |
| GET | `/v1/vaults/{vault_id}` | Get Vault | — | DOCUMENTED, BETA |
| POST | `/v1/vaults/{vault_id}` | Update Vault | `display_name`, `metadata` | DOCUMENTED, BETA |
| POST | `/v1/vaults/{vault_id}/archive` | Archive Vault | cascades to credentials; secrets purged, records kept; new sessions fail, running continue | DOCUMENTED, BETA |
| DELETE | `/v1/vaults/{vault_id}` | Delete Vault | hard delete | DOCUMENTED, BETA |
| GET | `/v1/vaults/{vault_id}/credentials` | List Credentials | `include_archived`, `limit`, `page` | DOCUMENTED, BETA |
| POST | `/v1/vaults/{vault_id}/credentials` | Create Credential | `auth`* (variant below), `display_name`, `metadata` | DOCUMENTED, BETA |
| GET | `/v1/vaults/{vault_id}/credentials/{credential_id}` | Get Credential | — | DOCUMENTED, BETA |
| POST | `/v1/vaults/{vault_id}/credentials/{credential_id}` | Update Credential | rotate secrets, `display_name`, `injection_location` (merge per field); structural fields immutable | DOCUMENTED, BETA |
| POST | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` | Archive Credential | purges secret; key freed for a replacement | DOCUMENTED, BETA |
| DELETE | `/v1/vaults/{vault_id}/credentials/{credential_id}` | Delete Credential | hard delete | DOCUMENTED, BETA |
| POST | `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` | Validate Credential | → `vault_credential_validation {status: valid\|invalid\|unknown, has_refresh_token, mcp_probe {method, http_response{status_code, content_type, body, body_truncated}}, refresh {status: succeeded\|failed\|connect_error\|no_refresh_token, http_response}, validated_at}` | DOCUMENTED, BETA |

**Vault** `{type:"vault", id (vlt_…), display_name, metadata, created_at, updated_at, archived_at}`. **Credential** `{type:"vault_credential", id (vcrd_…), vault_id, display_name, metadata, auth, timestamps}` with `auth` variants:

| `auth.type` | Create fields | Response fields | Semantics |
|---|---|---|---|
| `mcp_oauth` | `mcp_server_url`*, `access_token`*, `expires_at`, `refresh {token_endpoint*, client_id*, refresh_token*, token_endpoint_auth {type: none \| client_secret_basic \| client_secret_post, client_secret}, scope, resource}` | `mcp_server_url`, `expires_at`, `refresh {client_id, token_endpoint, token_endpoint_auth, scope, resource}` | Injected when the agent connects to that URL; Anthropic refreshes on expiry; `vault_credential.refresh_failed` webhook on failure |
| `static_bearer` | `mcp_server_url`*, `token`* | `mcp_server_url` | Fixed bearer token |
| `environment_variable` | `secret_name`*, `secret_value`*, `networking`* `{type:"unrestricted"}` \| `{type:"limited", allowed_hosts[] (hostname, IPv4, `*.` wildcard)}`, `injection_location {header, body}` (omitted fields false when object given; both true when omitted) | `secret_name`, `networking`, `injection_location {header, body}` | Sandbox sees an opaque placeholder; substituted at egress only on allowed hosts and enabled locations; environment networking must also allow the host (else `credential_host_unreachable_error`); breaks clients that validate/sign the secret locally (e.g. SigV4); tokens fetched with it arrive unredacted; **not supported on self-hosted sandboxes**; Console-created credentials are header-only |

Constraints: `mcp_server_url` / `secret_name` unique among active credentials in a vault (409 on duplicate) and immutable; ≤20 credentials per vault. Credentials are re-resolved periodically during sessions (rotation/archival propagate without restart) and are not validated until runtime. Multiagent: vault credentials apply to every thread.

---

## 15. Scheduled deployments and runs

Guide: https://platform.claude.com/docs/en/managed-agents/scheduled-deployments

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/deployments` | List Deployments | `agent_id`, `status` (active\|paused), `include_archived`, `created_at[gte\|lte]`, `limit`, `page` | DOCUMENTED, BETA |
| POST | `/v1/deployments` | Create Deployment | `name`*, `agent`* (id or `{type:"agent",id,version}`), `environment_id`*, `initial_events`* (1–50: `user.message` \| `user.define_outcome` \| `system.message`), `schedule` `{type:"cron", expression, timezone}` or null, `budget`, `resources[]` (≤500), `vault_ids[]` (≤50), `description`, `metadata` | DOCUMENTED, BETA |
| GET | `/v1/deployments/{deployment_id}` | Get Deployment | — | DOCUMENTED, BETA |
| POST | `/v1/deployments/{deployment_id}` | Update Deployment | any field; `budget: null` clears (re-settable) | DOCUMENTED, BETA |
| POST | `/v1/deployments/{deployment_id}/pause` | Pause Deployment | suppresses scheduled triggers; `paused_reason {type:"manual"}`; manual runs still allowed | DOCUMENTED, BETA |
| POST | `/v1/deployments/{deployment_id}/unpause` | Unpause Deployment | resumes from next occurrence; no backfill | DOCUMENTED, BETA |
| POST | `/v1/deployments/{deployment_id}/archive` | Archive Deployment | terminal | DOCUMENTED, BETA |
| POST | `/v1/deployments/{deployment_id}/run` | Run Deployment Now | creates a session immediately → `deployment_run` with `trigger_context.type:"manual"` (no `deployment_run.*` webhooks for manual runs) | DOCUMENTED, BETA |
| GET | `/v1/deployment_runs` | List Deployment Runs | `deployment_id`, `has_error`, `trigger_type` (schedule\|manual), `created_at[gt\|gte\|lt\|lte]`, `limit`, `page` | DOCUMENTED, BETA |
| GET | `/v1/deployment_runs/{deployment_run_id}` | Get Deployment Run | — | DOCUMENTED, BETA |

**Deployment** (`type:"deployment"`, `id depl_…`): `name`, `description`, `agent {type:"agent", id, version}` (resolved), `environment_id`, `initial_events[]`, `resources[]` (echo minus write-only tokens), `vault_ids[]`, `budget`, `schedule {type:"cron", expression, timezone, last_run_at, upcoming_runs_at[] (≤5)}`, `status` (`active`\|`paused`), `paused_reason` (`{type:"manual"}` \| `{type:"error", error{type,message}}`), `metadata`, timestamps. Cron: 5-field POSIX, minute granularity, IANA timezone, literal wall-clock matching (non-existent spring-forward times skipped; fall-back duplicates fire twice); execution jitter up to 15% of the interval (min 5 s, max 9 min). Max 1,000 deployments per org.

**DeploymentRun** (`type:"deployment_run"`, `id drun_…`): `deployment_id`, `agent {id, version}`, `trigger_context` (`{type:"schedule", scheduled_at}` \| `{type:"manual"}`), `session_id` xor `error {type, message}`. Error types: `environment_archived_error`, `agent_archived_error`, `environment_not_found_error`, `vault_not_found_error`, `vault_archived_error`, `file_not_found_error`, `memory_store_archived_error`, `skill_not_found_error`, `session_resource_not_found_error`, `workspace_archived_error`, `organization_disabled_error`, `session_rate_limited_error` (no retry; schedule keeps firing), `session_creation_rejected_error`, `self_hosted_resources_unsupported_error`, `mcp_egress_blocked_error`, `unknown_error`. Failure behavior: agent archived → deployment archived (no run recorded); agent deleted → archived at next trigger; archived subagent/environment/vault → failed run + auto-pause (`paused_reason.error.type` mirrors the run error).

---

## 16. Memory stores, memories, versions

Guide: https://platform.claude.com/docs/en/managed-agents/memory · beta header **`agent-memory-2026-07-22`** on all `/v1/memory_stores/**` calls (not combined with the managed-agents header).

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/memory_stores` | List memory stores | `include_archived`, `created_at[gte\|lte]`, `limit`, `page` | DOCUMENTED, BETA |
| POST | `/v1/memory_stores` | Create a memory store | `name`* (1–255; slug → `/mnt/memory/<slug>`), `description` (≤1,024, shown to agent), `metadata` | DOCUMENTED, BETA |
| GET | `/v1/memory_stores/{memory_store_id}` | Retrieve a memory store | — | DOCUMENTED, BETA |
| POST | `/v1/memory_stores/{memory_store_id}` | Update a memory store | `name`, `description`, `metadata` | DOCUMENTED, BETA |
| POST | `/v1/memory_stores/{memory_store_id}/archive` | Archive a memory store | read-only, cannot attach; one-way | DOCUMENTED, BETA |
| DELETE | `/v1/memory_stores/{memory_store_id}` | Delete a memory store | removes memories + versions | DOCUMENTED, BETA |
| GET | `/v1/memory_stores/{memory_store_id}/memories` | List memories | `path_prefix` (must end with `/`), `depth` (0 = subtree, 1 = children → `memory_prefix` roll-ups), `view` (basic\|full), `limit`, `page`; stable server order | DOCUMENTED, BETA |
| POST | `/v1/memory_stores/{memory_store_id}/memories` | Create a memory | `path`*, `content`*; `view` query; does not overwrite | DOCUMENTED, BETA |
| GET | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | Retrieve a memory | `view` | DOCUMENTED, BETA |
| POST | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | Update a memory | `content`, `path` (rename), `precondition {type:"content_sha256", content_sha256}` (optimistic concurrency) | DOCUMENTED, BETA |
| DELETE | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | Delete a memory | `expected_content_sha256` query | DOCUMENTED, BETA |
| GET | `/v1/memory_stores/{memory_store_id}/memory_versions` | List memory versions | `memory_id`, `operation` (created\|modified\|deleted), `session_id`, `api_key_id`, `service_account_id`, `created_at[gte\|lte]`, `view`, `limit`, `page` (newest first) | DOCUMENTED, BETA |
| GET | `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}` | Retrieve a memory version | `view` (adds `content`) | DOCUMENTED, BETA |
| POST | `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact` | Redact a memory version | scrubs content, keeps audit trail; the current head of a live memory cannot be redacted | DOCUMENTED, BETA |

Objects: **MemoryStore** `{type:"memory_store", id memstore_…, name, description, metadata, timestamps, archived_at}`; **Memory** `{type:"memory", id mem_…, memory_store_id, path (starts with /, case-sensitive, unique, ≤1,024 bytes), content (≤100 kB; null when view=basic), content_sha256, content_size_bytes, memory_version_id, created_at, updated_at}`; **MemoryPrefix** `{type:"memory_prefix", path}`; **MemoryVersion** `{type:"memory_version", id memver_…, memory_id, memory_store_id, operation, path, content, content_sha256, content_size_bytes, created_by (session_actor{session_id} \| api_actor{api_key_id} \| user_actor{user_id} \| service_account_actor{service_account_id}), created_at, redacted_at, redacted_by}`. No restore endpoint (write a version's content back). Store full (10,000) → new writes fail. Security: `read_write` default is a prompt-injection sink — use `read_only` for reference material.

---

## 17. Dreams, webhooks, GitHub, files, user profiles

### 17.1 Dreams (research preview)

Guide: https://platform.claude.com/docs/en/managed-agents/dreams · headers `anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21` on dream endpoints.

A **dream** is an asynchronous job that reads one memory store plus 1–100 past session transcripts and produces a **new, reorganized output memory store** (duplicates merged, stale entries replaced, insights surfaced); the input store is never modified (default `output_behavior {type:"create_new"}`; `{type:"update_existing", memory_store_id}` consolidates in place — EAP, must be the input store). Supported models: `claude-opus-5`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`, `claude-sonnet-4-6`. Billed at standard token rates for the chosen model.

| Method | Path | Title | Key params | Status |
|---|---|---|---|---|
| GET | `/v1/dreams` | List Dreams | `statuses[]`, `include_archived`, `created_at[gt\|lt]`, `limit` (default 20, max 100), `page` | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/dreams` | Create a Dream | `inputs`* [`{type:"memory_store", memory_store_id}`, `{type:"sessions", session_ids[]}`], `model`* (string or `{id, speed}`), `instructions` (≤4,096), `output_behavior` | DOCUMENTED, BETA, PREVIEW |
| GET | `/v1/dreams/{dream_id}` | Get a Dream | — | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/dreams/{dream_id}/cancel` | Cancel a Dream | pending/running → canceled; idempotent on canceled; 400 on completed/failed | DOCUMENTED, BETA, PREVIEW |
| POST | `/v1/dreams/{dream_id}/archive` | Archive a Dream | terminal states only (400 otherwise); no unarchive | DOCUMENTED, BETA, PREVIEW |

**Dream** `{type:"dream", id drm_…, status (pending\|running\|completed\|failed\|canceled), inputs[], outputs[] ({type:"memory_store", memory_store_id}; may be briefly empty while running), model {id, speed}, instructions, output_behavior, session_id (underlying pipeline session — streamable; archived at end), usage {input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens}, error {type, message} (timeout, internal_error, memory_store_org_limit_exceeded, input_memory_store_too_large, input_memory_store_unavailable, input_session_unavailable), created_at, ended_at, archived_at}`.

### 17.2 Webhooks

Guide: https://platform.claude.com/docs/en/managed-agents/webhooks · reference: https://platform.claude.com/docs/en/api/beta/webhooks

Registered in Console (**Manage > Webhooks**): HTTPS on port 443, public hostname, subscribed `data.type` list, 32-byte `whsec_` signing secret shown once. Payload envelope: `{type:"event", id:"whe_…", created_at, data:{type, id (resource id), organization_id, workspace_id, session_thread_id? (thread events), vault_id? (credential events)}}` — fetch the resource with GET; `.deleted` events are final. Verify with headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (SDK `unwrap()`; rejects payloads older than 5 minutes; `webhook-timestamp` regenerated per attempt). Delivery: any 2xx acknowledges; up to 3 attempts, jittered 5–120 s backoff, then dropped (not a durable log); duplicates possible (dedupe on `event.id` = `webhook-id`); **no ordering guarantee**; no backfill for late subscriptions; auto-disable on 3xx (never followed), non-public IP, or sustained failures (re-enable in Console).

Event types (44 in the reference union; 42 in the guide tables):

| Family | Types |
|---|---|
| session | `session.status_run_started` (stream twin `session.status_running`), `session.status_idled` (twin `session.status_idle`), `session.budget_reached` (once per budget value), `session.status_rescheduled`, `session.status_terminated`, `session.thread_created`, `session.thread_idled`, `session.thread_terminated` (child threads only), `session.outcome_evaluation_ended`, `session.updated`, `session.deleted`; **reference-only, not in the guide**: `session.created`, `session.pending`, `session.running`, `session.idled`, `session.requires_action`, `session.archived` |
| vault | `vault.created`, `vault.archived`, `vault.deleted`, `vault_credential.created`, `vault_credential.archived`, `vault_credential.deleted`, `vault_credential.refresh_failed` |
| agent (resource lifecycle) | `agent.created`, `agent.updated` (new version only), `agent.archived`, `agent.deleted` |
| deployment | `deployment.created`, `deployment.updated`, `deployment.paused`, `deployment.unpaused`, `deployment.archived`, `deployment.deleted` |
| deployment_run | `deployment_run.started`, `deployment_run.succeeded`, `deployment_run.failed` (scheduled runs only; `data.id` = run id) |
| environment | `environment.created`, `environment.updated`, `environment.archived`, `environment.deleted` (work items emit none) |
| memory_store | `memory_store.created` (incl. dream clones), `memory_store.archived`, `memory_store.deleted` (no per-memory events) |

### 17.3 GitHub

Guide: https://platform.claude.com/docs/en/managed-agents/github. Mount repos as `github_repository` resources (fields in §6.1; repos cached for faster starts; token scopes: `repo` for private clone/PRs, `repo`/`public_repo` for issues; use fine-grained PATs); rotate the token via `POST /v1/sessions/{id}/resources/{resource_id}` `{authorization_token}`; repos are attached for the session's lifetime (new session to change). Pair with the GitHub MCP server (`https://api.githubcopilot.com/mcp/`) declared on the agent + credential in a vault to create branches/PRs. Cloud sandboxes only.

### 17.4 Files

Guide: https://platform.claude.com/docs/en/managed-agents/files. Upload via Files API (`POST /v1/files` multipart), mount via `resources[] {type:"file", file_id, mount_path}` (→ `/mnt/session/uploads/<mount_path>`; default `/mnt/session/uploads/<file_id>`; read-only copies; parents auto-created; ≤500/session), add/remove on a running session via session resources. Session outputs written to `/mnt/session/outputs/` are listed with `GET /v1/files?scope_id=<session_id>` (requires `anthropic-beta: managed-agents-2026-04-01`) and downloaded with `GET /v1/files/{id}/content`; session-produced files are deleted with the session, uploaded files are not.

### 17.5 User profiles (separate beta, listed for completeness)

`/v1/user_profiles` (list `order`, `order_by` created_at\|name; create/update `access_type` application\|passthrough, `external_id` or `external_user_details`, `external_user_onboarded_at`, `metadata`, `name`; retrieve; `POST /v1/user_profiles/{id}/enrollment_url` → `{type:"enrollment_url", url, expires_at}`) returns `BetaUserProfile {type:"user_profile", id uprof_…, trust_grants{…}, …}`. Beta headers `user-profiles-2026-09-04` (older `-03-24`, `-08-18`). **No Managed Agents guide references user profiles** (grep of the 27 pages: zero hits); they are documented here only because the slug was in scope. Status: DOCUMENTED, BETA.

---

## 18. Pricing, availability, migration notes, gotchas

**Pricing facts quoted from the docs** (no dedicated Managed Agents pricing page exists in the downloaded set; these are the only figures stated):

| Item | Documented figure | Source |
|---|---|---|
| Model tokens | "at each served model's list price" | budgets |
| Web searches | "$10 per 1,000 searches" | budgets |
| Session running time | "$0.08 per hour" (priced on `usage.active_seconds`, overlapping threads counted once) | budgets, events-and-streaming |
| Web fetch | "no per-request charge and aren't metered" (`web_fetch_requests` reads 0) | budgets |
| Advisor consultations | "billed at the advisor model's rates" | multiagent |
| Dreams | "standard API token rates for the model you select" | dreams |
| Fast mode (`speed: fast`) | "premium pricing" | reference schema |
| Prompt caching | 5-minute TTL by default; `cache_creation.ephemeral_5m/1h_input_tokens` reported | events-and-streaming |
| Skills | "a modest cost on the session's context window" | skills |
| Discounts | List cost ≠ contracted price; budgets enforce at list rates | budgets |

**Availability / regions**: `model.inference_geo` `"us"` or `"global"` pinning (data residency; validated against workspace `allowed_inference_geos`); Claude Platform on AWS supports Managed Agents with feature differences (IAM auth for workers; no memory stores on self-hosted there). Not ZDR/HIPAA-BAA eligible. Console features: visual agent builder (onboarding), session viewer (Developers/Admins), `ant beta:sessions connect`.

**Branding**: partners may use "Claude Agent", "Claude" (within an "Agents" menu), "{Name} Powered by Claude"; not "Claude Code", "Claude Cowork" or Claude Code-styled ASCII art.

**Migration notes**: model upgrades are a one-field `model` change on the agent (new version, next sessions); `max_tokens`/`thinking` are runtime-managed (not exposed); assistant prefill does not exist; tool argument JSON is parsed before you see `agent.custom_tool_use`. CLI `ant apply` syncs agent/environment/skill files and records IDs in `claude-lock.json`.

**Gotchas / contradictions found while cross-reading (2026-09-18):**

1. Memory store calls need `agent-memory-2026-07-22` and **reject** the pair with `managed-agents-2026-04-01`; the REST reference pages only show a generic `anthropic-beta` header. Dreams need both `managed-agents-2026-04-01` and `dreaming-2026-04-21`.
2. Webhook names differ from stream names (`session.status_idled` vs `session.status_idle`, `session.status_run_started` vs `session.status_running`, `session.thread_idled` vs `session.thread_status_idle`). The reference union lists six extra webhook types (`session.created`, `session.pending`, `session.running`, `session.idled`, `session.requires_action`, `session.archived`) that the guide never describes — treated as UNVERIFIED in the fragment.
3. Thread stream path is `/threads/{thread_id}/stream` (no `/events/stream` at thread level); the ref JSON slug is `sessions__threads__events__stream` but the path has no `/events`.
4. Two ID prefixes appear for threads: `sthr_` (reference) and `sth_` (guide example JSON).
5. `sessions.update` documents `vault_ids` but the reference says it is reserved and rejected.
6. `sessions.resources.add` only accepts `file`; `retrieve`/`update` examples return a `github_repository`; repos and memory stores are creation-time only.
7. Deployments' `initial_events` accept `system.message`; sessions' do not.
8. `effort` inside a session-level `model` override is silently not applied.
9. Poll header `Anthropic-Worker-ID` is optional but `workers_polling` in stats is null/0 without it.
10. `environment_variable` credentials are cloud-only; self-hosted sandboxes accept only `memory_store` resources (files/repos → 400); the CLI worker cannot mount memory stores (SDK worker required).
11. Environments are not versioned; sessions keep the agent snapshot (`session.agent`) but only reference `environment_id`.
12. Session budgets cannot be added after creation and removal is one-way; deployment budgets can be cleared and re-set.
13. Interrupt has no dedicated stop reason (`end_turn`); an interrupt while paused at budget is silently ignored.
14. Reference marks `stop_reason` variant `retries_exhausted`, which the guide tables omit.

---

## 19. Examples (docs-only, UNVERIFIED until the parent agent runs them)

| File | Language | Flow |
|---|---|---|
| `examples/anthropic/agents/create_agent_session_stream.sh` | bash (curl + jq) | create agent (`claude-haiku-4-5-20251001`, no tools) → cloud env (limited) → session (budget 5 ¢) → open SSE → `user.message` "Reply with OK." → until `session.status_idle` → DELETE session, archive agent, DELETE/archive env (EXIT trap) |
| `examples/anthropic/agents/create_agent_session_stream.py` | Python (`scripts.live.anthropic_request`, `stream=True`) | same |
| `examples/anthropic/agents/create_agent_session_stream.ts` | TypeScript (raw fetch, `node --env-file=.env --experimental-strip-types`) | same |

Expected stream sequence for the trivial prompt (per docs): `user.message` → `session.status_running` → `session.thread_status_running` → `span.model_request_start` → `agent.message` → `span.model_request_end` → `session.thread_status_idle{end_turn}` → `session.usage` → `session.status_idle{end_turn}`.

---

## Live verification (2026-09-18, regular API key, model `claude-haiku-4-5-20251001`, cost ≈ $0.001)

Raw sanitized transcripts: `tmp-live/platform-anthropic/agents-probes.json` (list probes + first attempt) and `agents-probes-2.json` (full round-trip). Everything created was deleted/archived (session deleted, agent archived, environment archived then deleted).

| Step | Call | Beta header | HTTP | Observation |
|---|---|---|---|---|
| list agents / sessions / environments / vaults / deployments / deployment_runs | `GET …?limit=1` | `managed-agents-2026-04-01` | **200** | `{"data": []}` (environments also `next_page: null`) → **LIVE_VERIFIED** |
| list memory stores | `GET /v1/memory_stores?limit=1` | `agent-memory-2026-07-22` | **200** | `{"data": []}` |
| list tunnels | `GET /v1/tunnels?limit=1` | `mcp-tunnels-2026-06-22` | **401** `authentication_error "Authentication failed"` | ACCOUNT_RESTRICTED (tunnel endpoints need a `workspace:manage_tunnels`-scoped credential / not a plain API key) |
| list dreams | `GET /v1/dreams?limit=1` | `dreaming-2026-04-21` | **404** `not_found_error "not found"` | FAILED_VERIFICATION — not enabled for this account (gated preview) |
| list user profiles | `GET /v1/user_profiles?limit=1` | `user-profiles-2026-08-18` | **404** `not_found_error "not found"` | FAILED_VERIFICATION — gated |
| agents without beta header | `GET /v1/agents?limit=1` | — | **400** `invalid_request_error "Failed to parse request body: unknown field \"limit\""` | the header is mandatory (the route exists but parses differently) |
| create environment | `POST /v1/environments {"name": "atlas-platform-agent-env", "config": {"type": "cloud"}}` | MA | **200** | defaults filled: `config.networking {type: unrestricted}`, `config.packages {pip:[],npm:[],apt:[],cargo:[],gem:[],go:[]}`, `scope: organization`, `state: active` |
| create agent | `POST /v1/agents {"model": "claude-haiku-4-5-20251001", "name": "atlas-platform-agent-min", "system": "Reply with OK and nothing else.", "tools": []}` | MA | **200** | `version: 1`, `model: {"id": "claude-haiku-4-5-20251001", "speed": "standard"}`, `mcp_servers: []`, `skills: []`, `multiagent: null` |
| retrieve agent / list versions | `GET` | MA | 200 / 200 | versions list = `{"data": [ <version 1> ]}` |
| create session (wrong budget) | `POST /v1/sessions … "max_list_cost": {"amount": 5, …}` | MA | **400** `"Failed to parse request body: invalid value for string field amount: 5"` | `amount` is a **string of cents** (`"20"` = $0.20) |
| create session | `POST /v1/sessions {"agent": "<id>", "environment_id": "<id>", "title": …, "budget": {"type": "limit", "max_list_cost": {"amount": "20", "currency": "USD"}}}` | MA | **200** (1.0 s) | `status: "idle"`, embedded `agent` snapshot (version 1), `usage` zeroed (`list_cost.amount: "0"`), `stats {active_seconds, duration_seconds}`, `outcome_evaluations: []`, `resources: []`, `vault_ids: []` |
| send event | `POST /v1/sessions/{id}/events {"events": [{"type": "user.message", "content": [{"type": "text", "text": "Reply with OK."}]}]}` | MA | **200** | `{"data": [{"id": "sevt_…", "type": "user.message", "content": […]}]}` |
| stream | `GET /v1/sessions/{id}/events/stream?event_deltas=agent.message` | MA | **200** `text/event-stream` (turn finished in ~1 s) | every frame is `event: message` + JSON `data:`; sequence below |
| list events | `GET /v1/sessions/{id}/events?limit=50` | MA | 200 | 10 persisted events (the `event_start`/`event_delta` previews are **not** persisted); response is `{"data": [...]}` only |
| retrieve session after turn | `GET` | MA | 200 | `usage: {input_tokens: 548, output_tokens: 33, cache_*: 0, active_seconds: 1.008, list_cost: {"amount": "0"}, server_tool_use: {web_search_requests: 0, web_fetch_requests: 0}}`, `stats: {active_seconds: 0.65, duration_seconds: 2.15}` |
| archive → delete session | `POST …/archive`, `DELETE` | MA | 200 / 200 | `{"id": "sesn_…", "type": "session_deleted"}` |
| archive agent | `POST /v1/agents/{id}/archive` | MA | 200 | `archived_at` set (no DELETE for agents) |
| archive → delete environment | `POST …/archive`, `DELETE` | MA | 200 / 200 | `{"type": "environment_deleted"}` |

### Observed event sequence (one `user.message` turn, no tools)

```
session.status_running
session.thread_status_running        {agent_name, session_thread_id: "sthr_…"}
user.message                         (echo of the sent event, same sevt_ id)
span.model_request_start
agent.thinking                       (start-only signal)
event_start                          {"event": {"id": "sevt_…", "type": "agent.message"}}          ← preview (event_deltas)
event_delta                          {"delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "OK"}}, "event_id": …}
agent.message                        {"content": [{"type": "text", "text": "OK"}]}
span.model_request_end               {"is_error": false, "model_request_start_id": …, "model_usage": {"input_tokens": 548, "output_tokens": 33, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}}
session.thread_status_idle           {"stop_reason": {"type": "end_turn"}, agent_name, session_thread_id}
session.usage                        {"usage": {..., "list_cost": {"amount": "0", "currency": "USD"}}, "budget": {...}}
session.status_idle                  {"stop_reason": {"type": "end_turn"}}
```
Thread ids observed use the `sthr_` prefix (reference), not `sth_` (guide example). Every persisted event carries `id` (`sevt_…`) and `processed_at`.

### Status summary
- **LIVE_VERIFIED · BETA**: agents (create/retrieve/list/versions/archive), environments (create/list/archive/delete), sessions (create/retrieve/list/archive/delete), events (send/list/stream), vaults/deployments/deployment_runs/memory_stores (list).
- **ACCOUNT_RESTRICTED · BETA**: `/v1/tunnels` (401).
- **FAILED_VERIFICATION · BETA** (404 "not found" — gated preview on this account): `/v1/dreams`, `/v1/user_profiles`.
- **DOCUMENTED · BETA** (not called — mutations on resources we did not need, or sub-resources): everything else (threads, resources, work queue, memories, credentials, deployments create/pause/run, webhooks…).
Examples: `examples/anthropic/agents/create_agent_session_stream.{sh,py,ts}` (same sequence; header updated to LIVE_VERIFIED). Tests: `tests/anthropic/test_managed_agents.py`.

Machine-readable: endpoints `generated/fragments/endpoints/anthropic-managed-agents.json` (96, verification patched with the results above), parameters `generated/fragments/parameters/anthropic-managed-agents.json` (1,122), session/thread events `generated/fragments/streaming-events/anthropic-managed-agents.json` (44), webhook events `generated/fragments/webhook-events/anthropic-managed-agents.json` (44), objects in `generated/fragments/objects/anthropic-platform-objects.json`.