Vier Wege, einen Claude-Agenten zu bauen

TL;DR

Tool Runner, Claude Agent SDK und Managed Agents klingen austauschbar und sind es nicht. Zwei Fragen trennen sie sauber: Wer liefert die Agentenschleife, und wer liefert den Betrieb? Nur einer der vier Wege liefert beides.

Die zwei Fragen

Ein Agent braucht zweierlei. Erstens eine Schleife — die Mechanik, die das Modell aufruft, Werkzeugaufrufe erkennt, sie ausführt, das Ergebnis zurückgibt und wiederholt, bis das Modell fertig ist. Zweitens einen Ort, an dem die Werkzeuge tatsächlich laufen: Dateizugriffe, Shell-Befehle, Code-Ausführung.

Die vier Wege unterscheiden sich genau darin:

Die häufigste Verwechslung: Tool Runner und Claude Agent SDK liefern nur die Schleife — den Betrieb stellen Sie in beiden Fällen selbst. Nur Managed Agents nimmt Ihnen beides ab.

Weg 1: die eigene Schleife

Sie schreiben die Schleife von Hand:

messages = [{"role": "user", "content": eingabe}]

while True:
    response = client.messages.create(
        model="claude-opus-5", max_tokens=16000,
        tools=werkzeuge, messages=messages,
    )
    if response.stop_reason == "end_turn":
        break

    messages.append({"role": "assistant", "content": response.content})

    ergebnisse = []
    for block in response.content:
        if block.type == "tool_use":
            ergebnisse.append({
                "type": "tool_result",
                "tool_use_id": block.id,          # muss zur Anfrage passen
                "content": werkzeug_ausfuehren(block.name, block.input),
            })
    messages.append({"role": "user", "content": ergebnisse})

Wann sinnvoll: Wenn Sie die vollständige Kontrolle über den Ablauf brauchen — eigener Transport, Anfrageformen, die das SDK nicht baut, oder eine Ablauflogik, die zwischen den Runden unzusammenhängende Arbeit einschiebt. Und wenn Sie keine Beta-Abhängigkeit wollen.

Zwei Fallen, die hier regelmäßig auftreten: Hängen Sie immer den vollständigen response.content an, nicht nur den Text — sonst gehen die Werkzeugaufruf-Blöcke verloren und die nächste Runde ist ungültig. Und geben Sie alle Werkzeugergebnisse in einer Nutzernachricht zurück; wer sie auf mehrere Nachrichten aufteilt, gewöhnt dem Modell parallele Werkzeugaufrufe ab.

Weg 2: Tool Runner

Das SDK übernimmt die Schleife, Sie schreiben nur die Werkzeuge:

from anthropic import beta_tool

@beta_tool
def bestand_abfragen(artikelnummer: str, werk: str) -> str:
    """Gibt den verfügbaren Bestand eines Artikels in einem Werk zurück.

    Args:
        artikelnummer: Die Artikelnummer, etwa 4711.
        werk: Werkskennung, etwa "W2".
    """
    return erp.bestand(artikelnummer, werk)

runner = client.beta.messages.tool_runner(
    model="claude-opus-5", max_tokens=16000,
    tools=[bestand_abfragen],
    messages=[{"role": "user", "content": "Wie viele 4711 gibt es in Werk 2?"}],
)

for message in runner:
    print(message)

Das Schema wird aus der Signatur und dem Docstring erzeugt — Sie schreiben kein JSON-Schema.

Der verbreitete Irrtum: "Ich brauche eine eigene Schleife, weil ich Kontrolle brauche." In den meisten Fällen nicht. Jede Runde liefert die Antwort des Modells, bevor die Werkzeuge laufen, und Sie können eingreifen — Freigaben abfragen, Fehler abfangen, Ergebnisse verändern, Wiederholungen auslösen. Menschliche Freigabe verlangt ausdrücklich keine eigene Schleife.

Was der Runner nicht automatisch tut: Bei serverseitigen Werkzeugen kann eine Runde mit stop_reason: "pause_turn" enden. Der Runner setzt das nicht selbstständig fort — er beendet die Schleife und gibt die pausierte Runde als Endergebnis zurück, ohne Fehler und ohne Warnung. Das Ergebnis ist eine stillschweigend abgeschnittene Antwort. Wer serverseitige Werkzeuge nutzt, muss diesen Fall ausdrücklich behandeln.

Weg 3: Claude Agent SDK

Ein eigenes Paket, nicht Teil des API-SDK. Es ist im Kern Claude Code als Bibliothek: mit eingebauten Werkzeugen für Dateien lesen, schreiben, bearbeiten, Shell-Befehle, Suchen, Web-Zugriff, dazu Unteragenten, Berechtigungen und Sitzungsverwaltung.

Wann sinnvoll: Wenn Sie einen Coding- oder Dateisystem-Agenten wollen und die eingebauten Werkzeuge das abdecken, was er tun soll — auf Ihrer eigenen Infrastruktur.

Die Verwechslung, die es zu vermeiden gilt: Tool Runner und Agent SDK sind verschiedene Pakete. Der Tool Runner ist ein dünner Helfer über dem Nachrichten-Endpunkt und bringt keine eingebauten Werkzeuge mit — jedes Werkzeug definieren Sie selbst. Das Agent SDK bringt eine vollständige Werkzeugausstattung mit. Wer das eine erwartet und das andere einsetzt, wundert sich.

Weg 4: Managed Agents

Der einzige Weg, bei dem Anthropic beides übernimmt: die Schleife und den Ort, an dem die Werkzeuge laufen. Je Sitzung wird ein Container bereitgestellt — dort passieren Dateizugriffe, Shell-Befehle und Code-Ausführung.

Der Ablauf ist zweistufig und in dieser Reihenfolge zwingend:

# 1. Agent anlegen — EINMALIG, ID speichern
agent = client.beta.agents.create(
    name="Code-Prüfer",
    model="claude-opus-5",
    system="Du prüfst Quellcode auf Fehler.",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. Sitzung starten — bei jedem Lauf, mit der gespeicherten ID
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Der Fehler, den fast alle machen: agents.create() bei jedem Programmlauf aufzurufen. Der Agent ist eine dauerhafte, versionierte Ressource — einmal anlegen, ID ablegen, bei jedem Lauf wiederverwenden. Wer ihn pro Anfrage neu anlegt, sammelt verwaiste Objekte an und verliert die Versionierung, die der eigentliche Zweck des getrennten Objekts ist.

Zweiter Fehler: model, system und tools an die Sitzung zu hängen. Diese Felder gehören auf den Agenten. Die Sitzung bekommt nur einen Verweis.

Wichtig für die Plattformwahl: Managed Agents steht auf der Anthropic-API und Claude Platform on AWS zur Verfügung — nicht auf Amazon Bedrock, Google Vertex AI oder Microsoft Foundry. Wer aus Gründen der Datenresidenz einen dieser Wege wählt, kann Managed Agents nicht nutzen und braucht einen der ersten drei Wege.

Für Häuser, bei denen die Daten die eigene Infrastruktur nicht verlassen dürfen, gibt es einen Zwischenweg: die selbst betriebene Sandbox. Die Agentenschleife bleibt bei Anthropic, die Werkzeugausführung läuft bei Ihnen. Die Einrichtung steht im Beitrag zur selbst betriebenen Sandbox.

Die Entscheidung

• Werkzeuge, die Sie selbst definieren, ohne die Schleife zu schreiben → Tool Runner. Der Normalfall.
• Vollständige Kontrolle über den Ablauf oder keine Beta-Abhängigkeit → eigene Schleife.
• Coding- oder Dateisystem-Agent auf eigener Infrastruktur → Claude Agent SDK.
• Anthropic soll Schleife und Betrieb übernehmen, Konfigurationen versioniert, lange Sitzungen → Managed Agents.
• Datenresidenz über Bedrock oder Vertex nötig → Managed Agents fällt aus, einer der ersten drei.

Und die Frage davor, die man sich ehrlich stellen sollte: Brauchen Sie überhaupt einen Agenten? Für Klassifikation, Zusammenfassung, Extraktion und Frage-Antwort reicht ein einzelner Aufruf. Ein Agent lohnt sich, wenn die Aufgabe mehrstufig ist und sich nicht vollständig vorab beschreiben lässt.

Häufig gestellte Fragen

Was ist der Unterschied zwischen Tool Runner und Claude Agent SDK?

Der Tool Runner ist Teil des regulären API-SDK und automatisiert die Schleife über Werkzeuge, die Sie definieren — ohne eingebaute Werkzeuge. Das Claude Agent SDK ist ein eigenes Paket mit vollständiger Werkzeugausstattung für Dateien, Shell, Suche und Web. Beide laufen auf Ihrer Infrastruktur; nur der Umfang der mitgelieferten Ausstattung unterscheidet sich.

Wann brauche ich Managed Agents?

Wenn Anthropic sowohl die Agentenschleife als auch den Ausführungsort übernehmen soll — je Sitzung wird ein Container bereitgestellt, in dem Werkzeuge laufen. Sinnvoll bei langlaufenden Sitzungen, versionierten Agentenkonfigurationen und wenn Sie keine eigene Ausführungsumgebung betreiben wollen.

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

Nein, und das ist der häufigste Fehler. Der Agent ist eine dauerhafte, versionierte Ressource: einmal anlegen, die 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.

Brauche ich für menschliche Freigaben eine eigene Schleife?

Nein. Der Tool Runner liefert je Runde die Antwort des Modells, bevor die Werkzeuge ausgeführt werden — Sie können dort eingreifen, Freigaben abfragen und Aufrufe ablehnen. Alternativ setzen Sie die Prüfung in die Werkzeugfunktion selbst und geben ein Ergebnis "vom Nutzer abgelehnt" zurück.

Sind Managed Agents auf Amazon Bedrock verfügbar?

Nein. Managed Agents steht auf der Anthropic-API und auf Claude Platform on AWS zur Verfügung, nicht auf Amazon Bedrock, Google Vertex AI oder Microsoft Foundry. Wer aus Gründen der Datenresidenz einen dieser Cloud-Wege wählt, muss den Agenten über die eigene Schleife, den Tool Runner oder das Agent SDK bauen.

Der nächste Schritt

Beantworten Sie zuerst, ob die Aufgabe überhaupt einen Agenten braucht — mehrstufig und nicht vollständig vorab beschreibbar. Wenn ja, entscheidet die Frage nach dem Ausführungsort, nicht die nach dem Werkzeug. Beim Zuschnitt helfen wir gern.