September 24, 2026
A practical guide to Anthropic's server-hosted, persisted AI agents, and how they change the way you build with AI.
Most developers who start building with AI follow the same pattern. You send a message to the model, read the response, do something with it, and repeat. That works fine for simple tasks. Once a task needs multiple steps and tool use, you have a choice of how much of the plumbing you want to own. You can write the agentic loop yourself. You can let a helper in the Anthropic SDK, the Tool Runner, drive that loop for tools you define. Or you can hand the whole thing, loop and hosting both, to Anthropic. That third option is Managed Agents, and it is the one this post is about.
A Managed Agent is not a single API call. It is a persisted, versioned configuration, an Agent, that you create once, and a Session, which you start every time you actually want it to run. The model, the system prompt, the tools, and any MCP servers all live on the Agent. A Session references an Agent by ID and provisions a container as that run's workspace: bash, file operations, and code execution all happen inside that container. The agent loop itself runs on Anthropic's orchestration layer, acting on the container through tools, and the whole thing streams back to you as a series of events.
The two-step shape is not optional, and it exists for a real reason: versioning. Every update to an Agent creates a new immutable version. Sessions already running keep the version they started on; new sessions pick up the latest version, or pin to a specific one on purpose. That is what lets you tweak a system prompt or add a tool without breaking a session that is mid-task, and what lets you roll back a change that made things worse. Create the Agent once, store its ID, and every Session after that just points at it.
Here is the flow a Managed Agent actually follows:
client.beta.agents.create(...), giving it a model, a system prompt, and a list of tools. This happens once, in setup, not on every run.user.message event into the session, and open a stream to receive events back: agent.message for text, agent.tool_use or agent.custom_tool_use when the agent wants to act, and status events like session.status_idle when it is waiting on you.user.custom_tool_result event. Built-in tools, bash and file operations, run automatically inside the session's own container.Every event is part of a durable, inspectable session. You can list a session's events after the fact, download files the agent wrote to its workspace, and see exactly which tool ran with which input and why.
Install the Anthropic SDK:
pip install anthropic
Initialize the client. It resolves your API key from the ANTHROPIC_API_KEY environment variable automatically:
import anthropic
client = anthropic.Anthropic()
Create an environment, the container configuration your session will run inside:
environment = client.beta.environments.create(
name="my-dev-env",
config={
"type": "cloud",
"networking": {"type": "unrestricted"},
},
)
Create the agent. This is the one-time step: model, system prompt, and tools all live here, never on the session:
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-opus-5",
system="You are a careful, methodical coding assistant.",
tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
)
Start a session that references the agent by ID and version:
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment.id,
)
Open the event stream and send a message. Opening the stream first matters: it only delivers events that happen after it connects, so sending before streaming means the early events arrive buffered instead of live:
with client.beta.sessions.events.stream(session_id=session.id) as stream:
client.beta.sessions.events.send(
session_id=session.id,
events=[{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize what's in this workspace."}],
}],
)
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_idle":
print("\n--- Agent is waiting ---")
break
That is a complete, working Managed Agent: one Agent, created once, and one Session, streamed live.
There are really three tiers here, not two. Writing the agentic loop by hand gives you total control over every step, at the cost of owning error handling, retries, and state management yourself. The Tool Runner, a helper built into the regular Anthropic SDK, automates that loop for tools you define, but you still host the compute and you get no built-in tools or sandbox. Managed Agents goes a step further than either: Anthropic runs the loop and hosts the per-session container where tools actually execute, so there is no server to provision and no execution environment to secure.
That convenience comes with a real trade-off. A managed session gives you less control over exactly how the loop runs turn by turn than a hand-written loop does. If you need that level of control, or you need to run tool execution inside your own infrastructure for compliance reasons, a self-hosted sandbox or a DIY loop is the right tool. But for a session that just needs to read files, run commands, and get something done, Managed Agents removes an entire category of infrastructure you would otherwise have to build and operate.
Code review with real repository access. Attach a GitHub repository as a session resource, mounted straight into the container, and ask the agent to review it. It can read files, run the test suite through the built-in bash tool, and cite specific lines in its findings.
Research and reporting. Give the session a task with user.define_outcome instead of a plain message, along with a short rubric describing what a finished report needs. The agent iterates on its own output against that rubric until it passes, rather than stopping at a first draft.
Data processing with file output. Upload a CSV as a session resource. Ask the agent to clean it, calculate summary statistics, and write a report to the session's own output directory, which you can then list and download once the session goes idle.
Long-running, multi-step work. Because a session is a durable, streamed object rather than a single request-response pair, it comfortably handles tasks that take many tool calls and several minutes to finish, with every step logged and inspectable afterward.
Write custom tool descriptions the way you would write documentation for a junior developer. Be specific about what the tool does, what inputs it expects, and what it returns. Vague descriptions lead to tool calls made at the wrong time or with the wrong arguments.
Reconcile what the session needs before you create it, not after. Check that every action the task requires maps to a configured tool or MCP server, that every MCP server has a credential attached through a vault, and that every file or repository the agent will need is already mounted. A session that discovers a missing tool or credential mid-run does not fail cleanly, it flails.
Start with the built-in toolset alone, get a session working end to end, then add custom tools one at a time. Adding several custom tools at once and trying to debug a session that is behaving strangely is much harder than building incrementally.
Set a clear, specific system prompt on the agent, not the session, since that is where it actually lives. Tell it its role, the scope of what it should do, and any constraints it should respect.
The slide deck linked below is a companion reference for getting a Managed Agent running end to end, with code examples on each slide.
Download: How to Create a Claude Managed Agent (PowerPoint)
Managed Agents lower the barrier to running reliable AI workflows in production. The infrastructure question, where the loop runs and where tools execute, is answered for you. What remains is the interesting part: deciding what the agent should do, what tools and resources it actually needs, and what problem it is solving. That part is still yours to figure out, and it is the part worth spending time on.