Managed Agent Setup

Purpose and Scope

Managed Agent setup is the step where you turn a reusable idea for an agent into a versioned API resource. In the Claude Managed Agents product model, an agent is not a one-off chat request: it is a named configuration that can be reused across sessions. The configuration describes the model, behavior, and available capabilities that Claude should use later when a session starts. In this TypeScript SDK, that setup surface lives under client.beta.agents, with generated resource methods for creating, retrieving, updating, listing, archiving, and inspecting agent versions.

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

This page is for developers who already have an Anthropic client and want to define an agent resource before moving on to sessions, environments, and event streaming. The important distinction is that setup creates durable configuration, while sessions execute that configuration. The SDK mirrors this separation: the Agents resource is responsible for agent lifecycle operations, while the generated type exports name the configuration concepts that can participate in an agent, including models, toolsets, custom tools, MCP toolsets, skills, and permission policies.

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

Relevant Source Files

• src/resources/beta/agents/index.ts - Barrel export for the Managed Agents resource, its version resource, and the public TypeScript types used to describe agent configuration, tools, MCP servers, skills, models, and pagination.
• src/resources/beta/agents.ts - Namespace-level re-export that makes the generated agents module available through the beta resources tree.
• src/resources/beta/agents/agents.ts - Generated Agents API resource with create, retrieve, update, list, archive, beta-header handling, endpoint paths, examples, and pagination behavior.
• src/resources/beta/agents/versions.ts - Generated nested Versions API resource for listing historical versions of a configured agent.
• src/tools/agent-toolset/fs-util.ts - Node-only filesystem helper module used by the local agent toolset to confine file operations to a work directory and perform safer writes.
• src/tools/agent-toolset/node.browser.ts - Browser replacement module for the Node agent toolset; it preserves types but throws at runtime for Node-only tools in browser bundles.

Core Setup Primitives

The SDK exposes agent setup through a generated Agents class extending APIResource. The visible public methods are create, retrieve, update, list, and archive. Each method accepts normal SDK RequestOptions as an optional second argument, so callers can keep using the same request customization mechanisms they use elsewhere in the TypeScript SDK. The generated methods call /v1/agents?beta=true or an agent-specific /v1/agents/{agentID} path and return typed APIPromise or paginated PagePromise values.

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

The setup payload is represented by AgentCreateParams, and the generated example shows the minimal creation shape: a model and a human-readable name. Official Managed Agents docs describe the broader configuration as a reusable bundle of model, system prompt, tools, MCP servers, and skills. The SDK type barrel supports that vocabulary directly by exporting names such as BetaManagedAgentsModelConfigParams, BetaManagedAgentsAgentToolConfigParams, BetaManagedAgentsCustomToolParams, BetaManagedAgentsMCPToolsetParams, BetaManagedAgentsAnthropicSkillParams, and BetaManagedAgentsCustomSkillParams. Treat those type names as the SDK-facing contract for progressively richer agent definitions.

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

Permission and execution behavior are also visible in the exported setup types. BetaManagedAgentsAlwaysAllowPolicy and BetaManagedAgentsAlwaysAskPolicy indicate that tool use may be governed by explicit policies. BetaManagedAgentsAgentToolset20260401 and its specific input types for bash, edit, glob, grep, read, and write point to the built-in agent toolset version represented in this SDK. That naming matters during setup because the agent configuration determines which capabilities can be requested during a later session, even though actual work happens elsewhere in the Managed Agents flow.

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

Creating and Updating Agents

The shortest setup flow is to create an agent with a model and name, then store the returned agent ID for future session startup. The generated example uses client.beta.agents.create and returns a BetaManagedAgentsAgent. The SDK automatically adds the Managed Agents beta header, so application code does not need to manually attach managed-agents-2026-04-01 for these generated methods. If you pass additional beta values through the betas parameter, the implementation appends the Managed Agents beta value to that list before sending the request.

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

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic();
 
const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'Code Review Assistant',
});
 
console.log(agent.id);

Use update when you want to change an existing agent configuration. The generated method posts to the agent-specific path and accepts AgentUpdateParams. The visible example updates an agent by passing { version: 1 }, which reflects the versioned nature of Managed Agents: an agent is the stable resource, while versions capture concrete configurations over time. After a successful update, the method resolves to the updated BetaManagedAgentsAgent, keeping lifecycle operations consistently typed.

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

const updated = await client.beta.agents.update(
  'agent_011CZkYpogX7uDKUyvBTophP',
  { version: 1 },
);

Versioning, Listing, and Archiving

Agent setup should include a version-management habit from the beginning. The nested versions property on Agents instantiates VersionsAPI.Versions, and the Versions resource exposes list(agentID, params?, options?). That method returns a paginated list of BetaManagedAgentsAgent records using the same cursor pagination infrastructure as the main list operation. In practice, this lets you inspect how a reusable agent changed over time, compare deployed configurations, or confirm which version a workflow should reference.

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

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

Listing agents uses client.beta.agents.list() and returns a PagePromise over BetaManagedAgentsAgentsPageCursor. The generated example shows idiomatic asynchronous iteration, which is the easiest way to consume all available pages without manually handling cursors. Retrieving and archiving both take an agentID. Retrieve is useful after setup to confirm the server-side representation, while archive is the lifecycle endpoint for removing an agent from active use without treating it as an ordinary update.

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

Toolset and Runtime Constraints

A configured Managed Agent can include capabilities, but not every capability is equally portable across runtimes. The SDK separates Node-only local agent toolset behavior from browser builds. The browser replacement for tools/agent-toolset/node explicitly says the real module depends on Node built-ins such as child process and filesystem APIs. In browser bundles, exported functions like setupSkills, betaAgentToolset20260401, betaBashTool, betaReadTool, betaWriteTool, betaEditTool, betaGlobTool, and betaGrepTool throw an AnthropicError if invoked.

Sources: src/tools/agent-toolset/node.browser.ts

That constraint should influence setup decisions. If your agent configuration relies on built-in file or shell style tools, run the execution side in Node.js or a Node-compatible runtime. The browser stub is intentionally type-friendly: type exports are re-exported for compile-time use, but value exports fail at runtime so web bundles do not accidentally include or attempt to resolve Node-only modules. This design keeps browser packaging clean while making the operational boundary explicit.

Sources: src/tools/agent-toolset/node.browser.ts

Filesystem behavior for the Node toolset is designed around confinement. The helper module resolves paths against a root work directory, canonicalizes symlinks including leaf symlinks, rejects paths that escape the configured workdir, and exposes fixed creation modes for directories and files. It also documents a remaining time-of-check/time-of-use limitation and recommends sandboxing for the toolset as a whole. When you create agents that can use local file tools, pair the setup with a sandboxed or otherwise controlled execution environment.

Sources: src/tools/agent-toolset/fs-util.ts

System-to-Code Mapping

Setup Checklist and Next Steps

A practical setup sequence is: choose the Claude model, name the agent, add behavior and capability configuration using the exported Managed Agents types, create the agent, persist its ID, and then verify it with retrieve or list. If the agent will use local file or shell tools, confirm that execution will happen in Node.js or a Node-compatible runtime and that tool operations are confined to the intended work directory. If the agent needs external tools through MCP or skill packages, model those capabilities in the agent configuration before sessions depend on them.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts, src/tools/agent-toolset/fs-util.ts, src/tools/agent-toolset/node.browser.ts

After setup, continue to the pages that cover runtime use of the configured agent. Read Managed Agent Sessions to start sessions from an agent ID, Session Event Streaming to process session events and deltas, Agent Skills for packaging reusable skills, MCP Integration for external tool servers, and Cloud Environments and Work when the agent needs sandboxed execution infrastructure.