Was ist ein verwalteter Agent?

Wenn du eine Agent-Schleife von Hand gebaut hast, kennst du das Prozedere: While-Schleifen, Stop-Reason-Switches, Tool-Ausführungen. Das funktioniert, und für viele Features ist es tatsächlich die richtige Struktur. Aber manchmal wird diese Schleife sehr lange laufen — Minuten, vielleicht sogar Stunden — über viele Tools hinweg, mit Zustand zum Verwalten, Dateien zum Schreiben und Arbeit zum Fortsetzen nach einer Netzwerkunterbrechung. An diesem Punkt möchtest du die Schleife nicht auf deinem Server ausführen. Du möchtest sie delegieren. Das ist, wofür es verwaltete Agenten gibt.

Ein verwalteter Agent ist eine Agent-Schleife, die auf der Infrastruktur von Anthropic läuft, nicht auf deiner. Du beschreibst den Agent einmal, gibst ihm eine Umgebung zum Arbeiten und startest eine Session. Anthropic führt die Schleife aus, und du streamst einfach die Events zurück, während er arbeitet.

Verwaltete Agenten sind standardmäßig für jeden API-Account aktiviert — kein spezieller Zugriff erforderlich.

Die vier Primitiven

Es gibt vier Primitive, und sie kommen in dieser Reihenfolge:

Agent — die Persona: Modell, System-Prompt und Toolset. Dies ist über viele Läufe hinweg wiederverwendbar.
Environment — wo der Agent läuft: Cloud oder lokal, Netzwerkkonfiguration usw.
Session — ein einzelner Lauf eines Agenten in einer bestimmten Umgebung. Die Session ist die Arbeitseinheit.
Events — die Nachrichten, die ein- und ausgehen: die Aktionen des Agenten, die Tool-Aufrufe, die Ergebnisse, die Antworten.

So passen die Teile zusammen: Deine App spricht mit einer Session, die Session treibt Arbeit in der Umgebung an, und alles, was passiert, fließt über den Event-Stream zurück zu deiner App:

Architektur-Diagramm, das einen Agent zeigt, der mit einer Session verbunden ist, die eine Umgebung antreibt, mit Ergebnissen, die über einen Event-Stream zu deiner App zurückfließen

Beachte die Verschiebung hier: Du führst keine While-Schleife aus. Du sendest Events und liest Events.

Der kleinste mögliche verwaltete Agent

Lass uns den kleinsten verwalteten Agent bauen, der etwas Nützliches tut: eine Datei im Temp-Laufwerk erstellen, ihre Zeilen zählen und zurückberichten.

Für Tools verwenden wir das Agent-Toolset — Anthropics gebündeltes Datei-, Bash- und Web-Tool-Set. Sie funktionieren gut für diese Aufgabe, daher müssen wir keine Tools selbst definieren.

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-4-8", system="You are a helpful agent that completes small file tasks. ", tools=[ {"type": "agent_toolset_20260401", "default_config": {"enabled": True}} ], )

Denk dran: Der Agent ist wiederverwendbar. Erstelle ihn einmal und führe ihn über viele Sessions aus.

Schritt 2: Die Umgebung erstellen

Danach die Umgebung. Dies startet die Container-Vorlage — Cloud, mit uneingeschränktem Netzwerk. Dies ist die Sandbox, in der die Datei tatsächlich geschrieben wird:

environment = client. beta. environments. create( name="line-counter-env", config={ "type": "cloud", "networking": {"type": "unrestricted"}, }, )

Schritt 3: Die Session erstellen

Dann erstellen wir eine Session mit unserem Agent und unserer Umgebung, 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 die Kickoff-Nachricht senden

Jetzt öffnen wir den Event-Stream — und beachte, dass wir das zuerst tun. Der Stream liefert nur Events, die nach dem Öffnen auftreten, 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:

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 ist — Plural. Events sind, wie alles in dieser API fließt.

Schritt 5: Den Stream konsumieren

Schließlich konsumieren wir den Stream. Es gibt drei Event-Typen, die für diese Demo wichtig sind:

agent. message — Claudes Text
agent. tool_use — welches Tool Claude gewählt hat
session. status_idle — der Agent ist fertig

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

Führe es aus, und die Ausgabe ist der Agent, der laut nachdenkt — tatsächlicher Text, die Tools, die er wählt, und eine endgültige Antwort. Alles läuft in Anthropics Container, nicht in deinem:

Terminal-Ausgabe des verwalteten Agent-Laufs: Agent-, Umgebungs- und Session-IDs werden erstellt, dann zeigt der Event-Stream den Agent, der die Datei schreibt, seine Tools ausführt und meldet, dass die Datei 3 Zeilen enthält

Der Kompromiss

Normalerweise haben wir bei Agenten unsere eigene Schleife, in der wir alles kontrollieren müssen. Bei verwalteten Agenten delegierst du diese Schleife, die Sandbox und die Wiederaufnahmebarkeit — und konsumierst einfach den Event-Stream, wie er kommt.

In einer Produktions-App ist dies die Form für lange laufende, datei-berührende, „organisiere das für mich"-Aufgaben. Stell dir eine Dateifreigabe-Bereinigung vor: Ein verwalteter Agent liest eine Zielverzeichnisstruktur-Spezifikation, durchläuft den unordentlichen eingehenden Ordner, verschiebt Dateien in die richtigen Projektordner, archiviert Duplikate und Müll mit Null-Bytes und kennzeichnet alles, das er nicht sicher platzieren kann — alles in einer Session, die Minuten lang gegen Tausende von Dateien laufen kann. So sieht das in einer echten App aus — ein Dateifreigabe-Bereinigungs-Dashboard, das die Agent-Aktivität live streamt, während es Dateien sortiert, archiviert und kennzeichnet:

Eine Dateifreigabe-Bereinigungs-Web-App, die von einem verwalteten Agent angetrieben wird und die organisierte Ordnerstruktur neben einem Live-Aktivitäts-Feed der Agent-Events zeigt, während er Dateien verschiebt und archiviert

Zusammenfassung

Verwaltete Agenten sind die Agent-Schleife, die für dich läuft — auf Anthropics Infrastruktur statt auf deinem Server.
Der Ablauf ist: Erstelle einen Agent, erstelle eine Umgebung, erstelle eine Session, sende Events rein und streame Events raus.
Der Agent (Modell, System-Prompt, Toolset) ist über Läufe hinweg wiederverwendbar; die Session ist ein einzelner Lauf; Events sind, wie alles fließt.
Öffne den Event-Stream vor dem Senden deiner Kickoff-Nachricht — er liefert nur Events, die nach dem Öffnen auftreten.
Achte auf drei Events: agent. message (Text), agent. tool_use (Tool-Wahlen) und session. status_idle (fertig).
Greifen Sie zu verwalteten Agenten, wenn die Schleife zu lange laufen würde, zu viel tun würde oder eine Unterbrechung überstehen müsste. Greifen Sie zu einer manuellen Schleife, wenn Sie volle Kontrolle möchten.