How to start a first Claude Managed Agents session

Claude Managed Agents is Anthropic's hosted harness for running Claude as an autonomous agent. The overview contrasts it with the Messages API: direct model prompting is for custom agent loops and fine-grained control. Managed Agents is a pre-built, configurable harness on managed infrastructure, for long-running tasks and asynchronous work. You do not build the agent loop, tool execution, or runtime. The harness supplies those, plus built-in prompt caching, compaction, and other performance optimizations, so Claude can read files, run commands, browse the web, and run code securely.

This is a setup guide, not a product announcement. It follows the official quickstart: install the CLI or the Python SDK, create an agent and an environment, start a session, and stream events.

The four objects

The overview and the quickstart use the same four concepts.

Agent — the model, system prompt, tools, MCP servers, and skills. Create it once and reference it by ID across sessions.
Environment — where sessions run: an Anthropic-managed cloud sandbox, or a self-hosted sandbox on your own infrastructure.
Session — a running agent instance within an environment, performing a specific task and generating outputs.
Events — messages exchanged between your application and the agent (user turns, tool results, status updates).

The documented order is create the agent, create the environment, start a session that references both, then send user messages as events. Claude runs tools on its own and streams results through server-sent events. Event history is persisted server-side and can be fetched in full. You can send more user events to steer a run, or interrupt it and change direction.

Use this harness when a task runs for minutes or hours, needs a cloud or self-hosted sandbox, should keep a filesystem and conversation history, or should run on a recurring schedule. Use the Messages API when you want to own the loop.

Account, key, and the beta header

The quickstart's prerequisites are a Claude Console account and an API key.

The overview's beta-access list adds two requirements: the managed-agents-2026-04-01 beta header on all requests, and access to Claude Managed Agents, which the docs say is enabled by default for all API accounts. The quickstart does not show a sample header line, and it does not say that an SDK attaches that header for you. Keep the header on every request.

MCP tunnels and dreaming are not part of this first session. Within the beta, the overview places both in a more limited research preview and says to request access to enable them.

Sessions are stateful: long-running, able to resume after pauses, and storing conversation history, sandbox state, and outputs server-side. Because of that, the overview says Managed Agents is not currently eligible for Zero Data Retention or a HIPAA Business Associate Agreement. You can delete sessions, and separately delete files you uploaded, through the API.

Install the CLI or the Python SDK

The agent and environment examples below are the CLI forms from the quickstart. The session-create example is the Python form. The page lists other language tabs; this guide does not add commands from tabs it does not quote.

On macOS with Homebrew:

brew install anthropics/tap/ant

On Linux or WSL, the quickstart downloads a pinned release and extracts the ant binary. It also points to the CLI GitHub releases page for every release. Do not substitute another version number unless you have confirmed it there.

VERSION=1.39.1
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

From source, with Go 1.25 or later:

go install github.com/anthropics/anthropic-cli/cmd/ant@latest

The binary is placed in $(go env GOPATH)/bin. If that directory is not already on your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Check the install:

ant --version

Python SDK:

pip install anthropic

Set the key the quickstart shows. Replace the placeholder with your own key. This page does not document another variable name.

export ANTHROPIC_API_KEY="your-api-key-here"

Create the agent

The agent file sets the model, the system prompt, and the tools. The quickstart's CLI example is coding-assistant.md:

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding assistant. Write clean, well-documented code.

Apply it:

ant apply coding-assistant.md

ant apply prints the agent's ID and records it in claude-lock.json. You reference that ID in every session you create.

The tool type agent_toolset_20260401 enables the full set of pre-built agent tools: bash, file operations, web search, and more. The overview's built-in list is shell commands in the sandbox, file read, write, edit, glob, and grep, web search and fetch (optionally restricted to an allowlist or blocklist of domains), and MCP servers. Per-tool options live on the tools page the quickstart links; they are not repeated here.

Create the environment

An environment is the sandbox configuration. This quickstart uses a cloud sandbox with limited networking and package managers allowed, so code running in the sandbox can reach public package registries and code hosts. Web search and web fetch run outside the sandbox, and this quickstart does not need them. With limited networking, the allowed_hosts list applies to those tools too. They return no pages or search results in this environment, because the file lists no hosts. For your own agent, list the hosts it needs in allowed_hosts. The sample itself does not include that list.

Save environment.yaml as the quickstart shows it:

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: quickstart-env
config:
     type: cloud
     networking:
       type: limited
       allow_package_managers: true

Apply it:

ant apply environment.yaml

That records the environment ID in claude-lock.json as well. To create the agent and the environment with one command:

ant apply coding-assistant.md environment.yaml

Start a session and stream events

The Python session call in the quickstart uses agent.id and environment.id. The lines that construct those objects are not in the quickstart text used here. If you created the resources with ant apply, take the IDs from claude-lock.json. Do not guess a constructor the quickstart does not show.

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

print(f"Session ID: {session.id}")

The next quickstart step opens a stream on that session, sends a user event after the stream opens, and processes events as they arrive. The published Python sample for that send keeps trailing backslashes on the payload lines. Those lines are not repeated here, because a cleaned rewrite would not match the page. Copy that sample from the quickstart itself. Replace the send-and-stream step with the sample on that page.

What that sample does is described on the page. It sends one user message asking for a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. The handler prints text from agent.message, logs each agent.tool_use by name, and stops on session.status_idle.

The quickstart says the agent writes a Python script, runs it in the sandbox, and verifies the output file was created. It shows output similar to this:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

Treat that block as the docs' illustration, not a guaranteed transcript.

When you send a user event, the quickstart says Claude Managed Agents provisions a sandbox from your environment configuration, runs the agent loop and chooses tools from your message, runs file writes, bash commands, and other tool calls inside the sandbox, streams events as the agent works, and emits session.status_idle when it has nothing more to do.

Try this next

Apply the coding-assistant file and quickstart-env, start a session with the IDs in claude-lock.json, then copy the quickstart's send-and-stream sample and watch the event stream. Leave MCP tunnels and dreaming off until you have the research-preview access the overview describes. For versioned agent configuration, networking, per-tool settings, or steering mid-run, use the next-step links on the quickstart page rather than inventing flags. Those follow-on pages are not reproduced here.