Claude Managed Agents Guide — Build with Agent, Session, and Events in 4 Steps

By /

Table of Contents

There’s a common assumption that building an AI agent requires writing an orchestration framework from scratch. Whether it’s LangChain or CrewAI, the typical approach involves coding agent loops, implementing tool call logic, and managing container runtimes. Claude Managed Agents changes that premise. This managed agent infrastructure from Anthropic hides the loop, tool execution, and runtime behind the API — developers only need to define Agents and manage Sessions.

This article covers the four core concepts of Managed Agents, agent creation with the Python SDK, SSE streaming event handling, and MCP server integration, step by step. As of April 2026, the feature is in beta and accessible by default from all API accounts.

Four Core Concepts of Claude Managed Agents

Understanding Claude Managed Agents starts with distinguishing the four core resources. Without grasping this structure, the API call sequence and resource relationships quickly become confusing.

Agent — Agent Definition

An Agent is a configuration unit that bundles together a model, system prompt, tools, MCP servers, and skills. It defines which model to use, which tools to enable, and what the system prompt should be. Execution environments and conversation state are not part of the Agent resource.

Environment — Execution Environment

An Environment defines the container template where an agent runs. Infrastructure-level configurations like networking policies and cloud settings belong here. Since it’s separate from the Agent, the same Agent can run in different Environments.

Session — Running Instance

A Session is a running agent instance. Combining an Agent and an Environment to start a Session puts the agent in a state where it can send and receive messages. Multiple Sessions can run simultaneously from a single Agent.

Events — Message Exchange

Events are the channel for exchanging messages between the application and the agent. Sending user messages, receiving agent responses, and returning custom tool call results all happen through Events.

ResourceRoleAnalogy
AgentModel, tools, prompt configurationDocker image definition
EnvironmentContainer templateDocker Compose configuration
SessionRunning instanceRunning container
EventsMessage exchange channelstdin/stdout stream

These four resources make up the entire Managed Agents architecture. The relationship between each resource can be visually confirmed in the Managed Agents architecture overview.

Version Control and Deletion Policy
Agents can only be archived, not deleted. Version control is applied, so previous versions are preserved when settings change. Rolling back from an accidental overwrite is possible with this approach.

Claude Managed Agents Quickstart — 4 Steps

Getting an agent up and running involves four steps: Create Agent → Create Environment → Start Session → Send Events and Stream. All endpoints require the anthropic-beta: managed-agents-2026-04-01 beta header, but the Python SDK sets this header automatically.

Step 1: Create an Agent

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding assistant. Write clean, well-documented code.",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
)

Specifying the agent_toolset_20260401 tool type activates all built-in tools — bash, file operations, web search, and more — at once. There’s no need to register tools individually with this type.

Step 2: Create an Environment

environment = client.beta.environments.create(
    name="quickstart-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

The unrestricted value in the networking setting allows external network access. Production environments would typically restrict this, but detailed networking policy options aren’t yet specified in the official documentation.

Step 3: Start a Session

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)

Combining the Agent ID and Environment ID creates a Session. From this point, the agent is ready to receive messages.

SDK Beta Header Auto-Configuration
Using beta namespaces like `client.beta.agents` and `client.beta.sessions` automatically includes the `anthropic-beta: managed-agents-2026-04-01` header. Manual header addition is only necessary when calling the REST API directly.

API Structure and Configuration Options for Agent Creation

The Managed Agents API consists of nine resource groups: Agents, Sessions, Events, Resources, Environments, Vaults, Credentials, Files, and Skills. The most frequently used configuration options for Agent creation are outlined below.

The request body structure for Agent creation looks like this:

{
  "name": "string (required, 1-256 chars)",
  "model": "claude-opus-4-7",
  "system": "string (optional, up to 100,000 chars)",
  "tools": [
    { "type": "agent_toolset_20260401" }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ]
}

model is a required field, and system accepts up to 100,000 characters. The limits are 50 for tools, 64 for skills, and 20 for mcp_servers. Exceeding these limits returns an API error, so keeping these ceilings in mind is important when building complex agents.

FieldRequiredLimitPurpose
nameRequired256 charsAgent identifier name
modelRequired—Claude model to use
systemOptional100,000 charsSystem prompt
toolsOptional50Built-in/custom tools
skillsOptional64Reusable skills
mcp_serversOptional20External MCP server connections

Rate Limits

Create endpoints are rate-limited to 60 requests per minute, and read endpoints to 600 requests per minute. Patterns that create Agents dynamically — for example, creating a new Agent per user request — can hit this limit quickly. Pre-creating Agents and only spinning up new Sessions is more favorable from a rate-limiting perspective.

Create Endpoint Rate Limit
Exceeding 60 requests per minute returns a 429 error. The recommended pattern is to reuse Agents and only create new Sessions. Practical examples for error handling and retry patterns are not yet covered in detail in the official documentation.

Handling Claude Managed Agents Events with SSE Streaming

After creating a Session, SSE streaming must be set up to actually communicate with the agent. In the Python SDK, SSE streaming follows a stream-first pattern — open the stream first, then send messages within it.

with client.beta.sessions.stream(
    session_id=session.id,
) as stream:
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.custom_tool_use":
            print(f"\nCustom tool call: {event.tool_name}")

Several aspects of this code are worth noting.

First, client.beta.sessions.stream() opens the stream. The HTTP connection stays open, allowing messages to be sent and responses received in real time.

Second, events.send() transmits the user message. The event type is user.message, and a text block is placed inside the content array.

Third, branching logic based on incoming event types is necessary. agent.message corresponds to the agent’s text response, and agent.custom_tool_use represents a custom tool call request. Additionally, session.status_idle and session.status_terminated events exist for tracking session state changes.

Complete List of Incoming Event Types

Incoming event types from the stream are categorized by role. Knowing when each type fires helps prevent gaps in branching logic.

Event TypeTrigger PointHandler
agent.messageAgent text response completeApplication
agent.custom_tool_useCustom tool call requestApplication (execute and return result)
session.status_idleAgent enters input-waiting stateState monitoring / session termination trigger
session.status_terminatedSession termination completeResource cleanup

session.status_idle indicates the agent has finished tool execution and is waiting for the next user input. This event can serve as the timing reference for sending follow-up messages or closing the session.

Returning Custom Tool Results

When the agent calls a custom tool, the application must execute it and return the result. This is done by sending a user.custom_tool_result event type that includes the custom_tool_use_id. Built-in tools (bash, file operations, etc.) are executed directly by the Managed Agents infrastructure, so this process isn’t needed for them. However, custom tools like external API calls must be handled by the application, with results injected back into the stream.

This pattern is essentially a cooperative execution model. The agent requests “execute this tool,” the application runs it and returns the result — a ping-pong structure. The full custom tool handling flow can be found in the Python SDK Managed Agents streaming guide.

Built-in Tools and MCP Server Integration

Built-in tools provided by Managed Agents fall into four categories:

  • Bash: Shell command execution — package installation, script execution, system commands
  • File operations: File read, write, edit, glob pattern search, grep search
  • Web search and fetch: Web search and page content retrieval
  • MCP servers: Connections to external MCP servers

Specifying the single agent_toolset_20260401 type activates all of the above. A method to selectively disable individual tools is not specified in the official documentation.

MCP Server Integration Architecture

MCP (Model Context Protocol) servers are added to the mcp_servers array during Agent creation. As shown in the API structure section, each entry consists of three fields: type, name, and url, with a maximum of 20 connections. Since the agent automatically discovers and calls tools from MCP servers at runtime, simply configuring the connection makes the MCP server’s capabilities available without separate tool registration.

[Application]
    ↓ events.send(user.message)
[Session / Managed Agents Runtime]
    ↓ Tool call decision
    ├─ Built-in tools → Executed directly by runtime
    ├─ MCP server tools → Called via MCP protocol
    └─ Custom tools → Delegated to app via agent.custom_tool_use event

Built-in tools and MCP tools are handled internally by the runtime, requiring no additional application code. Only custom tools need the event-based ping-pong pattern described in the previous section.

Tool Count and MCP Server Count Limits
The 50-tool limit and 20-MCP-server limit are counted separately. Since a single MCP server can provide multiple tools, the total number of usable tools may exceed 50. However, too many tools can reduce the model’s tool selection accuracy.

Beta Limitations and Current Constraints

Claude Managed Agents is in beta as of April 2026. Core features — Agent, Environment, Session, and Events — are available to all API accounts, but some extended features have restricted access.

Research Preview Features

Outcomes, multiagent, and memory features are in research preview status, requiring separate access requests. Detailed documentation for these features is not yet available in the official docs.

Currently Undocumented Areas

Guidance on cost optimization for production deployments — session duration management, token-saving strategies — is not specified in the official documentation. Practical examples for error handling and retry patterns are also lacking. Additionally, no official documentation is available in Korean; all official guides are provided in English only.

FeatureStatusAccess Method
Agent/Environment/Session/EventsBeta (default)All API accounts
OutcomesResearch previewSeparate access request
MultiagentResearch previewSeparate access request
MemoryResearch previewSeparate access request

Session Lifecycle and Cost Management Strategies

No explicit session billing structure is documented yet, but practical patterns are worth considering. A Session remains alive from creation until a session.status_terminated event is received. Failing to explicitly terminate sessions after conversations end can lead to idle session accumulation.

Three patterns are recommended. First, explicitly call the session termination API when a conversation ends. Second, add timeout logic that closes the session if no follow-up message arrives within a set period after receiving a session.status_idle event. Third, for consecutive conversations from the same user, reuse the existing Session instead of creating a new one to maintain context. Note, however, that session reuse means previous conversation context consumes tokens.

Beta API Change Risk
As the beta header `managed-agents-2026-04-01` suggests, the API spec is managed with date-based versioning. Endpoints and request formats may change at general availability, so version pinning and migration planning should be factored into production adoption.

Claude Managed Agents Summary and Practical Adoption Strategy

Three practical points to consider when adopting Managed Agents:

First, reusing Agents and creating only new Sessions is the default pattern. Given the 60-per-minute limit on Agent creation API calls, pre-defining agent configurations and opening a new Session per conversation is the rational approach.

Second, built-in tools alone cover a substantial range of automation. With bash, file operations, and web search provided by default, code generation, execution, and verification loops can run entirely within the agent runtime. MCP servers or custom tools only need to be added when external system integration is required.

Third, understanding the stream-first pattern of SSE streaming is essential. Opening the stream before sending messages may feel counterintuitive, but this pattern enables real-time response reception simultaneous with connection establishment.

Practical Adoption Checklist:

1. Agent design    → Define model, system, tools
2. Environment     → Determine networking policy
3. Session mgmt    → Design creation/termination lifecycle
4. Event handling  → stream-first + custom tool handler
5. Monitoring      → Watch session.status_idle / terminated

Once the Claude Managed Agents API stabilizes, several areas are worth exploring next. The multiagent feature, currently in research preview, is expected to enable workflows where multiple agents collaborate. The memory feature will likely support context persistence across sessions. As the MCP server ecosystem expands, the scope of external system integration through Claude MCP server connections will broaden as well. Using the Managed Agents quickstart guide as a baseline and tracking API version changes to gauge production readiness is a practical adoption strategy for Claude Managed Agents.

Read next

Scroll to Top