Claude Managed Agents Setup Guide — From Agent·Session Separation to Streaming in 5 Steps

Table of Contents

• Claude Managed Agents Architecture — Agent and Session Separation
  • Components of an Agent Configuration Object
  • Session Lifecycle
• Claude Managed Agents Setup Guide — 3-Step Onboarding
  • Suitable Scenarios by Pattern
• SSE Streaming in Python — The Stream-First Pattern
  • Why Stream-First Is Necessary
  • File Upload Handling
• Vault Credential Management and Security Setup
  • Considerations When Using Vault
• Claude Agent SDK vs. Managed Agents Comparison
  • Which One to Choose
• Practical Setup Pitfalls and Troubleshooting
  • Missing Beta Header
  • Handling Idle State During Custom Tool Calls
  • Environment Configuration Mistakes
• Pre-Production Checklist and Next Steps

The core takeaway of this Claude Managed Agents setup guide is understanding the architecture that separates Agent (a persistent configuration object) from Session (a runtime instance). An Agent is created once, and only a new Session is spawned for each execution — eliminating the need to repeatedly send model and system prompt parameters as with the Messages API. This article covers the Managed Agents architecture, onboarding procedure, Python streaming implementation, security setup, and a comparison with the Agent SDK, all with code examples.

Claude Managed Agents Architecture — Agent and Session Separation

The design philosophy of Managed Agents centers on complete separation of configuration and execution. An Agent is a persistent configuration object that defines the model type, system prompt, and list of tools. Once created via POST /v1/agents, an agent.id is issued, and all subsequent references use this ID alone.

A Session is a runtime instance created from an Agent — effectively the unit where actual conversations take place. Passing agent.id to POST /v1/sessions starts a new Session. Each Agent update creates a new immutable version, and any already-running Session retains its pinned version. This means configuration changes don’t affect work in progress.

# ONE-TIME: Create agent
agent = client.beta.agents.create(
    model="claude-opus-4-7",
    system="You are...",
    tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}]
)
agent_id = agent.id

# EVERY RUN: Create session
session = client.beta.sessions.create(agent=agent_id)

The benefits of this pattern are clear. Agent configuration is version-controlled in one place, while execution is isolated at the Session level. Consider a database migration agent as an example: DB schema analysis tools and the system prompt are defined in the Agent, and a new Session is created for each migration request. When configuration changes are needed, the Agent is updated, but existing Sessions continue running on the previous version — enabling zero-downtime rollouts.

Components of an Agent Configuration Object

The key parameters passed during Agent creation are model, system (system prompt), and tools (tool array). The tools array can combine three types: agent_toolset_20260401 (built-in default tools), MCP server integration tools, and Custom tools. All Managed Agents API calls require the managed-agents-2026-04-01 beta header.

Session Lifecycle

A Session transitions through created → active → idle → terminated. When a Custom tool call occurs, the Session switches to idle, and the client must return results via a user.custom_tool_result event to bring it back to active. Failing to understand this state transition can lead to infinite hangs during streaming implementation.

Claude Managed Agents Setup Guide — 3-Step Onboarding

According to the Managed Agents onboarding guide, onboarding consists of three stages.

Step 1 — Choose a Pattern: Determine the agent’s execution mode. Options include event-triggered (auto-execution on webhook receipt), cron (periodic execution), fire-and-forget PR (auto-terminate after code review), and research + dashboard (data collection followed by report generation).

Step 2 — Configure Tools: Set up the tools the agent will use. Tools fall into three categories.

Tool Type	Description	Example Use
agent_toolset_20260401	Anthropic built-in tools	File read/write, code execution
MCP tools	External MCP server integration	GitHub, Slack, DB access
Custom tools	User-defined function calls	Internal API calls, data transformation

Step 3 — Environment + Session Setup: Create an Environment, create the Agent, then start a Session — in that order.

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

agent = client.beta.agents.create(
    name="my-agent",
    model="claude-opus-4-7",
    tools=[{"type": "agent_toolset_20260401"}],
    system_prompt="..."
)

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

An Environment defines the infrastructure context in which the agent runs. Setting networking to unrestricted enables external network access; restrictions can be applied via separate configuration when needed. Narrowing network policies is recommended for production environments, though detailed options for this are not specified in the official documentation.

Suitable Scenarios by Pattern

The event-triggered pattern suits agents that react to notifications from external systems like GitHub webhooks or Slack events. The cron pattern fits batch workloads such as daily log analysis or periodic data collection. The fire-and-forget PR pattern covers agents that perform code review when a PR is opened, leave comments, and auto-terminate. The research + dashboard pattern is used for collecting information from multiple sources and generating summary reports.

SSE Streaming in Python — The Stream-First Pattern

The most important concept in the Python implementation of Managed Agents is the stream-first pattern. Unlike the typical request-response model where a message is sent first and the response awaited, Managed Agents requires opening the stream first and sending messages within it. Reversing this order can result in lost events.

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": "Review the auth module"}]}]
    )
    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 == "session.status_terminated":
            break

After installing the SDK with pip install anthropic, running the code above receives agent responses in real time via SSE (Server-Sent Events). client.beta.sessions.stream() opens the stream as a context manager, and events.send() transmits user messages from within that context.

A critical point in the event loop: the session.status_terminated event must be handled. Ignoring it leaves the stream open and the process waiting indefinitely. For agents that include Custom tool calls, idle state detection and user.custom_tool_result event dispatch logic are also required.

Why Stream-First Is Necessary

In a standard HTTP request-response model, a request is sent and the client waits for a response. Managed Agents Sessions, however, may perform long-running tasks and require bidirectional communication for exchanging tool call results mid-execution. Establishing the SSE stream first ensures that every event the agent generates — messages, tool calls, state transitions — is received without loss.

File Upload Handling

When files need to be passed to an agent, the Files API is used. A separate files-api-2025-04-14 beta header is required, and the uploaded file’s ID is included in the message event. Specific details on file size limits and supported formats are not specified in the official documentation.

Vault Credential Management and Security Setup

When configuring agents that integrate with MCP servers or access external APIs, embedding authentication credentials directly in the agent configuration creates security risks. Managed Agents solves this with a Vault system. Credentials are stored in a Vault, and Sessions reference them via vault_ids at creation time.

# Store credentials in Vault
vault = client.beta.vaults.create()
cred = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    type="github",
    github_token="ghp_xxxx"
)

# Reference vault in Session
session = client.beta.sessions.create(
    agent=agent.id,
    vault_ids=[vault.id]
)

The key point is that the Agent configuration itself never contains tokens or passwords. The Agent only knows “use GitHub tools” — actual authentication credentials are injected at runtime when the Session accesses the Vault. Anthropic also handles automatic OAuth token renewal, reducing downtime caused by token expiration.

Considerations When Using Vault

GitHub tokens are a confirmed credential type for Vault storage, but the complete list of supported types is not specified in the official documentation. For general-purpose credentials like database connection strings or AWS keys, a separate authentication flow combined with Custom tools may be necessary. Pricing details (per-session costs, container time billing, etc.) are also unavailable in the current documentation, so contacting the Anthropic sales team directly before production deployment is the safest approach.

Claude Agent SDK vs. Managed Agents Comparison

Both the Claude Agent SDK (claude-agent-sdk) and the Managed Agents API are tools for building agents, but comparing the Agent SDK Python repository and the Managed Agents architecture documentation reveals different approaches.

Comparison	Managed Agents API	Claude Agent SDK
Installation	pip install anthropic	pip install claude-agent-sdk
Python Version	SDK default requirements	Python 3.10+
Execution Environment	Anthropic cloud (Environment)	Local or self-hosted server
State Management	Server-side Agent/Session management	Client-side manual management
Tool Definition	Declared as API parameters	@tool decorator
MCP Server	Integrated in agent configuration	In-process MCP server creation
Access Control	Vault + network policies	Hooks system (PreToolUse)
Version Management	Automatic immutable versioning	Manual management
Bidirectional Communication	SSE streaming	ClaudeSDKClient
Simple Queries	Session-based	query() function

The Agent SDK runs agents directly in a local environment. Defining tools with the @tool decorator creates an in-process MCP server, and the Hooks system’s PreToolUse controls permissions before tool execution.

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

server = create_sdk_mcp_server(
    name="my-tools", version="1.0.0", tools=[greet_user]
)

Managed Agents runs on Anthropic’s cloud, reducing infrastructure management overhead. The Agent SDK runs on self-hosted servers, making it easier to access internal systems without network latency or data exfiltration concerns. The exact relationship and integration path between the two tools is not specified in the official documentation.

Which One to Choose

The decision typically comes down to where the execution environment lives and how much operational overhead is acceptable. For fully managed execution on Anthropic’s cloud, Managed Agents is the better fit. For running agents on private infrastructure with fine-grained control, the Agent SDK is the stronger option. Both approaches support the MCP protocol, so tool definitions are likely compatible — though no official documentation guarantees this at present.

Practical Setup Pitfalls and Troubleshooting

Several common issues arise when setting up Managed Agents in practice.

Missing Beta Header

The most frequent mistake is omitting the beta header. The Python SDK’s client.beta.* namespace includes the header automatically, but when calling directly via curl or other HTTP clients, the managed-agents-2026-04-01 header must be added manually. Without it, 404 or 400 errors are returned, and the error message alone doesn’t always make it obvious that a missing header is the cause.

Handling Idle State During Custom Tool Calls

When a Custom tool call occurs in an agent, the Session transitions to idle. If the client doesn’t return results via a user.custom_tool_result event, the Session stays idle indefinitely. Logic to detect the idle state and set appropriate timeouts in the streaming event loop is essential.

[Flow Summary]
1. Agent invokes custom tool → Session transitions to idle
2. Client executes the tool → sends result as user.custom_tool_result
3. Session returns to active → Agent continues based on the result

Environment Configuration Mistakes

Deploying to production with the Environment’s networking set to unrestricted allows the agent to access unintended external services. Even if this setting is left open for convenience during development, narrowing the network policy before production deployment is recommended. Detailed network policy options are not specified in the official documentation.

Pre-Production Checklist and Next Steps

Before deploying Managed Agents to production, refer to the checklist below.

Check Item	What to Verify	Notes
Beta header	managed-agents-2026-04-01 included in all calls	Automatic with SDK
Vault setup	Credentials not embedded directly in Agent config	Verify token auto-renewal
Archive prevention	Block archive calls on production Agents	No recovery possible
Network policy	Remove unrestricted from Environment	Principle of least privilege
Idle timeout	Prevent infinite waits on Custom tool calls	Implement in streaming loop
Stream order	Follow stream-first pattern	Prevent event loss
Monitoring	Log Session state transitions	No official guide available

No official guide for monitoring and alerting currently exists, so Session state transitions must be logged manually by consuming the event stream. Pricing is also not publicly disclosed, so contacting Anthropic directly is the only way to get cost estimates.

Once the Managed Agents setup is complete, MCP server integration is a logical next step. Connecting external systems like GitHub, Slack, and databases as MCP tools significantly expands what the agent can do. Building a local MCP server with the Claude Agent SDK’s @tool decorator is another approach that can run alongside Managed Agents. Setting up an Eval pipeline that automatically evaluates agent execution results by input, output, and tool call is also an essential topic for production operations. With the fundamentals of Claude Managed Agents setup in place, these extended areas are where meaningful differentiation happens.

Read next

docker GPT-5.5 API Migration in 7 Steps — Breaking Changes and Docker Setup May 4, 2026

database TypeScript 7 Beta Benchmark Results — CI Performance Bottleneck Analysis May 3, 2026

aws GPT-5 API Guide: Responses API Migration and Parameter Tuning April 26, 2026