Deinen ersten verwalteten Agenten erstellen

Was ist ein verwalteter Agent?

Ein verwalteter Agent ist eine Agent-Loop, die auf Anthropics Infrastruktur läuft statt auf deiner eigenen. Du beschreibst den Agenten 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 arbeitet.

Verwaltete Agenten sind standardmäßig für jedes API-Konto aktiviert — kein besonderer Zugang nötig.

Die vier Primitiven

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

1. Agent — die Persona: Modell, System-Prompt und Toolset. Das ist über viele Durchläufe hinweg wiederverwendbar.
2. Environment — wo der Agent läuft: Cloud oder selbst gehostet, Netzwerkkonfiguration und so weiter.
3. Session — ein einzelner Durchlauf eines Agenten innerhalb einer bestimmten Umgebung. Die Session ist die Arbeitseinheit.
4. Events — die Nachrichten, die hinein- und herausfließen: die Aktionen des Agenten, die Tool-Aufrufe, die Ergebnisse, die Antworten.

So greifen die Teile ineinander: Deine App spricht mit einer Session, die Session treibt die Arbeit innerhalb der Umgebung voran, 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 verwaltete Agent

Lass uns den kleinsten verwalteten Agenten bauen, der etwas Nützliches tut: eine Datei auf dem 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 Agenten erstellen

Zuerst erstellen wir den Agenten. 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-Netzwerk. 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 erhält 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 Agenten 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 laufenden 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 — Plural. Events sind die Art, wie in dieser API alles 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 ausgewählt hat
• session.status_idle — der Agent hat angehalten und wartet auf Eingabe

Diese Demo stoppt beim ersten Idle-Event. In deiner eigenen App solltest du event.stop_reason.type prüfen, bevor du die Arbeit als abgeschlossen 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 ---")
            break

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



Der Tausch

Normalerweise haben wir bei Agenten unsere eigene Schleife, bei der wir alles kontrollieren müssen. Mit verwalteten Agenten delegierst du diese Schleife, die Sandbox und die Wiederaufnahmefähigkeit — und konsumierst einfach den Event-Stream, während er eintrifft. Die Event-Historie der Session wird auf dem Server gespeichert. Wenn also deine Verbindung 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. Siehe Ohne verpasste Events wieder verbinden für den Code.

In einer Produktions-App ist das die richtige Herangehensweise für lang laufende, dateibezogene „organisiere das für mich"-Aufgaben. Stell dir eine Dateifreigabe-Bereinigung vor: Ein verwalteter Agent liest eine Zielverzeichnisstruktur-Spezifikation, durchläuft den unordentlichen 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 Minuten lang gegen Tausende von Dateien laufen kann. So sieht das in einer echten App aus — ein Dashboard zur Dateifreigabe-Bereinigung, das die Aktivität des Agenten live streamt, während er Dateien sortiert, archiviert und markiert:



Zusammenfassung

• Verwaltete Agenten sind die Agent-Loop, für dich ausgeführt — auf Anthropics Infrastruktur statt auf deinem Server.
• Der Ablauf ist: einen Agenten 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) und session.status_idle (angehalten und wartend auf Eingabe, mit stop_reason.type, das den Grund angibt).
• Greife zu verwalteten Agenten, 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.