Managed Agents: der Einstieg

TL;DR

Der Ablauf ist zweistufig und in dieser Reihenfolge zwingend: Agent einmal anlegen, Sitzung bei jedem Lauf. model, system und tools gehören auf den Agenten, nie auf die Sitzung. Und die Abbruchbedingung der Ereignisschleife schreiben fast alle falsch.

Die drei Objekte

Der Container, in dem die Werkzeuge laufen, wird je Sitzung bereitgestellt. Die Agentenschleife selbst läuft auf Anthropics Orchestrierungsebene und wirkt über Werkzeugaufrufe auf den Container.

Der Aufbau

import anthropic
client = anthropic.Anthropic()

# EINMALIG — Umgebung
umgebung = client.beta.environments.create(
    name="entwicklung",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

# EINMALIG — Agent. ID speichern!
agent = client.beta.agents.create(
    name="Code-Review-Agent",
    model="claude-opus-5",
    system="Du prüfst Quellcode auf Fehler und meldest Fundstellen knapp.",
    tools=[{"type": "agent_toolset_20260401"}],
)
print(agent.id)     # agent_... — in die Konfiguration, nicht in den Code

# BEI JEDEM LAUF — Sitzung
session = client.beta.sessions.create(
    agent=agent.id,                     # oder {"type": "agent", "id": ..., "version": ...}
    environment_id=umgebung.id,
    title="Review Modul Abrechnung",
)
print(f"https://platform.claude.com/workspaces/default/sessions/{session.id}")

Die letzte Zeile lohnt sich beim Entwickeln: Der Link zeigt die Sitzung live in der Konsole, mit allen Werkzeugaufrufen. Ersetzen Sie default durch Ihre Arbeitsbereichs-Kennung, wenn der Schlüssel nicht zum Standard-Arbeitsbereich gehört.

Fehler 1: den Agenten bei jedem Lauf anlegen

Das häufigste Muster in erstem Code — und es ist falsch:

def vorgang_bearbeiten(aufgabe):             # FALSCH
    agent = client.beta.agents.create(...)   # bei jedem Aufruf!
    session = client.beta.sessions.create(agent=agent.id, ...)

Der Agent ist eine dauerhafte, versionierte Ressource. Jeder Aufruf von agents.create() erzeugt ein neues Objekt. Nach einem Monat im Produktivbetrieb haben Sie tausende verwaiste Agenten, zahlen bei jedem Vorgang die Anlegelatenz, und die Versionierung — der eigentliche Zweck des getrennten Objekts — ist wertlos.

Richtig: Agent im Einrichtungsskript anlegen, ID in Konfiguration oder Umgebungsvariable ablegen, im Anfragepfad nur noch sessions.create() aufrufen.

Noch besser: Definieren Sie Agent und Umgebung als versionierte YAML-Dateien und wenden Sie sie über die Kommandozeile an. Dann liegt die Konfiguration im Repository und nicht in einem Skript:

# code-review.agent.yaml
name: Code-Review-Agent
model: claude-opus-5
system: |
  Du prüfst Quellcode auf Fehler und meldest Fundstellen knapp.
tools:
  - type: agent_toolset_20260401

AGENT_ID=$(ant beta:agents create < code-review.agent.yaml --transform id -r)
# Später aktualisieren:
ant beta:agents update --agent-id "$AGENT_ID" --version 1 < code-review.agent.yaml

Fehler 2: Konfiguration an die Sitzung hängen

session = client.beta.sessions.create(     # FALSCH
    agent=agent.id,
    model="claude-opus-5",                 # gehört auf den Agenten
    system="...",                          # gehört auf den Agenten
    tools=[...],                           # gehört auf den Agenten
)

Die Sitzung nimmt nur einen Verweis. Wenn Sie für einen einzelnen Lauf etwas überschreiben wollen, gibt es dafür eine eigene Form:

session = client.beta.sessions.create(
    agent={"type": "agent_with_overrides", "id": agent.id,
           "model": "claude-sonnet-5"},     # nur für diese Sitzung
    environment_id=umgebung.id,
)

Überschreibungen ersetzen das jeweilige Feld als Ganzes, sie mischen nicht — eine Werkzeugüberschreibung muss alle Werkzeuge auflisten, die die Sitzung haben soll.

Fehler 3: die Abbruchbedingung

Die Ereignisschleife, die fast jeder zuerst schreibt:

for event in stream:                       # FALSCH
    if event.type == "session.status_idle":
        break

Eine Sitzung geht vorübergehend in den Leerlauf — zwischen parallelen Werkzeugausführungen, während sie auf eine Freigabe wartet, oder während sie ein Ergebnis von Ihnen erwartet. Wer beim ersten Leerlauf abbricht, verpasst den Rest.

Richtig ist die Prüfung des Abbruchgrunds:

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": "Prüfe das Modul."}]}],
    )

    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_terminated":
            break

        elif event.type == "session.status_idle":
            if event.stop_reason.type == "requires_action":
                continue          # wartet auf Sie — behandeln, nicht abbrechen
            break                 # end_turn oder retries_exhausted — beides final

Fehler 4: senden, bevor der Strom offen ist

Der Ereignisstrom liefert nur, was nach dem Öffnen passiert — er spielt nichts nach. Wer erst die Nachricht sendet und dann den Strom öffnet, bekommt die frühen Ereignisse gebündelt nachgereicht und kann nicht darauf reagieren.

Deshalb im Beispiel oben: erst stream öffnen, dann innerhalb des Kontexts senden.

Und für den Fall, dass die Verbindung abreißt: Beim Wiederverbinden zuerst die Ereignisliste abrufen, nach Ereignis-ID entdoppeln und dann den Strom weiterlesen. Ohne das verlieren Sie alles, was während der Unterbrechung passiert ist — und wenn dabei ein Werkzeugaufruf offen war, steht die Sitzung.

Was Sie danach brauchen

Zugangsdaten gehören in einen Tresor, nie in den Systemprompt — siehe Tresor-Zugangsdaten.

Bei strenger Datenlage verschieben Sie die Werkzeugausführung in die eigene Infrastruktur — siehe selbst betriebene Sandbox.

Wichtig für die Plattformwahl: Managed Agents steht auf der Anthropic-API und Claude Platform on AWS zur Verfügung, nicht auf Amazon Bedrock, Vertex AI oder Microsoft Foundry.

Häufig gestellte Fragen

Muss ich für jeden Vorgang einen neuen Agenten anlegen?

Nein, und das ist der häufigste Fehler. Der Agent ist eine dauerhafte, versionierte Ressource: einmal anlegen, ID speichern, bei jedem Lauf per Verweis wiederverwenden. Wer agents.create() in den Anfragepfad legt, erzeugt verwaiste Objekte, zahlt unnötige Latenz und verliert die Versionierung.

Wohin gehören Modell, Systemanweisung und Werkzeuge?

Auf den Agenten, nicht auf die Sitzung. Die Sitzung nimmt nur einen Verweis auf Agent und Umgebung. Für einmalige Abweichungen gibt es die Form agent_with_overrides — die ersetzt die jeweiligen Felder allerdings als Ganzes, sie mischt nicht.

Warum bricht meine Ereignisschleife zu früh ab?

Weil sie auf session.status_idle allein abbricht. Eine Sitzung geht vorübergehend in den Leerlauf — zwischen Werkzeugausführungen oder während sie auf eine Freigabe oder ein Werkzeugergebnis wartet. Prüfen Sie zusätzlich stop_reason: Bei requires_action weiterlaufen, bei allem anderen abbrechen.

Warum verpasse ich die ersten Ereignisse?

Weil der Strom erst nach dem Senden geöffnet wurde. Der Ereignisstrom liefert ausschließlich, was nach dem Öffnen passiert, und spielt nichts nach. Öffnen Sie ihn deshalb vor dem Senden der ersten Nachricht.

Was passiert bei einem Verbindungsabbruch?

Ereignisse, die während der Unterbrechung entstanden sind, gehen für den Strom verloren — es gibt keine Wiederholung. Rufen Sie beim Wiederverbinden zuerst die Ereignisliste ab, entdoppeln Sie nach Ereignis-ID und lesen Sie dann weiter. Ohne das steht die Sitzung, wenn während des Abbruchs ein Werkzeugaufruf offen war.

Der nächste Schritt

Legen Sie Agent und Umgebung als YAML-Dateien im Repository an und wenden Sie sie über die Kommandozeile an. Damit ist die Konfiguration versioniert, überprüfbar und aus dem Anfragepfad heraus — und der häufigste Fehler ist strukturell ausgeschlossen. Beim Aufbau unterstützen wir gern.