Managed Agents — Endpoint Reference

All endpoints require x-api-key and anthropic-version: 2023-06-01 headers. Managed Agents endpoints additionally require the anthropic-beta header.

Beta Headers

anthropic-beta: managed-agents-2026-04-01

The SDK adds this header automatically for all client.beta.{agents,environments,sessions,vaults,memory_stores}.* calls. Skills endpoints use skills-2025-10-02; Files endpoints use files-api-2025-04-14.

SDK Method Reference

All resources are under the beta namespace. Python and TypeScript share identical method names.

Naming quirks to watch for:

• Agents and Session Threads have no delete — only archive. Archive is permanent: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both delete and archive; Session Resources, Files, Skills, and Memories are delete-only; Memory Versions have neither — only redact.
• Session resources use add (not create).
• Go's event stream is StreamEvents (not Stream).

Agent shorthand: agent on session create accepts either a bare string (agent="agent_abc123" — uses latest version) or the full reference object ({type: "agent", id: "agent_abc123", version: 123}).

Model shorthand: model on agent create accepts either a bare string (model="claude-opus-4-7" — uses standard speed) or the full config object ({type: "model_config", id: "claude-opus-4-6", speed: "fast"}). Note: speed: "fast" is only supported on Opus 4.6.

Agents

Step one of every flow. Sessions require a pre-created agent — there is no inline agent config under managed-agents-2026-04-01.

Sessions

Events

Session Threads

Per-subagent event streams in multiagent sessions. See shared/managed-agents-multiagent.md.

Session Resources

Environments

Vaults

Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via vault_ids. See managed-agents-tools.md §Vaults for the conceptual guide and credential shapes.

Credentials

Credentials are individual secrets stored inside a vault.

Memory Stores

Workspace-scoped persistent memory that survives across sessions. Attach to a session via a {"type": "memory_store", "memory_store_id": ...} entry in resources[] (session-create time only). See shared/managed-agents-memory.md for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.

Memories

Individual text documents inside a store (≤ 100KB each). create creates at a path and returns 409 (memory_path_conflict_error, with conflicting_memory_id) if the path is occupied; update mutates by mem_... ID (rename and/or content). Only update accepts a precondition ({"type": "content_sha256", "content_sha256": ...}) — on mismatch returns 409 (memory_precondition_failed_error). List endpoints accept view: "basic"|"full" (controls whether content is populated; retrieve defaults to full).

Memory Versions

Immutable per-mutation snapshots (memver_...) — the audit and rollback surface. operation ∈ created / modified / deleted.

Files

Skills

Request/Response Schema Quick Reference

CreateAgent Request Body

Always start here. model, system, tools, mcp_servers, skills are top-level fields on this object — they do NOT go on the session.

{
  "name": "string (required, 1-256 chars)",
  "model": "claude-opus-4-7 (required — bare string, or {id, speed} object)",
  "description": "string (optional, up to 2048 chars)",
  "system": "string (optional, up to 100,000 chars)",
  "tools": [
    { "type": "agent_toolset_20260401" }
  ],
  "skills": [
    { "type": "anthropic", "skill_id": "xlsx" },
    { "type": "custom", "skill_id": "skill_abc123", "version": "1" }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      "agent_abc123",
      { "type": "agent", "id": "agent_def456", "version": 4 },
      { "type": "self" }
    ]
  },
  "metadata": {
    "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
  }
}

Limits: tools max 128, skills max 20, mcp_servers max 20 (unique names). multiagent.agents 1–20 entries (string ID | {type:"agent",id,version?} | {type:"self"}) — see shared/managed-agents-multiagent.md.

CreateSession Request Body

{
  "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
  "environment_id": "env_abc123 (required)",
  "title": "string (optional)",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/owner/repo (required)",
      "authorization_token": "ghp_... (required)",
      "mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
      "checkout": { "type": "branch", "name": "main" }
    }
  ],
  "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"],
  "metadata": {
    "key": "value"
  }
}

The agent field accepts only a string ID or {type: "agent", id, version} — model/system/tools live on the agent, not here.

>

checkout accepts {type: "branch", name: "..."} or {type: "commit", sha: "..."}. Omit for the repo's default branch.

CreateEnvironment Request Body

{
  "name": "string (required)",
  "description": "string (optional)",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted | limited (union — see SDK types)"
    },
    "packages": { }
  },
  "metadata": { "key": "value" }
}

SendEvents Request Body

{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Hello"
        }
      ]
    }
  ]
}

Define Outcome Event

{
  "type": "user.define_outcome",
  "description": "Build a DCF model for Costco in .xlsx",
  "rubric": { "type": "file", "file_id": "file_01..." },
  "max_iterations": 5
}

rubric is required: {type: "text", content} or {type: "file", file_id}. max_iterations default 3, max 20. Echoed back with outcome_id + processed_at. See shared/managed-agents-outcomes.md.

Tool Result Event

{
  "type": "user.custom_tool_result",
  "custom_tool_use_id": "sevt_abc123",
  "content": [{ "type": "text", "text": "Result data" }],
  "is_error": false
}

Error Handling

Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing type, error, and request_id:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Description of what went wrong"
  },
  "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
}

Include the request_id when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner error.type is one of the following:

Note that 409 Conflict carries error.type: "invalid_request_error" (there is no separate conflict_error type); inspect both the HTTP status and the message to distinguish conflicts from other invalid requests.

Rate Limits

Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your Messages API token limits. Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.

Files and Skills endpoints use the standard tier-based rate limits.

When a limit is exceeded the API returns 429 with a rate_limit_error (see Error Handling for the response envelope) and a retry-after header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.