Managed Agents Overview

Purpose and Scope

Managed Agents are the SDK surface for creating reusable Claude agent configurations and then operating them through beta resources. In the product model, an agent is a versioned configuration that bundles a model, a name, system instructions, tools, MCP servers, skills, and related capability settings. In the TypeScript SDK, that concept is exposed under client.beta.agents, with a generated Agents resource and a nested versions resource. This page orients SDK users who already know the regular Messages API and want to understand where the Managed Agents beta begins, how it is namespaced, and what pieces are involved before moving into setup or session-specific guides.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents.ts, src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

The important distinction is that a Managed Agent is not just one request to Claude. The agent resource stores the reusable definition, while sessions and events provide the runtime conversation and operation layer. The source paths for this page focus on the agent-definition side and the shared beta tool-runner primitives that bridge Messages-style tool use and session event tool use. That means this page covers the SDK entry points, the agent lifecycle methods, exported configuration types, version listing, and the helper contracts that make client-runnable tools behave consistently across beta surfaces.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/lib/tools/BetaRunnableTool.ts, src/lib/tools/BetaToolRunner.ts

Relevant Source Files

src/resources/beta/agents/index.ts - Barrel export for the beta agents package; it exposes the Agents class, the Versions class, agent configuration types, toolset types, skill types, MCP-related types, and method parameter types.
src/resources/beta/agents.ts - Top-level beta agents module that re-exports the generated ./agents/index surface for the SDK namespace.
src/resources/beta/agents/agents.ts - Generated Agents resource implementation, including create, retrieve, update, list, and archive methods and automatic managed-agents-2026-04-01 beta header construction.
src/resources/beta/agents/versions.ts - Generated nested versions resource; it lists historical or versioned agent configurations through client.beta.agents.versions.list(agentID, ...).
src/lib/tools/BetaRunnableTool.ts - Shared beta tool contract for client-runnable tools, including BetaRunnableTool, BetaToolUse, BetaToolRunContext, toolName, and standardized tool error formatting.
src/lib/tools/BetaToolRunner.ts - Helper loop for beta message tool execution; it shows how the SDK manages tool-loop state, helper headers, cloned message state, completion tracking, and deprecated local compaction control.

Core Primitives

The first primitive is the agent resource itself. Agents extends the SDK APIResource base and exposes the operations most users need for lifecycle management: create a new agent, retrieve an existing agent by ID, update it, list agents with cursor pagination, and archive an agent. Each operation calls a /v1/agents... endpoint with beta=true and builds an anthropic-beta header that appends managed-agents-2026-04-01, while still preserving any optional betas supplied by the caller. This directly implements the documentation requirement that Managed Agents API requests use the Managed Agents beta header, while keeping the beta header automatic for normal SDK users.

Sources: src/resources/beta/agents/agents.ts

The second primitive is versioning. The official docs frame an agent as a reusable, versioned configuration, and the SDK reflects that with client.beta.agents.versions.list(agentID, ...). The nested Versions resource returns a cursor-paginated list of BetaManagedAgentsAgent records for a specific agent ID. This shape matters when teams promote or audit agent definitions: the current agent ID stays stable enough to reference from session creation, while versions let you inspect prior configurations. The version resource follows the same header pattern as the main agents resource, so beta compatibility is handled consistently across lifecycle and history calls.

Sources: src/resources/beta/agents/versions.ts, src/resources/beta/agents/agents.ts

The third primitive is capability configuration. The beta agents barrel exports types for model configuration, built-in agent toolsets, custom tools, MCP server definitions, MCP toolsets, permission policies, Anthropic skills, custom skills, multi-agent coordination, and session-thread agent references. These names are useful because they reveal the SDK vocabulary you will see in TypeScript completions when building an agent definition. Local tools are functions implemented by your application; MCP toolsets point to external MCP servers; skills are reusable filesystem-based expertise attached to the agent. The agent definition layer can describe these capabilities before a session ever starts.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts

System-to-Code Mapping

Product concept	SDK surface	Source grounding
Reusable agent configuration	`client.beta.agents.create(params)`	`Agents.create` posts to `/v1/agents?beta=true` with a generated beta header.
Agent lookup	`client.beta.agents.retrieve(agentID, params?)`	`Agents.retrieve` gets `/v1/agents/{agentID}?beta=true`.
Agent update	`client.beta.agents.update(agentID, params)`	`Agents.update` posts a body to `/v1/agents/{agentID}?beta=true`.
Agent catalog	`client.beta.agents.list(params?)`	`Agents.list` uses `getAPIList` and `PageCursor`.
Archival lifecycle	`client.beta.agents.archive(agentID, params?)`	`Agents.archive` posts to `/v1/agents/{agentID}/archive?beta=true`.
Agent versions	`client.beta.agents.versions.list(agentID, params?)`	`Versions.list` returns paginated `BetaManagedAgentsAgent` records.
Local beta tools	`BetaRunnableTool`	Tool helpers parse input, run user code, and return text or structured tool-result blocks.

The exports in src/resources/beta/agents/index.ts are intentionally broad because Managed Agents combine several capability families. For example, model and model-config types describe which Claude model powers the agent, toolset types describe what the agent may call, MCP types represent server-backed tools, and skill parameter types represent domain expertise that can be attached to the configuration. Users should treat this module as the type entry point for agent setup rather than hand-writing loosely typed objects. The small src/resources/beta/agents.ts file is also significant because it makes the generated package available through the broader beta namespace instead of requiring deep imports.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents.ts

Execution Flow

A typical setup flow starts by constructing an Anthropic client, then calling client.beta.agents.create with at least the fields required by the API, such as a model and human-readable name. The method examples embedded in the generated resource show the intended calling style: await client.beta.agents.create({ model: 'claude-sonnet-4-6', name: 'My First Agent' }). After creation, applications keep the returned agent ID and use it when starting sessions in the Managed Agents session surface. If the agent definition changes, update creates a newer configuration state, and versions.list can be used to inspect the available versions for that agent.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

Pagination is part of the normal flow for list operations. Both Agents.list and Versions.list return PagePromise values backed by PageCursor, and the generated examples demonstrate for await ... of iteration. That means callers can process agent catalogs or version histories without manually managing cursors in simple cases. When you do need request-level control, each method accepts RequestOptions, and the generated implementation merges request options with SDK-built beta headers. The method-specific params types also allow optional betas, which are appended before the Managed Agents beta token rather than replacing it.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

Tool Integration and Helper Behavior

Managed Agents often need tools, but the SDK separates tool definition from tool execution. BetaRunnableTool is the client-runnable contract: it combines a beta tool definition with parse, run, and an optional close hook. Its run method receives parsed arguments and a BetaToolRunContext, which includes the triggering tool use and an optional abort signal. The source explicitly defines BetaToolUse as a union of Messages tool-use blocks and Managed Agents session events such as agent.tool_use and agent.custom_tool_use, so tool code that only depends on common fields like id, name, and input can be reused across surfaces.

Sources: src/lib/tools/BetaRunnableTool.ts

The helper layer also normalizes naming and failures. The toolName helper returns name for most tools but uses mcp_server_name for MCP toolsets, which keeps lookup behavior consistent when tools are addressed by the model. toolErrorContent turns a thrown ToolError into its structured content and turns other exceptions into an Error: ... string. BetaToolRunner then handles an automatic conversation loop for beta message tool use: it is an async iterable, clones message state to avoid accidental mutation, records helper headers, tracks iterations and completion, and warns that its old compactionControl option is deprecated in favor of server-side compaction edits.

Sources: src/lib/tools/BetaRunnableTool.ts, src/lib/tools/BetaToolRunner.ts

Compact API Reference

Entry point	Signature shape	Behavior
`Agents.create`	`create(params: AgentCreateParams, options?: RequestOptions): APIPromise<BetaManagedAgentsAgent>`	Creates an agent with a request body and automatic Managed Agents beta header.
`Agents.retrieve`	`retrieve(agentID: string, params?: AgentRetrieveParams, options?: RequestOptions): APIPromise<BetaManagedAgentsAgent>`	Retrieves one agent by ID, with optional query params and beta headers.
`Agents.update`	`update(agentID: string, params: AgentUpdateParams, options?: RequestOptions): APIPromise<BetaManagedAgentsAgent>`	Updates an agent by posting a body to the agent endpoint.
`Agents.list`	`list(params?: AgentListParams, options?: RequestOptions): PagePromise<BetaManagedAgentsAgentsPageCursor, BetaManagedAgentsAgent>`	Lists agents through cursor pagination.
`Agents.archive`	`archive(agentID: string, params?: AgentArchiveParams, options?: RequestOptions): APIPromise<BetaManagedAgentsAgent>`	Archives an agent through the archive endpoint.
`Versions.list`	`list(agentID: string, params?: VersionListParams, options?: RequestOptions): PagePromise<BetaManagedAgentsAgentsPageCursor, BetaManagedAgentsAgent>`	Lists versions for one agent ID.
`BetaRunnableTool`	`{ run(args, context?), parse(content), close? }`	Defines a client-executable beta tool shared by tool-runner helpers.

For next steps, start with agent setup when you need to author the reusable configuration, then move to sessions and event streaming when you need runtime execution. Read the tool-helper pages when your agent must call application-owned functions, and read the skills and MCP pages when the capability belongs in reusable filesystem expertise or an MCP server rather than local code. The overview here is intentionally centered on the beta entry points and shared contracts; task guides can layer concrete session creation, file resources, event deltas, and deployment workflows on top of these primitives.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/lib/tools/BetaRunnableTool.ts, src/lib/tools/BetaToolRunner.ts

Ask a question...