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. Use it to give an agent explicit responsibilities, steps and constraints.

Editorial note: curated source snapshot published by Collider.club under the MIT License. Source attribution is preserved in the front matter.

Source snapshot

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.

Most users should define agents and environments as version-controlled YAML applied with the ant CLI — see shared/anthropic-cli.md. The endpoints below are the underlying API that the CLI and SDKs drive.

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,deployments,deployment_runs}.* 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).
• The self-hosted worker is not under client.beta.* — it's EnvironmentWorker from anthropic.lib.environments / @anthropic-ai/sdk/helpers/beta/environments; only environments.work.poller/stats/stop are client methods.

Agent shorthand: agent on session create accepts three forms — a bare string (agent="agent_abc123", latest version), a pinned reference {type: "agent", id, version}, or {type: "agent_with_overrides", id, version?, model?, system?, tools?, mcp_servers?, skills?} to override those fields for this session only (see shared/managed-agents-core.md → Override agent configuration for a session).

Model shorthand: model on agent create accepts either a bare string (model="claude-opus-5" — uses standard speed) or the full config object, which takes speed and effort alongside id: {id: "claude-opus-5", speed: "fast"}, {id: "claude-opus-5", effort: "high"}. effort accepts a level string (low/medium/high/xhigh/max) or {type: "<level>"}, and is agent-configuration only — an effort inside a per-session model override is ignored. See shared/managed-agents-core.md → Effort on the agent model. Note: speed: "fast" is supported on Claude Opus 5 and Opus 4.8 — on the Claude API only, which includes Managed Agents but not Amazon Bedrock, Google Cloud, or Microsoft Foundry. Opus 4.7 fast mode has been removed; speed: "fast" on Opus 4.7 returns an error.

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

For type: "self_hosted", config is the bare {"type": "self_hosted"} — networking and packages do not apply.

Deployments

Scheduled deployments (depl_ IDs) run an agent on a recurring cron schedule — each firing creates a session. See shared/managed-agents-scheduled-deployments.md for the conceptual guide (cron/DST semantics, failure behavior, lifecycle).

Deployment Runs

Each trigger attempt (scheduled or manual) writes a deployment_run record (drun_ IDs) carrying either the created session_id or an error.type (environment_archived, agent_archived, vault_not_found, session_rate_limited, service_unavailable).

Vaults

Vaults store credentials that Anthropic manages on your behalf — MCP credentials (OAuth with auto-refresh, or static bearer tokens) and environment_variable credentials substituted into outbound requests at egress. 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-5 (required — bare string, or {id, speed?, effort?} 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" }
    }
  ],
  "initial_events": [
    { "type": "user.message", "content": [{ "type": "text", "text": "Review the auth module." }] }
  ],
  "vault_ids": ["vlt_abc123 (optional — vault credentials: MCP auth + environment variables)"],
  "metadata": {
    "key": "value"
  }
}

The agent field accepts a string ID, {type: "agent", id, version}, or {type: "agent_with_overrides", id, version?, ...} for session-local overrides of model/system/tools/mcp_servers/skills. Outside the overrides form, those fields live on the agent, not here. An effort inside a model override is ignored — set it on the agent.

initial_events (optional, max 50) sends events at creation and starts the agent loop in the same call. Only user.message and user.define_outcome are accepted — no system.message, and none of the tool-result kinds. Validation is all-or-nothing. See shared/managed-agents-core.md → Seeding a session with initial_events.

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 | self_hosted",
    "networking": {
      "type": "unrestricted | limited (union — see SDK types)"
    },
    "packages": { }
  },
  "metadata": { "key": "value" }
}

CreateDeployment Request Body

{
  "name": "Weekly compliance scan",
  "agent": "agent_abc123 (required — same shapes as CreateSession)",
  "environment_id": "env_abc123 (required)",
  "initial_events": [
    { "type": "user.message", "content": [{ "type": "text", "text": "Run the weekly compliance scan." }] }
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York"
  }
}

Optional session config (resources, vault_ids, etc.) is supported the same way as on CreateSession. Response includes status, paused_reason, and schedule.upcoming_runs_at (next fire times). See shared/managed-agents-scheduled-deployments.md.

SendEvents Request Body

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

system.message events (append system-level context for this turn and later ones) use the same envelope with type: "system.message" — supported on Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5, checked against the agent's primary model only; see shared/managed-agents-events.md § Adding system context mid-session.

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.

Pagination

Most Managed Agents list endpoints use the page / next_page cursor scheme:

Every SDK exposes an auto-paginating iterator that follows next_page. In Python and TypeScript, iterate the list result directly; the other SDKs expose the iterator via a separate method (iterating the plain list result returns one page). SDK auto-pagination is forward-only — to go back a page, read prev_page from the response and pass it back as the page parameter yourself.

⚠️ Some endpoints use a different cursor scheme: Message Batches, Files, Models, and several Admin API endpoints take after_id/before_id and return has_more/first_id/last_id instead of page/next_page. Some page-scheme endpoints (e.g. GET /v1/skills) also return a has_more boolean alongside next_page. Check the endpoint's reference page for its exact pagination fields.

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.

About Collider.club

This card belongs to the curated knowledge base of Collider.club — a closed business club for entrepreneurs, engineers, investors and domain experts building projects for international markets. Members work across DeFi, AI/ML, FinTech, Web3, banking, hardware and venture capital, and the club runs closed sessions on high-margin niches with anonymous speakers.

• Club: https://collider.club
• Collection: Collider.club curated card library (mdrss-card/v2)
• Maintainer: Collider.club editorial team

License

MIT License — Copyright (c) 2026 Collider.club. Full text: LICENSE · https://opensource.org/licenses/MIT