Claude Managed Agents Custom Agent in 4 Steps — SSE Streaming and Tool Integration Guide

By /

Table of Contents

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"},
    ],
)

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

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

This single code block is essentially all it takes to set up a Claude Managed Agents custom agent. Define an Agent, create an execution environment, and open a session — three steps. Compared to building a custom agent loop from scratch, the reduction in code is dramatic. A single agent_toolset_20260401 activates all built-in tools including bash, file operations, and web search, and adding MCP servers extends connectivity to external APIs.

This article breaks down the internal architecture behind this code, the configuration options available when defining a team-specific agent, and the patterns for processing real-time events through SSE streaming.

The cost of a self-built agent loop — Why Claude Managed Agents custom agents matter

Building an AI agent from scratch involves far more than just calling a model. Tool execution runtimes, agent loop control, container isolation, state management, error recovery — infrastructure code outside the model call itself often accounts for over 70% of the total codebase. For smaller teams, this overhead can become a significant bottleneck.

Claude Managed Agents tackles this problem directly. It provides a pre-built, configurable agent harness that runs on managed infrastructure. Instead of building a custom agent loop, tool execution layer, and runtime from scratch, it offers a fully managed environment where Claude can read/write files, execute shell commands, search the web, and run code.

CategorySelf-built agentClaude Managed Agents
Agent loopCustom implementation (ReAct, Plan-Act, etc.)Managed harness provided
Tool execution runtimeSelf-managed containers/sandboxesCloud environment auto-provisioning
Built-in toolsEach implemented separatelySingle line with agent_toolset_20260401
MCP server integrationProtocol implemented manuallyConnected by specifying a URL
State managementSelf-managed session storeAutomatic Session resource management
Initial setup time2–4 weeks (including infrastructure)Hours (API-call level)
Available by default on all API accounts
Although currently in beta, Managed Agents is accessible from all Anthropic API accounts without a separate application. However, outcomes, multiagent, and memory features are in research preview status and require a separate access request.

In enterprise settings, infrastructure teams can afford to build and maintain a dedicated agent runtime. For smaller teams, however, that effort alone can become a bottleneck. Managed Agents provides a structural separation — delegating agent infrastructure to Anthropic so teams can focus exclusively on defining agent behavior and connecting tools.

Agent · Environment · Session · Events — 4 core concepts

Designing a Claude Managed Agents custom agent properly requires a clear understanding of the roles and boundaries of four core concepts.

Agent — defining the agent

An Agent is defined as a combination of model, system prompt, tools, MCP servers, and skills. It’s essentially a configuration object that declares “what this agent can do.” Once created, it can be reused across multiple Sessions, and version control is applied so configuration change history is preserved.

Environment — execution context

An Environment is the container context in which an agent runs. It’s created with the cloud type, and networking policies (unrestricted or restricted) can be configured. Agents and Environments are created independently and combined at the point of Session creation.

Session — execution instance

A Session is an execution instance created by combining an Agent and an Environment. It represents a single conversation context, and all messages and tool calls within the session are managed together.

Events — message exchange

Events are the channel through which an application and an agent exchange messages. The basic structure sends input via user.message and receives responses via agent.message. When custom tool calls are involved, agent.custom_tool_use and user.custom_tool_result events are exchanged as well.

The separation of Agent and Environment
Because Agent definitions and Environments are separated, the same Agent can run in development and production environments with different networking policies. For example, using unrestricted during development while allowing only specific domains in production.

Managed Agents API resource structure and constraints

According to the Managed Agents API resource reference, the API is organized into 9 resource groups: Agents, Sessions, Events, Resources, Environments, Vaults, Credentials, Files, and Skills. The key configurable parameters when creating an Agent are as follows.

  • model (required): The Claude model to use. e.g., claude-opus-4-7
  • system (optional): System prompt. Up to 100,000 characters
  • tools (optional): Tool array. Up to 50 items
  • skills (optional): Skill array. Up to 64 items
  • mcp_servers (optional): MCP server array. Up to 20 items
{
  "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/"
    }
  ]
}

An important detail is the Agent resource lifecycle. Agents can only be archived, not deleted. Once created, an Agent definition can be archived but never fully removed. This appears to be a design decision aimed at supporting version control and audit trails.

API rate limits

Rate limits are a critical consideration for production environments.

Endpoint typeLimit
Create (write)60 per minute
Read600 per minute

The Create limit of 60 per minute can become a bottleneck in patterns that dynamically create and delete agents. A practical strategy for team-specific agents is to pre-create Agent definitions and only create Sessions dynamically, effectively working around the rate limit.

Beta header required
All API endpoints require the anthropic-beta: managed-agents-2026-04-01 beta header. The Python/TypeScript SDK sets this header automatically, but when calling the REST API directly, it must be explicitly included. Omitting it may result in 404 or 400 responses.

Building a Claude Managed Agents custom agent — step-by-step implementation

The standard flow outlined in the Managed Agents quickstart guide consists of 4 steps: Create Agent → Create Environment → Start Session → Send events and stream.

Step 1: Create an Agent

This is the first step in defining a team-specific custom agent. name and model are required, and the system prompt constrains the agent’s behavior scope. Specifying agent_toolset_20260401 in the tools array activates all built-in tools — bash, file operations, web search — in a single declaration.

System prompt design arguably determines 80% of agent quality. With a maximum of 100,000 characters allowed, domain knowledge, coding conventions, and response formats can be specified in detail. However, longer prompts increase token consumption, so placing critical instructions at the beginning reduces the risk of important directives being truncated when hitting token limits.

Step 2: Create an Environment

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

An Environment defines the execution isolation boundary for an agent. The cloud type means it runs in an Anthropic-managed cloud container, and the networking setting controls network access scope. For agents that should only access internal team APIs, restricting the networking policy is the recommended security approach.

Step 3: Start a Session

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

Session creation combines an Agent ID and an Environment ID. At this point, the container is provisioned and the agent gains access to the specified tools and MCP servers. Since each Session represents a single conversation context, creating a new Session for each task is the common pattern.

Step 4: Send events and stream responses

Once a Session is open, interaction with the agent happens through events. The specific implementation of this step is covered in the next section alongside the SSE streaming pattern.

SSE streaming and event handling — the stream-first pattern

The core pattern presented in the Python SDK Managed Agents guide is the stream-first approach. 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}")

Three structural characteristics in this code deserve attention.

First, the stream is managed as a context manager. The stream stays alive within the with block and is automatically cleaned up when exiting. This structure prevents resource leaks during long-running agent tasks.

Second, event sending happens inside the stream. The connection is established first with stream(), then messages are sent via events.send(). If this order is reversed — sending messages before opening the stream — early events can be missed.

Third, branching by event type is essential. agent.message represents text responses, while agent.custom_tool_use represents custom tool call requests. Beyond these, handling session.status_idle and session.status_terminated events is necessary for complete session lifecycle management.

What stream-first means
Unlike the typical request-response pattern, stream-first corresponds to “start listening first, then speak.” It’s a common pattern in WebSocket-based real-time systems and serves as the foundation for agents to relay intermediate tool execution results in real time.

Returning custom tool results — custom_tool_use processing flow

Built-in tools (agent_toolset_20260401) alone aren’t sufficient for most real-world use cases. Internal API calls, database queries, and in-house authentication system integrations require custom tools. The execution flow for custom tools in a Claude Managed Agents custom agent works as follows.

[Agent] → agent.custom_tool_use event fired
              (includes tool_name, input, custom_tool_use_id)
                    ↓
[Application] → Execute tool (internal API call, etc.)
                    ↓
[Application] → Send user.custom_tool_result event
              (include custom_tool_use_id with the result)
                    ↓
[Agent] → Decides next action based on the result

The critical piece is matching the custom_tool_use_id. When the agent calls a custom tool, a unique ID is issued. The application must include this ID when returning the result. If the IDs don’t match, the agent can’t associate the result with the correct tool call.

Using MCP servers allows custom tools to be separated into independently versioned server units. Registering servers in the mcp_servers array during Agent creation automatically adds the tools exposed by those MCP servers to the agent’s tool list. With up to 20 connections supported, splitting MCP servers by domain is advantageous for scalability.

Built-in tools vs MCP server tools — selection criteria

CriteriaBuilt-in tools (agent_toolset)MCP server tools
Setup complexitySingle line (type specification)Build MCP server + register URL
Tool scopeBash, File ops, Web searchUnlimited (self-defined)
MaintenanceManaged by AnthropicManaged by the team
Access controlLimited via Environment networkingAuthentication at MCP server level
Best fitGeneral-purpose coding and search tasksInternal APIs, databases, auth integration

For general-purpose tasks, agent_toolset_20260401 is sufficient. But connecting team-specific business logic to an agent effectively requires MCP servers. Combining both approaches is the common pattern — secure baseline capabilities with built-in tools, then add domain-specific functionality through MCP servers. With a combined maximum of 50 tool registrations across built-in and MCP server tools, capacity limits rarely become a bottleneck.

Operational constraints and future possibilities — the reality of beta

Claude Managed Agents is in beta as of 2026-04-01, and the constraints that come with this status need to be clearly understood before production adoption.

Current constraints

Cost optimization guidance for production deployments (session time management, token savings) isn’t covered in the official documentation. Optimizing per-session token consumption requires independent experimentation with strategies like system prompt length tuning, session reuse, and disabling unnecessary tools.

Practical examples for error handling and retry patterns are also insufficiently covered in the official docs. Recovery strategies for mid-stream SSE disconnections or tool execution timeouts need to be designed internally.

No official documentation exists in Korean — all guides are provided in English only. API error messages are also in English, which is worth noting when debugging in Korean-language environments.

Research Preview features

Outcomes, multiagent, and memory features are in research preview status. Detailed documentation isn’t available, and access is only possible through a separate request. The multiagent feature in particular could be critical for scenarios orchestrating multiple Agents, but treating it as experimental at this stage is appropriate.

Stability of research preview features
The API interfaces for outcomes, multiagent, and memory are likely to change. Rather than forming production dependencies, a realistic approach is to use them at the prototyping level to validate possibilities.

Key areas on the expansion roadmap

Currently supported built-in tools consist of Bash, File operations (read/write/edit/glob/grep), Web search and fetch, and MCP servers. This toolset alone covers general-purpose scenarios like coding assistants, research agents, and data analysis agents.

Once the memory feature stabilizes, cross-session context retention becomes possible. When multiagent reaches general availability, it enables collaborative workflows between agents. The Managed Agents architecture overview provides insight into this roadmap direction. Modularizing Agent definitions with these future capabilities in mind minimizes transition costs when new features ship.

Agent definition modularization specifically means creating role-specific Agents instead of a single all-purpose agent, with system prompts and tool combinations optimized for each role. Defining separate agents for code review, documentation generation, and data pipeline tasks allows natural composition when multiagent orchestration becomes available. This approach aligns with the Anthropic Agent SDK’s design philosophy and also reduces the complexity of managed agents session management.

Read next

Scroll to Top