Beta Agents Reference

Purpose and Scope

This page is a reference for the beta Managed Agents agent resource exposed by the official Anthropic TypeScript SDK. In SDK terms, an agent is a reusable Managed Agents definition: it has a model, a human-readable name, optional system instructions, optional skills, optional MCP server connections, and optional tool configuration. Sessions later run against an agent reference, often pinned to a particular version. This reference focuses on the public client.beta.agents surface and the nested client.beta.agents.versions surface rather than the broader session, environment, vault, or file workflows that use agents after they are created.

Sources: src/resources/beta/agents/index.ts, tests/api-resources/beta/agents/agents.test.ts, tests/api-resources/beta/agents/versions.test.ts, api.md

The implementation evidence shows this surface is generated from the OpenAPI specification by Stainless, so the TypeScript package follows the API reference closely. The beta agents barrel exports the Agents resource, the nested Versions resource, agent response types, request parameter types, toolset types, skill parameter types, MCP server parameter types, model configuration types, and the cursor page type used for listing agents. The tests then demonstrate how callers reach the resource from an initialized Anthropic client and how SDK response wrappers behave for representative calls.

Relevant Source Files

• src/resources/beta/agents/index.ts - Barrel export for the beta agents namespace. It exposes Agents, nested Versions, agent response and reference types, Managed Agents model and model config types, toolset and MCP types, skill parameter types, request parameter types such as AgentCreateParams, AgentRetrieveParams, AgentUpdateParams, AgentListParams, AgentArchiveParams, and BetaManagedAgentsAgentsPageCursor.
• tests/api-resources/beta/agents/agents.test.ts - Generated API resource tests for client.beta.agents. These tests show the client construction pattern, create calls with required and optional parameters, response wrapper helpers, update calls, beta header parameters, and skipped retrieve cases that document a generated path-level query handling signal.
• tests/api-resources/beta/agents/versions.test.ts - Generated API resource tests for client.beta.agents.versions. These tests show the nested version-list call shape, pagination-style parameters, beta header parameters, response wrapper helpers, and skipped path-level query handling cases.
• api.md - Generated repository API reference for the SDK. Use it as the broad reference companion for endpoint and type names when navigating the full beta namespace.

Public Namespace and Exported Types

The public namespace is client.beta.agents. The barrel export is important because it defines what TypeScript consumers can import or rely on from this part of the package. It exports the resource class Agents, a nested Versions resource, and the request parameter aliases for the primary operations: AgentCreateParams, AgentRetrieveParams, AgentUpdateParams, AgentListParams, and AgentArchiveParams. It also exports VersionListParams from the nested versions module, which is the parameter shape used when listing historical versions for a specific agent.

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

The same export surface includes the domain model vocabulary used throughout the Managed Agents API. BetaManagedAgentsAgent represents an agent returned by the service, while BetaManagedAgentsAgentReference is the compact form used when another resource needs to refer to an agent. Model configuration is represented by BetaManagedAgentsModel, BetaManagedAgentsModelConfig, and BetaManagedAgentsModelConfigParams. This matters because the create operation accepts a model string or a model configuration object in the official API, and TypeScript users should prefer these SDK types when building reusable configuration helpers.

Tooling-related exports distinguish built-in agent toolsets, MCP toolsets, and custom tools. The barrel exposes BetaManagedAgentsAgentToolset20260401, its parameter type, specific built-in input types such as bash, edit, glob, grep, read, and write inputs, and permission policy types such as BetaManagedAgentsAlwaysAllowPolicy and BetaManagedAgentsAlwaysAskPolicy. It also exports BetaManagedAgentsMCPToolset, MCP tool configuration types, URL MCP server definitions, and custom tool input schema types. These names map directly to the optional tools and mcp_servers areas used when creating or updating an agent.

Agent Method Reference

Use client.beta.agents.create(params) to create an agent. The generated tests show the minimal call shape as an object with model and name, for example model: 'claude-sonnet-4-6' and name: 'My First Agent'. The same test file demonstrates that the returned SDK request promise supports .asResponse() to access the raw Response, direct awaiting to obtain parsed data, and .withResponse() to receive both parsed data and the raw response together. This response-wrapper pattern is consistent with the generated SDK resource tests and is useful when callers need headers, status, or debugging metadata alongside the typed object.

Sources: tests/api-resources/beta/agents/agents.test.ts

The create operation also accepts a richer configuration object. The generated optional-parameter test passes description, mcp_servers, metadata, multiagent, skills, system, tools, and betas. The mcp_servers example uses a URL server with a name and URL, and the tools example enables the built-in agent_toolset_20260401 with a bash config and an always_allow permission policy. The skills example references the Anthropic xlsx skill with a version, while multiagent demonstrates a coordinator topology that includes both an agent ID and a self-reference. The betas parameter is the SDK-side way to send beta header values for the request.

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({ apiKey: 'my-anthropic-api-key' });
 
const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'My First Agent',
  description: 'A general-purpose starter agent.',
  system: 'You are a general-purpose agent.',
  mcp_servers: [
    {
      name: 'example-mcp',
      type: 'url',
      url: 'https://example-server.modelcontextprotocol.io/sse',
    },
  ],
  tools: [
    {
      type: 'agent_toolset_20260401',
      default_config: {
        enabled: true,
        permission_policy: { type: 'always_allow' },
      },
    },
  ],
  betas: ['message-batches-2024-09-24'],
});

Use client.beta.agents.retrieve(agentID, params?, options?) to retrieve an existing agent by ID. The generated retrieve tests are skipped with a note that path-level query parameters are dropped by buildURL for SDK-4349, but they still document the intended public call form: an agent ID string, an optional parameter object containing values such as version and betas, and optional request options. When you need a specific historical version rather than the latest state, pass the version parameter deliberately and verify behavior against the current package version and API reference.

Use client.beta.agents.update(agentID, params) to patch an agent and create a new versioned definition. The tests show the required update shape includes a version number, which is an optimistic concurrency and versioning signal: callers update the version they last observed rather than blindly replacing the latest configuration. Optional update fields mirror the create-time configuration areas, including descriptive metadata, MCP servers, skills, tools, and system instructions. The examples in the generated tests reinforce that updates are not just metadata edits; they can change the operational capabilities of the agent by adding or reconfiguring toolsets and skills.

The exported AgentListParams and AgentArchiveParams types identify list and archive as part of the resource contract, even though the supplied test excerpt highlights create, retrieve, and update in more detail. Treat list as the collection operation for discovering agents and archive as the lifecycle operation for retiring an agent definition rather than deleting its history outright. For exact option names and return shapes, pair these exported type names with the generated api.md reference in the repository and the current platform API reference.

Versions Resource Reference

Agent versions are exposed through the nested client.beta.agents.versions resource. The tests show the primary method shape as client.beta.agents.versions.list(agentID, params?, options?), where the first argument is the parent agent ID. The optional parameter object can include pagination-style values such as limit and page, and it can include betas for beta header selection. As with retrieve, the supplied version-list tests are skipped with the same SDK-4349 path-level query note, but they still document the generated resource shape and intended request construction.

Sources: tests/api-resources/beta/agents/versions.test.ts

Version listing is the key read-side companion to agent updates. When an agent is created, the returned object includes an ID and version information in normal Managed Agents workflows; when it is updated, the new configuration becomes a later version. Listing versions lets applications build audit views, pin session creation to a known definition, or compare current behavior with earlier configurations. In practice, a production workflow usually stores the agent ID and the version used for each session so that later debugging can distinguish model, system prompt, tool, skill, and MCP changes from session-level event behavior.

const versions = await client.beta.agents.versions.list('agent_011CZkYpogX7uDKUyvBTophP', {
  limit: 20,
  page: 'next-page-token',
  betas: ['message-batches-2024-09-24'],
});

Request Parameters and Configuration Objects

The beta agent create and update parameter families are intentionally broad because an agent definition is a bundle of runtime capabilities. model chooses the Claude model or model configuration used by the agent. name gives the definition a human-readable identity, and description, metadata, and system help document and steer behavior. skills attach Anthropic or custom skills, while tools configure built-in toolsets, MCP toolsets, or custom tools. mcp_servers define remote MCP server connections that toolsets can reference. multiagent configures a coordinator topology rather than a single isolated agent.

Sources: src/resources/beta/agents/index.ts, tests/api-resources/beta/agents/agents.test.ts, api.md

The distinction between MCP servers and tools is important. An MCP server definition names and locates a remote Model Context Protocol server, while an MCP toolset in tools makes tools from that server available to the agent. Built-in agent_toolset_20260401 tools are different again: they represent Anthropic-managed tool capabilities such as bash, read, write, edit, glob, and grep inputs surfaced by the exported built-in toolset types. Custom tools are caller-defined contracts with names, descriptions, and input schemas. Keeping these pieces separate makes configuration review easier and avoids treating a connection URL as permission to use every possible tool.

The betas field shown in tests corresponds to the API's optional beta header behavior. The official beta Agents API documents an anthropic-beta header for selecting beta versions, and the TypeScript SDK exposes that pattern as a request parameter named betas. Use it when a specific beta feature gate is required by your agent configuration, such as Managed Agents, MCP client behavior, skills, or other evolving API features. Because beta headers can change over time, keep them close to the operation that requires them rather than hiding them in unrelated application configuration.

Execution Flow and Response Handling

A typical SDK flow starts with an Anthropic client, calls client.beta.agents.create, optionally calls client.beta.agents.update to produce a revised version, and then uses other beta resources such as sessions to run the agent. This page stops at the agent boundary, but the versioning design is visible here: create establishes the first reusable definition, update requires the observed version and returns a newer definition, and versions list gives you a way to enumerate history. That makes agent configuration a durable artifact rather than a transient request body.

Sources: tests/api-resources/beta/agents/agents.test.ts, tests/api-resources/beta/agents/versions.test.ts

The generated tests also show how to choose between parsed and raw responses. Awaiting the SDK request promise gives the parsed data object. Calling .asResponse() returns the platform Response object, which is useful for status-code inspection or lower-level diagnostics. Calling .withResponse() returns an object whose data property is the parsed value and whose response property is the raw response. Use direct awaiting for ordinary application code, .withResponse() for observability and logging, and .asResponse() only when you need to inspect or stream the raw HTTP-level result yourself.

Compact Reference

Testing Signals and Next Steps

The tests in tests/api-resources/beta/agents/agents.test.ts and tests/api-resources/beta/agents/versions.test.ts are generated resource tests, not end-to-end behavioral examples. They are still valuable because they lock down public method names, argument ordering, request-option placement, beta parameter forwarding, and response-wrapper behavior. The skipped retrieve and versions-list tests are also useful signals: when working on generated URL construction or path-level query behavior, preserve the public call shapes while validating the lower-level request builder against the current API contract.

Sources: tests/api-resources/beta/agents/agents.test.ts, tests/api-resources/beta/agents/versions.test.ts

For next steps, read the Managed Agents overview to understand how agent definitions relate to environments, sessions, files, vaults, skills, and event streaming. Then use the beta sessions reference when you are ready to run an agent, send user messages, stream events, and handle tool results. If your agent configuration includes MCP, custom tools, or skills, review those capability-specific pages before production rollout so that permissions, credentials, and version pinning are explicit rather than accidental.