# 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.

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):

# 2. Architecture

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):

# 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.

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:

# 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.

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

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

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

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

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

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)

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.

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)

# 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:

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

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

Cloud config (BetaCloudConfig):

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).

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[]:

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).

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):

# 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.

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:

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

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).

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.

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):

# 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):

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)

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).

# 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.