Wird geladen

Deinen ersten Managed Agent erstellen

Lektion 128 Min.
Wird geladen

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:

  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 Agents innerhalb einer bestimmten Environment. Die Session ist die Arbeitseinheit.
  4. 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:

Architekturdiagramm, das einen Agent zeigt, der mit einer Session verbunden ist, die eine Environment antreibt, wobei die Ergebnisse über einen Event-Stream zurück zu deiner App fließen

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:

python
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:

python
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:

python
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:

python
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 Text
  • agent.tool_use — welches Tool Claude gewählt hat
  • session.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.

python
    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 abschließende Antwort. Alles läuft innerhalb von Anthropics Container, nicht deinem:

Terminalausgabe des Managed-Agent-Laufs: Agent-, Environment- und Session-IDs werden erstellt, dann zeigt der Event-Stream, wie der Agent die Datei schreibt, seine Tools ausführt und meldet, dass die Datei 3 Zeilen enthält

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.

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:

Eine Fileshare-Bereinigungs-Webanwendung, die von einem Managed Agent angetrieben wird und den Ordnerbaum zeigt, der organisiert wird, zusammen mit einem Live-Aktivitätsfeed der Events des Agents, während er Dateien verschiebt und archiviert

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) und session.status_idle (angehalten und wartet auf Eingabe, wobei stop_reason.type den 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.