Beta Managed Agent Resources Reference

Purpose and Scope

This page is a reference for the SDK surfaces that support Claude Managed Agents in the beta namespace. In this context, a support resource is anything that gives an agent durable configuration, reusable expertise, tool access, version history, or memory-like behavior outside a single Messages API call. The source set for this page centers on client.beta.agents, the generated agent version resource, the exported Managed Agents type names, and the local filesystem memory tool helper. That makes the page most useful when you are wiring an agent definition, attaching skills or toolsets, listing versions, or deciding whether a local memory implementation is safe for your runtime.

Managed Agents API calls require beta semantics. The generated SDK resource handles that detail by sending requests to beta-enabled paths and by adding managed-agents-2026-04-01 to the anthropic-beta header for agent and version operations. Callers can still pass additional beta names through the betas parameter, and the SDK combines them with the required Managed Agents beta header. Treat this as an important difference from ordinary stable resources: the public method names look like normal SDK methods, but the generated implementation deliberately opts each request into the Managed Agents beta surface.

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

Relevant Source Files

• src/resources/beta/agents/index.ts — barrel export for the generated beta agents package; it exposes the Agents resource, version resource, Managed Agents model/config types, skill parameter types, toolset types, MCP toolset types, and agent CRUD parameter types.
• src/resources/beta/agents.ts — beta namespace bridge that re-exports the generated agents index, making the agent resource family available through the broader beta resource tree.
• src/resources/beta/agents/agents.ts — generated implementation of Agents, including create, retrieve, update, list, archive, pagination, request paths, and required Managed Agents beta headers.
• src/resources/beta/agents/versions.ts — generated implementation of client.beta.agents.versions.list, including cursor pagination and the same Managed Agents beta header behavior.
• src/tools/memory/node.browser.ts — browser-target substitute for tools/memory/node; it re-exports the runtime-agnostic betaMemoryTool helper but throws for filesystem-backed handlers.
• src/tools/memory/node.ts — Node implementation of BetaLocalFilesystemMemoryTool, including filesystem permissions, atomic writes, symlink-escape validation, and command handler imports for memory operations.

System-to-Code Mapping

At the package boundary, the beta agents surface is assembled through generated barrel files. src/resources/beta/agents.ts re-exports ./agents/index, and that index file re-exports both the Agents class and the Versions class. It also re-exports many type-only contracts, including BetaManagedAgentsAnthropicSkill, BetaManagedAgentsCustomSkill, BetaManagedAgentsSkillParams, BetaManagedAgentsMCPToolset, BetaManagedAgentsCustomTool, permission policy types, model configuration types, and request parameter types such as AgentCreateParams, AgentUpdateParams, and AgentListParams. Those exports are the key reference point when you want compile-time help for support resources attached to agents rather than separate runtime helper classes.

The runtime agent resource lives in src/resources/beta/agents/agents.ts. The Agents class extends the SDK APIResource base and creates a nested versions resource as new VersionsAPI.Versions(this._client). Each agent method delegates to the shared client transport. create posts to /v1/agents?beta=true, retrieve gets /v1/agents/${agentID}?beta=true, update posts to the same agent path, list uses getAPIList with PageCursor, and archive posts to /v1/agents/${agentID}/archive?beta=true. These methods are generated but still form the public contract used by application code.

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

Agent Resource Reference

Use client.beta.agents when you need to create or manage an agent definition. An agent definition is the durable object that names a model, records the configuration you pass, and can reference support resources such as skills, MCP toolsets, custom tools, and permission policies through the exported parameter types. The official Managed Agents documentation describes skills as reusable, filesystem-based expertise that can be attached to agents, with pre-built Anthropic skills and custom uploaded skills sharing the same attachment model. In the SDK source, that concept appears as exported types such as BetaManagedAgentsAnthropicSkillParams, BetaManagedAgentsCustomSkillParams, and BetaManagedAgentsSkillParams.

The core methods are small and predictable. create(params, options?) accepts AgentCreateParams and returns APIPromise<BetaManagedAgentsAgent>. retrieve(agentID, params?, options?) returns a single agent. update(agentID, params, options?) sends updated body fields, including the version-oriented example shown in the generated comment. list(params?, options?) returns a PagePromise<BetaManagedAgentsAgentsPageCursor, BetaManagedAgentsAgent>, so it supports async iteration and automatic page fetching. archive(agentID, params?, options?) archives an agent and returns the updated agent representation. Each method accepts request options, so standard SDK headers, retries, and request overrides can still be used.

const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'My First Agent',
});
 
const current = await client.beta.agents.retrieve(agent.id);
 
for await (const item of client.beta.agents.list()) {
  console.log(item.id, item.name);
}

The betas parameter deserves special attention. The generated methods destructure betas away from the JSON body or query object, then build an anthropic-beta header containing your extra beta names plus managed-agents-2026-04-01. That means a caller can opt into additional beta features while preserving the Managed Agents requirement. It also means betas is a header parameter, not an agent field. When debugging unexpected request bodies, check whether a value belongs in the agent body or in the betas array.

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

Versions, Skills, and Tool Support Contracts

Agent versions are exposed as a nested resource at client.beta.agents.versions. The method available in the supplied source is list(agentID, params?, options?), which returns the same cursor page shape as agent listing but scoped to a single agent ID. Use this when you need to inspect historical agent definitions or build a deployment workflow that chooses an explicit version. The generated implementation uses path templating for /v1/agents/${agentID}/versions?beta=true, passes query parameters through, and adds the Managed Agents beta header just like the parent agent methods.

The support-resource type exports in src/resources/beta/agents/index.ts are broad because an agent can be configured with more than a model and name. Skill types model both Anthropic-provided skills and custom skills. Tool-related exports cover custom tools, MCP server URL definitions, MCP toolsets, default toolset configuration, and explicit permission policies such as always-allow and always-ask. The multiagent coordinator types indicate that an agent definition can participate in multiagent patterns. You normally interact with these as TypeScript types while composing AgentCreateParams or AgentUpdateParams, rather than by importing separate runtime classes from this specific source set.

for await (const version of client.beta.agents.versions.list(
  'agent_011CZkYpogX7uDKUyvBTophP',
)) {
  console.log(version.id);
}

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

Local Memory Tool Reference

The memory tool files are helper-level support for agent-like workflows that need a local filesystem memory implementation. src/tools/memory/node.ts exports the runtime-agnostic betaMemoryTool helper and the MemoryToolHandlers type, then implements BetaLocalFilesystemMemoryTool using Node built-ins. The imported command types show the supported operation family: view, create, string replace, insert, delete, and rename. This is not the same thing as a remote memory-store API; it is a local handler implementation you can use where filesystem-backed memory is appropriate and where Node-compatible APIs are available.

The Node implementation includes security and consistency decisions that matter in production. It sets file creation mode to owner read/write only and directory creation mode to owner-only access, avoiding permissive defaults in environments such as containers. It writes files atomically by creating a temporary file, syncing it, closing it, and renaming it into place, which helps prevent readers from seeing partially written content. It also validates that operations cannot escape the memory root through symlinks by resolving the deepest existing ancestor and checking it remains inside the configured root.

Browser builds deliberately do not provide the filesystem-backed handlers. src/tools/memory/node.browser.ts re-exports betaMemoryTool and the handler type so imports can remain structurally compatible, but BetaLocalFilesystemMemoryTool and all handler methods throw an AnthropicError explaining that Node.js or a Node-compatible runtime is required. This protects browser bundles from accidentally resolving Node built-ins such as fs/promises, path, and crypto, and it prevents client-side code from silently pretending that persistent local memory is available.

import { BetaLocalFilesystemMemoryTool, betaMemoryTool } from '@anthropic-ai/sdk/tools/memory/node';
 
const memory = await BetaLocalFilesystemMemoryTool.init('./memory');
 
// Wire `memory` as the handler implementation for the beta memory tool
// in a Node.js or Node-compatible runtime.
void betaMemoryTool;
void memory;

Sources: src/tools/memory/node.ts, src/tools/memory/node.browser.ts

Compact Reference

When choosing a support-resource path, start from the lifecycle you need. If the work changes an agent definition, use client.beta.agents and the exported parameter types. If the work examines historical definitions, use client.beta.agents.versions.list. If the work needs local memory command execution, use the Node memory tool only in a Node-compatible runtime and expect the browser substitute to fail fast for filesystem operations. For separate remote support resources such as vaults, webhooks, user profiles, or managed memory stores, continue to the broader beta namespace reference pages that cover those resources directly.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/resources/beta/agents/index.ts, src/tools/memory/node.ts, src/tools/memory/node.browser.ts