If you've built an agent loop by hand, you know the drill: while loops, stop reason switches, tool executions. That works, and for a lot of features it's actually the right shape. But sometimes that loop is going to run for a very long time — minutes, maybe even hours — across many tools, with state to keep, files to write, and work to resume after a network hiccup. At that point, you don't want to run the loop on your server. You want to delegate it. That's what managed agents are.
A managed agent is an agent loop that runs on Anthropic's infrastructure instead of yours. You describe the agent once, you give it an environment to work in, and you start a session. Anthropic runs the loop, and you just stream the events back out as it works.
Managed agents are enabled by default for every API account — no special access needed.
There are four primitives, and they come in order:
Here's how the pieces fit together: your app talks to a session, the session drives work inside the environment, and everything that happens flows back out through the event stream.
Notice the shift here: you're not running a while loop. You're sending events and reading events.
Let's build the smallest managed agent that does something useful: create a file in the temp drive, count its lines, and report back.
For tools, we'll use the agent toolset — Anthropic's bundled file, bash, and web tools. They work fine for this task, so we don't have to define any tools ourselves.
First, we create the agent. Note the agent toolset defined right in the tools array — that's the bundled toolset:
import anthropic
client = anthropic.Anthropic()
agent = client.beta.agents.create(
name="Line Counter",
model="claude-opus-5",
system="You are a helpful agent that completes small file tasks.",
tools=[
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
],
)
Anmelden an der Diskussion teilnehmen
Remember: the agent is reusable. Create it once and run it across many sessions.
Next, the environment. This spins up the container template — cloud, with unrestricted networking. This is the sandbox where the file actually gets written:
environment = client.beta.environments.create(
name="line-counter-env",
config={
"type": "cloud",
"networking": {"type": "unrestricted"},
},
)
Then we create a session with our agent and environment, plus an optional title. The session is the unit of work:
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Count lines demo",
)
Now we open the event stream — and notice that we do this first. The stream only delivers events that occur after it opens, so always open it before sending the kickoff message. Then we send the user message into the live stream:
with client.beta.sessions.events.stream(session_id=session.id) as stream:
# Stream is open — now send the kickoff
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Create a file in the temp directory, "
"count its lines, and report back.",
}
],
}
],
)
Notice it's events — plural. Events are how everything flows in this API.
Finally, we consume the stream. There are three event types that matter for this demo:
agent.message — Claude's textagent.tool_use — what tool Claude pickedsession.status_idle — the agent is done 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.tool_use":
print(f"\n[tool] {event.name}")
elif event.type == "session.status_idle":
print("\n--- Agent done ---")
break
Run it, and the output is the agent reasoning out loud — actual text, the tools it picks, and a final answer. All of it running inside Anthropic's container, not yours.
Usually with agents, we have our own loop where we have to control everything. With managed agents, you delegate that loop, the sandbox, and the resumability — and just consume the event stream as it comes in.
In a production app, this is the shape for long-running, file-touching, "go organize this for me" tasks. Picture a file share cleanup: a managed agent reads a target directory structure spec, walks the messy incoming folder, moves files into the right project folders, archives duplicates and zero-byte garbage, and flags anything it can't confidently place — all in a session that can run for minutes against thousands of files.
agent.message (text), agent.tool_use (tool picks), and session.status_idle (done).