Deinen ersten Managed Agent erstellen
Wenn du schon einmal eine Agent-Loop von Hand gebaut hast, kennst du den Ablauf: while-Schleifen, stop-reason-Switches, Tool-Ausführungen. Das funktioniert, und für viele Features ist das tatsächlich die richtige Form. Aber manchmal läuft diese Schleife sehr lange — Minuten, vielleicht sogar Stunden — über viele Tools hinweg, mit Zustand, der erhalten werden muss, Dateien, die geschrieben werden müssen, und Arbeit, die nach einem Netzwerkaussetzer fortgesetzt werden muss. An diesem Punkt willst du die Schleife nicht auf deinem Server laufen lassen. Du willst sie delegieren. Genau das sind Managed Agents.
Was ist ein Managed Agent?
Ein Managed Agent ist eine Agent-Loop, die auf Anthropics Infrastruktur läuft statt auf deiner eigenen. Du beschreibst den Agent einmal, gibst ihm eine Umgebung, in der er arbeiten kann, und startest eine Session. Anthropic führt die Schleife aus, und du streamst einfach die Events zurück, während sie läuft.
Managed Agents sind standardmäßig für jedes API-Konto aktiviert — kein besonderer Zugriff erforderlich.
Die vier Primitive
Es gibt vier Primitive, und sie folgen in dieser Reihenfolge:
- Agent — die Persona: Modell, System-Prompt und Toolset. Das ist über viele Durchläufe hinweg wiederverwendbar.
- Environment — wo der Agent läuft: Cloud oder selbst gehostet, Netzwerkkonfiguration und so weiter.
- Session — ein einzelner Durchlauf eines Agents innerhalb einer bestimmten Environment. Die Session ist die Arbeitseinheit.
- Events — die Nachrichten, die rein- und rausfließen: die Aktionen des Agents, die Tool-Aufrufe, die Ergebnisse, die Antworten.
So passen die Teile zusammen: Deine App spricht mit einer Session, die Session treibt die Arbeit innerhalb der Environment an, und alles, was passiert, fließt über den Event-Stream zurück:

Beachte die Verschiebung hier: Du führst keine while-Schleife aus. Du sendest Events und liest Events.
Der kleinstmögliche Managed Agent
Lass uns den kleinsten Managed Agent bauen, der etwas Nützliches tut: eine Datei im temporären Laufwerk erstellen, ihre Zeilen zählen und zurückmelden.
Für Tools verwenden wir das Agent-Toolset — Anthropics gebündelte Datei-, Bash- und Web-Tools. Sie funktionieren für diese Aufgabe einwandfrei, sodass wir keine eigenen Tools definieren müssen.
Schritt 1: Den Agent erstellen
Zuerst erstellen wir den Agent. Beachte das Agent-Toolset, das direkt im tools-Array definiert ist — das ist das gebündelte 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}}
],
)Denk daran: Der Agent ist wiederverwendbar. Erstelle ihn einmal und führe ihn über viele Sessions hinweg aus.
Schritt 2: Die Environment erstellen
Als Nächstes die Environment. Sie definiert die Sandbox, in der dein Agent läuft: Cloud, mit limited-Networking. Mit limited erreichen die Sandbox und die Web-Tools nur die Hosts, die du in allowed_hosts aufführst. Diese Aufgabe benötigt kein Netzwerk, also listen wir keine auf. Verwende unrestricted nur, wenn der Agent Seiten erreichen muss, die du nicht im Voraus auflisten kannst. Jede Session bekommt ihre eigene Sandbox, und dort wird die Datei geschrieben:
environment = client.beta.environments.create(
name="line-counter-env",
config={
"type": "cloud",
"networking": {"type": "limited"},
},
)Schritt 3: Die Session erstellen
Dann erstellen wir eine Session mit unserem Agent und unserer Environment, plus einem optionalen Titel. Die Session ist die Arbeitseinheit:
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Count lines demo",
)Schritt 4: Den Stream öffnen, dann den Kickoff senden
Jetzt öffnen wir den Event-Stream — und beachte, dass wir das zuerst tun. Der Stream liefert nur Events, die auftreten, nachdem er geöffnet wurde, also öffne ihn immer, bevor du die Kickoff-Nachricht sendest. Dann senden wir die Benutzernachricht in den Live-Stream:
with client.beta.sessions.events.stream(session_id=session.id) as stream:
# Stream ist offen – jetzt den Kickoff senden
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.",
}
],
}
],
)Beachte, dass es events heißt — im Plural. Events sind die Art und Weise, wie in dieser API alles fließt.
Schritt 5: Den Stream konsumieren
Schließlich konsumieren wir den Stream, immer noch innerhalb des with-Blocks aus Schritt 4. Es gibt drei Event-Typen, die für diese Demo wichtig sind:
agent.message— Claudes Textagent.tool_use— welches Tool Claude gewählt hatsession.status_idle— der Agent hat angehalten und wartet auf Eingabe
Diese Demo stoppt beim ersten Idle-Event. In deiner eigenen App prüfe event.stop_reason.type, bevor du die Arbeit als erledigt betrachtest: end_turn bedeutet, dass der Agent seinen Zug beendet hat oder du ihn unterbrochen hast, und requires_action bedeutet, dass ein Tool-Aufruf eine Antwort von dir benötigt.
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 ---")
breakFühre es aus, und die Ausgabe ist der Agent, der laut nachdenkt — tatsächlicher Text, die Tools, die er wählt, und eine abschließende Antwort. Alles läuft innerhalb von Anthropics Container, nicht deinem:

Der Tausch
Normalerweise haben wir bei Agents unsere eigene Schleife, in der wir alles selbst steuern müssen. Mit Managed Agents delegierst du diese Schleife, die Sandbox und die Fortsetzbarkeit — und konsumierst einfach den Event-Stream, während er eintrifft. Der Event-Verlauf der Session wird auf dem Server gespeichert. Wenn deine Verbindung also abbricht, öffne einen neuen Stream, liste die vergangenen Events auf, um zu sehen, was du verpasst hast, und überspringe jedes Live-Event, das die Liste bereits zurückgegeben hat. Den Code dazu findest du unter Erneut verbinden, ohne Events zu verpassen(öffnet in neuem Tab).
In einer Produktions-App ist das die passende Form für lang laufende, dateiintensive „Organisiere das für mich"-Aufgaben. Stell dir eine Fileshare-Bereinigung vor: Ein Managed Agent liest eine Zielverzeichnisstruktur-Spezifikation, durchläuft den unaufgeräumten Eingangsordner, verschiebt Dateien in die richtigen Projektordner, archiviert Duplikate und Null-Byte-Müll und markiert alles, was er nicht sicher zuordnen kann — alles in einer Session, die gegen Tausende von Dateien minutenlang laufen kann. So sieht das in einer echten App aus — ein Fileshare-Bereinigungs-Dashboard, das die Aktivität des Agents live streamt, während er Dateien sortiert, archiviert und markiert:

Zusammenfassung
- Managed Agents sind die Agent-Loop, die für dich ausgeführt wird — auf Anthropics Infrastruktur statt auf deinem Server.
- Der Ablauf ist: einen Agent erstellen, eine Environment erstellen, eine Session erstellen, Events hineinsenden und Events herausstreamen.
- Der Agent (Modell, System-Prompt, Toolset) ist über Durchläufe hinweg wiederverwendbar; die Session ist ein einzelner Durchlauf; Events sind die Art, wie alles fließt.
- Öffne den Event-Stream bevor du deine Kickoff-Nachricht sendest — er liefert nur Events, die auftreten, nachdem er geöffnet wurde.
- Achte auf drei Events:
agent.message(Text),agent.tool_use(Tool-Auswahl) undsession.status_idle(angehalten und wartet auf Eingabe, wobeistop_reason.typeden Grund angibt). - Greife zu Managed Agents, wenn die Schleife zu lange laufen würde, zu viel tun müsste oder einen Aussetzer überstehen muss. Greife zu einer manuellen Schleife, wenn du volle Kontrolle willst.