So funktioniert die Agent-Schleife

​

Die Schleife auf einen Blick

1. Prompt empfangen. Claude empfängt Ihren Prompt zusammen mit dem System-Prompt, Werkzeugdefinitionen und Gesprächsverlauf. Das SDK gibt eine SystemMessage mit dem Subtyp "init" aus, die Sitzungsmetadaten enthält.
2. Bewerten und antworten. Claude bewertet den aktuellen Status und bestimmt, wie vorzugehen ist. Es kann mit Text antworten, einen oder mehrere Werkzeugaufrufe anfordern oder beides. Das SDK gibt eine AssistantMessage aus, die den Text und alle Werkzeugaufrufe enthält.
3. Werkzeuge ausführen. Das SDK führt jedes angeforderte Werkzeug aus und sammelt die Ergebnisse. Jeder Satz von Werkzeugergebnissen wird an Claude für die nächste Entscheidung zurückgesendet. Sie können Hooks verwenden, um Werkzeugaufrufe vor ihrer Ausführung abzufangen, zu ändern oder zu blockieren.
4. Wiederholen. Die Schritte 2 und 3 wiederholen sich als Zyklus. Jeder vollständige Zyklus ist eine Runde. Claude ruft weiterhin Werkzeuge auf und verarbeitet Ergebnisse, bis es eine Antwort ohne Werkzeugaufrufe erzeugt.
5. Ergebnis zurückgeben. Das SDK gibt eine endgültige AssistantMessage mit der Textantwort (keine Werkzeugaufrufe) aus, gefolgt von einer ResultMessage mit dem endgültigen Text, Token-Nutzung, Kosten und Sitzungs-ID.

​

Runden und Nachrichten

1. Runde 1: Claude ruft Bash auf, um npm test auszuführen. Das SDK gibt eine AssistantMessage mit dem Werkzeugaufruf aus, führt den Befehl aus und gibt dann eine UserMessage mit der Ausgabe (drei Fehler) aus.
2. Runde 2: Claude ruft Read auf auth.ts und auth.test.ts auf. Das SDK gibt die Dateiinhalte zurück und gibt eine AssistantMessage aus.
3. Runde 3: Claude ruft Edit auf, um auth.ts zu beheben, und ruft dann Bash auf, um npm test erneut auszuführen. Alle drei Tests bestehen. Das SDK gibt eine AssistantMessage aus.
4. Letzte Runde: Claude erzeugt eine nur-Text-Antwort ohne Werkzeugaufrufe: „Behobener Auth-Bug, alle drei Tests bestehen jetzt.” Das SDK gibt eine endgültige AssistantMessage mit diesem Text aus, gefolgt von einer ResultMessage mit dem gleichen Text plus Kosten und Nutzung.

​

Nachrichtentypen

• SystemMessage: Sitzungslebenszyklus-Ereignisse. Das Feld subtype unterscheidet sie: "init" ist die erste Nachricht (Sitzungsmetadaten), und "compact_boundary" wird nach Komprimierung ausgelöst. In TypeScript ist die Komprimierungsgrenze ihr eigener SDKCompactBoundaryMessage-Typ statt eines Subtyps von SDKSystemMessage.
• AssistantMessage: wird nach jeder Claude-Antwort ausgegeben, einschließlich der endgültigen nur-Text-Antwort. Enthält Textinhaltsblöcke und Werkzeugaufrufsblöcke aus dieser Runde.
• UserMessage: wird nach jeder Werkzeugausführung mit dem Werkzeugergebnis-Inhalt ausgegeben, der an Claude zurückgesendet wird. Wird auch für alle Benutzereingaben ausgegeben, die Sie mid-loop streamen.
• StreamEvent: wird nur ausgegeben, wenn Teilteilnachrichten aktiviert sind. Enthält rohe API-Streaming-Ereignisse (Text-Deltas, Werkzeug-Input-Chunks). Siehe Stream-Antworten.
• ResultMessage: markiert das Ende der Agent-Schleife. Enthält das endgültige Textergebnis, Token-Nutzung, Kosten und Sitzungs-ID. Überprüfen Sie das Feld subtype, um zu bestimmen, ob die Aufgabe erfolgreich war oder ein Limit erreicht hat. Eine kleine Anzahl von nachfolgenden Systemevenementen, wie prompt_suggestion, können danach ankommen, daher sollten Sie den Stream bis zum Ende durchlaufen, anstatt beim Ergebnis zu unterbrechen. Siehe Ergebnis verarbeiten.

​

Nachrichten verarbeiten

• Nur endgültige Ergebnisse: verarbeiten Sie ResultMessage, um die Ausgabe, Kosten und ob die Aufgabe erfolgreich war oder ein Limit erreicht hat, zu erhalten.
• Fortschritts-Updates: verarbeiten Sie AssistantMessage, um zu sehen, was Claude jede Runde tut, einschließlich welche Werkzeuge es aufgerufen hat.
• Live-Streaming: aktivieren Sie Teilteilnachrichten (include_partial_messages in Python, includePartialMessages in TypeScript), um StreamEvent-Nachrichten in Echtzeit zu erhalten. Siehe Stream-Antworten in Echtzeit.

• Python: überprüfen Sie Nachrichtentypen mit isinstance() gegen Klassen, die aus claude_agent_sdk importiert wurden (zum Beispiel, isinstance(message, ResultMessage)).
• TypeScript: überprüfen Sie das Feld type string (zum Beispiel, message.type === "result"). AssistantMessage und UserMessage umhüllen die rohe API-Nachricht in einem .message-Feld, daher befinden sich Inhaltsblöcke bei message.message.content, nicht bei message.content.

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

Werkzeugausführung

​

Integrierte Werkzeuge

• Externe Dienste verbinden mit MCP-Servern (Datenbanken, Browser, APIs)
• Benutzerdefinierte Werkzeuge definieren mit benutzerdefinierten Werkzeug-Handlern
• Projekt-Fähigkeiten laden über Einstellungsquellen für wiederverwendbare Workflows

​

Werkzeugberechtigungen

• allowed_tools / allowedTools genehmigt automatisch aufgelistete Werkzeuge. Ein schreibgeschützter Agent mit ["Read", "Glob", "Grep"] in seiner Werkzeugliste für zulässige Werkzeuge führt diese Werkzeuge ohne Aufforderung aus. Werkzeuge, die nicht aufgelistet sind, sind immer noch verfügbar, erfordern aber Berechtigung.
• disallowed_tools / disallowedTools blockiert aufgelistete Werkzeuge, unabhängig von anderen Einstellungen. Siehe Berechtigungen für die Reihenfolge, in der Regeln überprüft werden, bevor ein Werkzeug ausgeführt wird.
• permission_mode / permissionMode kontrolliert, was mit Werkzeugen passiert, die nicht durch Zulassungs- oder Ablehnungsregeln abgedeckt sind. Siehe Berechtigungsmodus für verfügbare Modi.

​

Parallele Werkzeugausführung

​

Kontrollieren Sie, wie die Schleife läuft

​

Runden und Budget

​

Anstrengungsgrad

​

Berechtigungsmodus

​

Modell

​

Das Kontextfenster

​

Was Kontext verbraucht

​

Automatische Komprimierung

• Zusammenfassungsanweisungen in CLAUDE.md: Der Kompressor liest Ihre CLAUDE.md wie jeden anderen Kontext, daher können Sie einen Abschnitt einschließen, der ihm sagt, was beim Zusammenfassen zu bewahren ist. Der Abschnittskopf ist frei (nicht eine magische Zeichenkette); der Kompressor passt auf Absicht an.
• PreCompact-Hook: Führen Sie benutzerdefinierte Logik vor der Komprimierung aus, zum Beispiel um das vollständige Transkript zu archivieren. Der Hook erhält ein trigger-Feld (manual oder auto). Siehe Hooks.
• Manuelle Komprimierung: Senden Sie /compact als Prompt-String, um Komprimierung bei Bedarf auszulösen. Befehle, die auf diese Weise gesendet werden, sind SDK-Eingaben, keine nur-CLI-Verknüpfungen. Siehe Befehle im SDK.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

​

Kontext effizient halten

• Verwenden Sie Subagenten für Unteraufgaben. Jeder Subagent startet mit einem frischen Gespräch (kein vorheriger Nachrichtenverlauf, obwohl er seinen eigenen System-Prompt und Projekt-Kontext wie CLAUDE.md lädt). Er sieht nicht die Runden des Elternteils, und nur seine endgültige Antwort kehrt zum Elternteil als Werkzeugergebnis zurück. Der Kontext des Hauptagenten wächst um diese Zusammenfassung, nicht um das vollständige Unteraufgaben-Transkript. Siehe Was Subagenten erben für Details.
• Seien Sie selektiv mit Werkzeugen. Jede Werkzeugdefinition nimmt Kontextraum ein. Verwenden Sie das Feld tools auf AgentDefinition, um Subagenten auf die minimale Menge zu beschränken, die sie benötigen.
• Beobachten Sie MCP-Server-Kosten. MCP-Werkzeugsuche schiebt MCP-Werkzeugschemas standardmäßig auf und lädt sie bei Bedarf. Wenn die Werkzeugsuche ausgeschaltet ist, auf Vertex AI oder hinter einer Nicht-First-Party-ANTHROPIC_BASE_URL, fügt jeder MCP-Server alle seine Werkzeugschemas zu jeder Anfrage hinzu, daher können ein paar Server mit vielen Werkzeugen erheblichen Kontext verbrauchen, bevor der Agent irgendwelche Arbeiten verrichtet.
• Verwenden Sie niedrigere Anstrengung für Routine-Aufgaben. Setzen Sie Anstrengung auf "low" für Agenten, die nur Dateien lesen oder Verzeichnisse auflisten müssen. Dies reduziert Token-Nutzung und Kosten.

​

Sitzungen und Kontinuität

​

Ergebnis verarbeiten

​

Hooks

​

Alles zusammenbringen

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    async for message in query(
        prompt="Find and fix the bug causing test failures in the auth module",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read",
                "Edit",
                "Bash",
                "Glob",
                "Grep",
            ],  # Listing tools here auto-approves them (no prompting)
            setting_sources=[
                "project"
            ],  # Load CLAUDE.md, skills, hooks from current directory
            max_turns=30,  # Prevent runaway sessions
            effort="high",  # Thorough reasoning for complex debugging
        ),
    ):
        # Handle the final result
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # Save for potential resumption

            if message.subtype == "success":
                print(f"Done: {message.result}")
            elif message.subtype == "error_max_turns":
                # Agent ran out of turns. Resume with a higher limit.
                print(f"Hit turn limit. Resume session {session_id} to continue.")
            elif message.subtype == "error_max_budget_usd":
                print("Hit budget limit.")
            else:
                print(f"Stopped: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")


asyncio.run(run_agent())

​

Nächste Schritte

• Haben Sie noch keinen Agent ausgeführt? Beginnen Sie mit dem Schnellstart, um das SDK installiert zu bekommen und ein vollständiges Beispiel von Anfang bis Ende laufen zu sehen.
• Bereit, in Ihr Projekt zu integrieren? Laden Sie CLAUDE.md, Fähigkeiten und Dateisystem-Hooks, damit der Agent automatisch Ihren Projektkonventionen folgt.
• Erstellen Sie eine interaktive Benutzeroberfläche? Aktivieren Sie Streaming, um Live-Text und Werkzeugaufrufe anzuzeigen, während die Schleife läuft.
• Benötigen Sie strengere Kontrolle über das, was der Agent tun kann? Sperren Sie den Werkzeugzugriff mit Berechtigungen und verwenden Sie Hooks, um Werkzeugaufrufe vor ihrer Ausführung zu prüfen, zu blockieren oder zu transformieren.
• Führen Sie lange oder teure Aufgaben aus? Lagern Sie isolierte Arbeiten auf Subagenten aus, um Ihren Hauptkontext schlank zu halten.