The Agents resource exposes methods to create, retrieve, and update managed agents through the Beta Managed Agents API; all requests include the anthropic-beta: managed-agents-2026-04-01 header and post to /v1/agents?beta=true. Agent creation requires model and name, with optional parameters controlling tools, MCP servers, coordinator topology via multiagent, and metadata; the mcp_servers array (max 20) and tools array (max 128) must satisfy strict uniqueness and cross-reference constraints. A managed agent is a server-side, reusable configuration pairing a model with its tools and instructions; stored remotely, the same agent definition can be invoked across multiple sessions without re-sending the full configuration.
The Agents resource (in src/anthropic/resources/beta/agents/agents.py) exposes a versions nested sub-resource accessible as a @cached_property.[1] List operations on Agents use SyncPageCursor / AsyncPageCursor for pagination — see Base client and pagination for pagination mechanics.[1]
Agents.create() requires model and name; all other parameters (description, mcp_servers, metadata, multiagent, skills, system, tools, betas) are optional.[1] The model parameter accepts either a model ID string (e.g. claude-opus-4-6) or a model_config object for additional configuration control.[1] Agents.create() posts to /v1/agents?beta=true and returns a BetaManagedAgentsAgent object.[1] The mcp_servers parameter accepts a maximum of 20 entries; names must be unique within the array, and every server must be referenced by an mcp_toolset in tools — unreferenced servers are rejected.[1] The tools array accepts a maximum of 128 tools across all toolsets.[1] The multiagent parameter defines a coordinator topology where the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the agents roster.[1]
Agents.retrieve() raises ValueError if agent_id is an empty string.[1] An optional version integer query parameter controls which version is fetched; omitting it returns the most recent version, and the value must be at least 1 if specified.[1] Agents.retrieve() issues a GET to /v1/agents/{agent_id}?beta=true, passing version as a query parameter, and returns a BetaManagedAgentsAgent.[1]
In Agents.update(), the description field follows a preserve-or-clear pattern: omit it to preserve the existing value, or send an empty string or null to clear it.[1] The mcp_servers field in update() is a full replacement: omit to preserve, send an empty array or null to clear; the same uniqueness and cross-reference constraints as create() apply, with a maximum of 20 entries.[1] The metadata field in update() is a patch: setting a key to a string upserts it, setting it to null deletes it, and omitting the field preserves existing metadata. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.[1]
Sources