Quickstart

Claude Managed Agents quickstart

Use this guide to build the first working Managed Agents session without mixing up agents, environments, sessions, and event streams.

Last updated

2026-04-12

Official sources

Managed Agents quickstart Managed Agents overview Container reference Session tracing

Before You Start

Get the access and environment assumptions right before you debug the agent itself.

If these prerequisites are missing, the first session usually fails in ways that look mysterious but are actually configuration gaps.

Create a Claude Console account and an API key before you touch the session endpoints.

Use the managed-agents-2026-04-01 beta header on direct API calls. The SDK adds it for you.

Decide which model, prompt, and tool scope belong in the first agent before you open a session.

Be explicit about network access when you create the environment because the default container starts with networking off.

First Session Flow

The shortest path is agent, environment, session, then events.

The quickstart stays short because Managed Agents only has a few first-class primitives.

1. Create the agent

Define the model, system prompt, tools, MCP servers, and skills once. Anthropic treats the agent definition as a reusable object you reference by ID later.

2. Create the environment

Create a cloud environment that defines packages, mounted files, and network access rules. This is the runtime container the session will use.

3. Start and steer the session

Start a session tied to the agent and environment, then post user events and stream results over SSE until the session goes idle.

Core Request

Start with a single session and a single event loop.

The first useful prototype only needs one session, one user event, and one stream of agent events coming back.

bash

This code example is adapted from the official quickstart and keeps the same order of operations while trimming extra scaffolding.

# Create a session
session=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": "agent_01...",
    "environment_id": "env_01...",
    "title": "Quickstart session"
  }')

SESSION_ID=$(jq -er '.id' <<<"$session")

# Send a user event
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{
        "type": "text",
        "text": "Inspect this project and summarize the deployment risks."
      }]
    }]
  }'

Early Failure Modes

Most quickstart failures are configuration failures, not model failures.

These are the first problems teams usually hit once the agent object exists.

Dimension	Problem	Likely cause	First fix
API rejects the request	Requests fail before the session even starts.	The beta header or API key is missing.	Add the managed-agents beta header and verify account credentials before changing the prompt.
External access does not work	The agent cannot reach external resources you expected it to use.	Networking is still disabled in the environment config.	Create or update the environment with the correct network policy.
It runs but you cannot tell what happened	The session appears idle but the useful output is hard to interpret.	You are not reading the event stream or inspecting session events directly.	Stream SSE events in real time and fetch the stored event log when debugging.

FAQ

Keep the quickstart mental model small and concrete.

These are the questions that help most when you are translating docs into the first working prototype.

Can I prototype in Console before I wire this into my app?+

Yes. Anthropic documents Console as a visual way to create and test the same agent and session resources before you move configuration into code.

Is creating a session enough to start useful work?+

Not by itself. A session gives you a running instance. You still need to send user events and then watch the event stream or fetch events later.

Keep moving with the page that matches the next decision.

These pages are the shortest path to the next question most teams hit.

What is Claude Managed Agents?

Use this page when you need a compact explanation of the hosted runtime, the core concepts, and the workloads that match Managed Agents best.

Open page

Claude Managed Agents pricing and limits

Use this page when you need the operational limits and runtime envelope before you promise capacity or security posture.

Open page

Claude Managed Agents troubleshooting

Use this page when a session is failing, stuck, or acting unlike the runtime you thought you configured.

Open page

Stay Updated

Want updates as Managed Agents evolves?

Use the waitlist if you want the next update without checking the docs every week.

Waitlist

Want updates as Managed Agents evolves?

Get a short email when this guide adds new examples, API changes, or managed-agents implementation notes.