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 ein oder mehrere AssistantMessage-Objekte aus, eines für jeden Inhaltsblock, wie einen Textblock oder eine Werkzeugaufrufsanforderung.
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 eine AssistantMessage für jeden Aufruf aus und gibt die Dateiinhalte zurück.
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 für jeden Aufruf 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": Sitzungsmetadaten für den Durchlauf. Wenn ein SessionStart- oder Setup-Hook während des Sitzungsstarts ausgeführt wird, kommen seine Hook-Lebenszyklus-Nachrichten vor der init-Nachricht an
  • "compact_boundary": wird nach Komprimierung ausgelöst
  • "informational": einfache Textstatusbanner aus der Schleife
  • "worker_shutting_down": der Host wird beendet oder Remote Control wurde getrennt
  In TypeScript ist jeder Subtyp außer "init" sein eigener Typ in der SDKMessage-Union statt eines Subtyps von SDKSystemMessage.
• AssistantMessage: wird für jeden Inhaltsblock in Claudes Antworten ausgegeben, einschließlich des endgültigen nur-Text-Blocks. Jede trägt einen einzelnen Inhaltsblock, wie Text oder einen Werkzeugaufruf, und die Nachrichten aus einer Antwort teilen sich eine Nachrichten-ID.
• 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.

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                # Each AssistantMessage carries one content block
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Tool call: {block.name}")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      // Each assistant message carries one content block
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(`Claude: ${block.text}`);
        } else if (block.type === "tool_use") {
          console.log(`Tool call: ${block.name}`);
        }
      }
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

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 aufgelistete Tools automatisch. Ein nur lesender Agent mit ["Read", "Glob", "Grep"] in seiner Liste zulässiger Tools führt diese Tools ohne Nachfrage aus, abgesehen von Lesevorgängen aus Netzwerkpfaden. Tools, die nicht aufgelistet sind, sind weiterhin verfügbar, und Aufrufe an sie, die eine Genehmigung benötigen, werden an den Berechtigungsmodus und canUseTool weitergereicht.
• 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, wie viel menschliche Überwachung Sie wünschen. Das SDK wertet den aktiven Modus zusammen mit Ihren Zulassungs- und Ablehnungsregeln in einer festen Reihenfolge aus, die in Wie Berechtigungen ausgewertet werden beschrieben ist. Siehe Berechtigungsmodus für verfügbare Modi.

​

Parallele Werkzeugausführung

​

Steuern Sie, wie die Schleife ausgeführt wird

​

Durchläufe und Budget

​

Budget-Spielraum

​

Anstrengungsgrad

​

Genehmigungsmodus

​

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 Kompressor passt auf Absicht an, daher ist der Abschnittskopf frei.
• 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. Siehe dispatch commands by name.

# 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 Teilaufgaben. Jeder Subagent startet mit einer neuen Konversation (kein vorheriger Nachrichtenverlauf, er lädt jedoch seinen eigenen System-Prompt und Kontext auf Projektebene wie CLAUDE.md). Er sieht die Turns des übergeordneten Agenten nicht, und nur seine abschließende Antwort wird an den übergeordneten Agenten zurückgegeben. Der Kontext des Hauptagenten wächst um diese Zusammenfassung, nicht um das vollständige Transkript der Teilaufgabe. 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 tool search schiebt MCP-Werkzeugschemas standardmäßig auf und lädt sie bei Bedarf. Wenn die Werkzeugsuche ausgeschaltet ist oder auf vorherige Laden auf nicht unterstützten Modellen und bestimmten Plattformen zurückgefallen ist, 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. Siehe Configure tool search für die Konfigurationen, bei denen das Fallback angewendet wird.
• 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

• Nach einem Sitzungsabsturz ist das endgültige Ergebnis ein error_during_execution, dessen Kostenfelder möglicherweise auf Null gesetzt sind und dessen stop_reason null ist, und der Prozess beendet sich nach dem Ausgeben. Siehe Gesamtsummen nach einem Sitzungsabsturz wiederherstellen.
• In Python sind total_cost_usd, usage und model_usage als optional typisiert, daher überprüfen Sie, dass sie nicht None sind, bevor Sie sie lesen.

​

Hooks

​

Alles zusammenbringen

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    try:
        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}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

try {
  for await (const message of query({
    prompt: "Find and fix the bug causing test failures in the auth module",
    options: {
      allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
      settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
      maxTurns: 30, // Prevent runaway sessions
      effort: "high" // Thorough reasoning for complex debugging
    }
  })) {
    // Save the session ID to resume later if needed
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }

    // Handle the final result
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`Done: ${message.result}`);
      } else if (message.subtype === "error_max_turns") {
        // Agent ran out of turns. Resume with a higher limit.
        console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
      } else if (message.subtype === "error_max_budget_usd") {
        console.log("Hit budget limit.");
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
      console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

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.
• Stellen Sie als Service bereit? Siehe Hosting des Agent SDK für Container- und Serverless-Anleitung und Sitzungsspeicher, um Sitzungen in Ihrem eigenen Backend zu speichern.