Advisor-Tool

Mit dem Advisor-Tool kann ein schnelleres, kostengünstigeres „executor model" (Ausführungsmodell) während der Generierung ein intelligenteres „advisor model" (Berater-Modell) um strategische Orientierung bitten. Der Advisor liest die gesamte Konversation, erstellt einen Plan oder eine Kurskorrektur, und der Executor setzt die Aufgabe fort.

Dieses Muster eignet sich für agentische Workloads mit langem Zeithorizont (Coding-Agenten, Computer Use, mehrstufige Recherche-Pipelines), bei denen die meisten Turns mechanisch sind, ein hervorragender Plan aber entscheidend ist. Du erreichst nahezu die Qualität des Advisor-Modells allein, während der Großteil der Token-Generierung zu den Preisen des Executor-Modells erfolgt. Gemessene Ergebnisse, einschließlich der Frage, wie der Nutzen schrumpft, wenn sich die Fähigkeiten des Executors denen des Advisors annähern, findest du unter Optimierung von Kosten und Intelligenz.

Wann du es verwenden solltest

Der Advisor eignet sich für diese Konfigurationen:

• Du verwendest derzeit Sonnet für komplexe Aufgaben: Füge einen Advisor einer höheren Stufe hinzu. Mit Opus bleiben die Gesamtkosten ähnlich oder sinken; Claude Fable 5.1 maximiert den Qualitätsgewinn.
• Du verwendest derzeit Haiku und möchtest mehr Intelligenz: Füge einen Opus- oder Fable-Advisor hinzu. Rechne mit höheren Kosten als bei Haiku allein, aber mit niedrigeren als beim Wechsel des Executors zu einem größeren Modell.

Die Ergebnisse hängen von der Aufgabe ab. Evaluiere mit deinem eigenen Workload.

Weniger gut geeignet ist der Advisor in diesen Fällen:

• Single-Turn-Q&A, weil es nichts zu planen gibt.
• Reine Pass-through-Modellauswahlen, bei denen deine Nutzer ihren Kompromiss zwischen Kosten und Qualität bereits selbst wählen.
• Workloads, bei denen wirklich jeder Turn die volle Leistungsfähigkeit des Advisor-Modells erfordert.

Schnellstart

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-5",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

Der content der Antwort enthält einen advisor_tool_result-Block mit der Anleitung des Advisors. Dieser Schnellstart verwendet claude-opus-5 als Advisor. In diesem Fall ist das content-Feld des Blocks die Variante advisor_redacted_result. Sie ist verschlüsselt: Der Executor liest sie serverseitig, dein Client jedoch nicht. Wenn du den Ratschlagstext direkt in deiner Antwort sehen möchtest, verwende stattdessen claude-opus-4-8 als Advisor-Modell. Es gibt die Klartext-Variante advisor_result zurück. Unter Ergebnisvarianten findest du beide Formen nebeneinander und erfährst, welche Advisor-Modelle welche Variante zurückgeben. Die vollständige Liste gültiger Paare findest du unter Modellkompatibilität.

Funktionsweise

Wenn du das Advisor-Tool zu deinem tools-Array hinzufügst, entscheidet das Executor-Modell wie bei jedem anderen Tool selbst, wann es das Tool aufruft. Ein Advisor-Aufruf läuft so ab:

1. Der Executor gibt einen server_tool_use-Block mit name: "advisor" und leerem input aus. Der Executor bestimmt also den Zeitpunkt, und der Server liefert den Kontext.
2. Anthropic führt serverseitig einen separaten Inferenzdurchlauf auf dem Advisor-Modell aus. Der Advisor läuft unter seinem eigenen, von Anthropic bereitgestellten „system prompt" (System-Prompt). Als Eingabe erhält er das vollständige Transkript des Executors als zitierten Kontext. Dieses Transkript umfasst deinen System-Prompt, die Tool-Definitionen, die vorherigen Turns und Tool-Ergebnisse sowie den Text, den der Executor in diesem Turn bisher erzeugt hat.
3. Die Antwort des Advisors geht als advisor_tool_result-Block an den Executor zurück.
4. Der Executor generiert weiter und berücksichtigt dabei den Ratschlag.

All dies geschieht innerhalb einer einzigen /v1/messages-Anfrage, ohne zusätzliche Roundtrips auf deiner Seite. Die Ausnahme ist ein Turn, der mitten im Aufruf pausiert. Diesen setzt du mit einer Folgeanfrage fort (siehe Einen pausierten Turn fortsetzen).

Der Advisor selbst läuft ohne Tools und ohne Kontextverwaltung. Seine „thinking blocks" (Thinking-Blöcke) werden verworfen, bevor das Ergebnis zurückgegeben wird. Nur der Ratschlagstext erreicht den Executor.

Tool-Parameter

Das caching-Objekt hat die Form {"type": "ephemeral", "ttl": "5m" | "1h"}. Anders als cache_control bei Content-Blöcken ist es keine Breakpoint-Markierung, sondern ein Ein/Aus-Schalter. Wo die Cache-Grenzen liegen, bestimmt der Server.

Das Advisor-Tool akzeptiert außerdem die generischen Eigenschaften, die jede Tool-Definition unterstützt: cache_control, allowed_callers, defer_loading und strict (beschrieben unter Structured Outputs). Ihre Semantik findest du in der Tool-Referenz.

Antwortstruktur

Erfolgreicher Advisor-Aufruf

Wenn der Advisor aufgerufen wird, folgt im Content des Assistenten auf einen server_tool_use-Block ein advisor_tool_result-Block. Das folgende Beispiel zeigt die Klartext-Variante advisor_result, die ein Claude Opus 4.8-Advisor zurückgibt. Der Schnellstart verwendet dagegen Claude Opus 5, das die verschlüsselte Variante advisor_redacted_result zurückgibt. Beide Formen nebeneinander findest du unter Ergebnisvarianten.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

server_tool_use.input ist immer leer. Der Server erstellt die Sicht des Advisors automatisch aus dem vollständigen Transkript. Was der Executor in input einträgt, erreicht den Advisor nicht.

Ergebnisvarianten

Das Feld advisor_tool_result.content ist eine Discriminated Union. Bei erfolgreichen Aufrufen hängt die Variante vom Advisor-Modell ab:

Die folgenden Beispiele zeigen beide Varianten anhand derselben Anfrage, die zweimal gesendet wird und sich nur im Advisor-model in der Tool-Definition unterscheidet.

Mit "model": "claude-opus-4-8" ist der Ratschlag Klartext:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
  }
}

Mit "model": "claude-opus-5" ist der Ratschlag verschlüsselt:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

Beide Ergebnisvarianten enthalten ein stop_reason-Feld, wenn du max_tokens in der Tool-Definition festlegst, und lassen es weg, wenn du das nicht tust. Es enthält den Stop-Grund des Advisor-Unteraufrufs, typischerweise "end_turn", oder "max_tokens", wenn die Obergrenze erreicht wird. Die Werte entsprechen dem stop_reason der Messages API auf oberster Ebene.

Bei advisor_result enthält das Feld text menschenlesbaren Ratschlag. Bei advisor_redacted_result enthält das Feld encrypted_content einen undurchsichtigen Blob, den du nicht lesen kannst. Im nächsten Turn entschlüsselt der Server ihn und fügt den Klartext in den Prompt des Executors ein.

Gib den Inhalt in beiden Fällen in nachfolgenden Turns unverändert zurück. Wenn du mitten in der Konversation das Advisor-Modell wechselst, verzweige anhand von content.type, um beide Formen zu verarbeiten.

Fehlerergebnisse

Wenn der Advisor-Aufruf fehlschlägt, enthält das Ergebnis einen Fehler:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

Der Executor sieht den Fehler und fährt ohne weitere Ratschläge fort. Die Anfrage selbst schlägt nicht fehl.

Ratenlimits für den Advisor zählen gegen dasselbe modellbezogene Kontingent wie direkte Aufrufe des Advisor-Modells. Ein Ratenlimit beim Advisor erscheint als too_many_requests im Tool-Ergebnis. Ein Ratenlimit beim Executor lässt dagegen die gesamte Anfrage mit HTTP 429 fehlschlagen.

Multi-Turn-Konversationen

Übergib in nachfolgenden Turns den vollständigen Assistenten-Content an die API zurück, einschließlich der advisor_tool_result-Blöcke. Gib die Ergebnisblöcke dabei unverändert zurück. Bei einem Claude Opus 5-Advisor ist der content des Ergebnisblocks die verschlüsselte Variante advisor_redacted_result. Der Server entschlüsselt sie und fügt den Ratschlag im nächsten Turn in den Prompt des Executors ein (siehe Ergebnisvarianten). Die Mechanik ist für jedes Advisor-Modell identisch.

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Hänge den vollständigen Antwortinhalt an, einschließlich aller advisor_tool_result-Blöcke
messages.append({"role": "assistant", "content": response.content})

# Setze die Unterhaltung fort
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Du kannst das Advisor-Tool in einem Folge-Turn aus tools entfernen, auch wenn der Nachrichtenverlauf noch advisor_tool_result-Blöcke enthält. Die Anfrage wird akzeptiert, und die historischen Blöcke bleiben erhalten. Das Modell kann den Advisor in diesem Turn allerdings nicht aufrufen. Den Beta-Header advisor-tool-2026-03-01 musst du trotzdem senden, damit diese Verlaufsblöcke akzeptiert werden.

Einen pausierten Turn fortsetzen

Eine Antwort kann mit stop_reason: "pause_turn" enden, während ein Advisor-Aufruf noch aussteht. Die Antwort enthält dann den server_tool_use-Block des Advisors, aber kein zugehöriges advisor_tool_result.

So setzt du den Turn fort:

1. Hänge diese Assistenten-Nachricht mit unverändertem Inhalt an messages an. Der server_tool_use-Block muss dabei erhalten bleiben.
2. Sende die Anfrage erneut mit demselben Advisor-Tool und demselben Beta-Header. Eine Benutzernachricht oder einen tool_result-Block musst du nicht hinzufügen.

Die API führt den ausstehenden Advisor-Aufruf aus und setzt den Turn des Executors in der neuen Antwort fort. Ein fortgesetzter Turn kann erneut pausieren. Wiederhole in diesem Fall dieselben Schritte.

Füge das Advisor-Tool immer hinzu, solange ein Aufruf aussteht. Fehlt es in der Fortsetzungsanfrage, gibt die API einen 400 invalid_request_error zurück, weil für den ausstehenden server_tool_use-Block keine Tool-Definition vorhanden ist.

Hat der Executor im selben Turn stattdessen eines deiner Tools aufgerufen, endet die Antwort mit stop_reason: "tool_use", während der Advisor-Aufruf noch aussteht. Sende die tool_result-Blöcke wie gewohnt. Der ausstehende Advisor-Aufruf wird dann zu Beginn dieser nächsten Anfrage ausgeführt. Siehe Server-Tools und Client-Tools in einem Turn kombinieren.

Anstoß mitten in der Konversation für Executors, die zu selten aufrufen

Wenn ein Haiku-Executor den Advisor in seinem ersten Assistenten-Turn nicht aufgerufen hat, hänge vor dem zweiten Assistenten-Turn eine kurze Erinnerung als zusätzliche Nutzernachricht an. In Anthropics interner Verhaltensevaluation mit Claude Haiku 4.5-Executors erhöhte dies die Erfolgsquote bei Aufgaben um etwa 7 Prozentpunkte. Bei Sonnet-Executors hatte der Klartext-Anstoß in Anthropics Tests keinen messbaren Effekt. Die folgenden Überlegungen zum Aufrufzeitpunkt sind besonders für Sonnet relevant. Wende den Anstoß nicht auf Opus-Executors an: Bei Opus senkte er die Erfolgsquoten leicht.

Mit dem Standardwert NUDGE_TURN von 2 kommt die Erinnerung typischerweise an, nachdem sich das Modell in der Aufgabe orientiert hat, aber bevor es sich auf einen Ansatz festgelegt hat.

client = anthropic.Anthropic()

NUDGE_TURN = 2  # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
    "You have not consulted the advisor yet. If the task has a non-obvious "
    "design decision or a failure mode you haven't ruled out, call advisor "
    "now before committing to an approach."
)
MAX_TURNS = 10  # agent loop cap


def run_your_tools(content):
    # Ersetze dies durch dein Tool-Dispatching. Gibt pro tool_use-Block einen tool_result-Block zurück.
    return [
        {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "Replace with your tool output.",
        }
        for block in content
        if block.type == "tool_use"
    ]


tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... deine anderen Tools
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False

for turn in range(1, MAX_TURNS + 1):
    response = client.beta.messages.create(
        model="claude-haiku-5-5",
        max_tokens=4096,
        betas=["advisor-tool-2026-03-01"],
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
    advisor_called = advisor_called or any(
        block.type == "server_tool_use" and block.name == "advisor"
        for block in response.content
    )
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it
    if response.stop_reason != "tool_use":
        break  # end_turn, or a stop such as max_tokens that needs handling (see below)

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # Überspringe dies, wenn dein System-Prompt das Modell bereits anweist, sparsam aufzurufen.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Die Schleife endet bei jedem Stop-Grund außer tool_use oder pause_turn. Wenn max_tokens eine Antwort abschneidet, entferne den abgeschnittenen Assistenten-Turn aus messages und versuche es mit einem höheren max_tokens erneut. Wenn dieser Turn keinen tool_use-Block enthält, kannst du ihn stattdessen behalten und die Antwort fortsetzen, indem du eine neue Nutzernachricht sendest. Den abgeschnittenen Assistenten-Turn erneut als letzte Nachricht zu senden, ist ein Prefill, das Claude 4.6 und neuere Modelle ablehnen.

Hänge den Anstoß als eigene Nutzernachricht nach den Tool-Ergebnissen an, statt als Geschwisterblock in derselben Nachricht. Aufeinanderfolgende Nutzernachrichten sind gültig. In Anthropics Tests mit Claude Haiku 4.5- und Sonnet-Executors verhielten sie sich gleichwertig zu einem Geschwisterblock. Die Form als separate Nachricht hält die Erinnerung außerdem klar von der Tool-Ausgabe getrennt.

Kompromisse: Der Anstoß erhöht die Aufrufrate, was trivial einfache Aufgaben zu einer unnötigen Konsultation verleiten kann. Wenn dein Workload einfache und komplexe Aufgaben mischt, erwäge, NUDGE_TURN auf 3 zu erhöhen, damit Aufgaben mit zwei Turns abgeschlossen sind, bevor der Anstoß ausgelöst wird, oder mache den Anstoß von einem Aufgabenkomplexitätssignal abhängig, das du bereits berechnest. Wenn dein System-Prompt bereits zurückhaltende Formulierungen enthält („reserve the advisor for genuine uncertainty"), verzichte ganz auf den Anstoß, da sich die beiden Anweisungen widersprechen.

Der Klartext-Anstoß ist bei Claude Haiku 4.5- und Sonnet-Executors sehr auffällig: 74 Prozent (Sonnet) bis 98 Prozent (Claude Haiku 4.5) der angestoßenen Versuche riefen in Anthropics Tests den Advisor sofort in Turn 2 auf. Wenn das geschieht, bevor dein Executor das Problem gelesen oder Kontext gesammelt hat, ist der resultierende Advisor-Aufruf kontextarm und kann einen besser getimten späteren Aufruf verdrängen. Miss den Turn des ersten Aufrufs deines Executors als Ausgangswert, bevor du den Anstoß hinzufügst. Wenn der Executor den Advisor bereits zuverlässig aufruft und sein erster Aufruf typischerweise in Turn N erfolgt, setze NUDGE_TURN größer als N. In Anthropics Tests korrelierte ein Anstoß in Turn 2 bei Workloads, bei denen der erste Aufruf im Ausgangszustand in Turn 7 oder später erfolgte, mit einem Rückgang der Aufgabenleistung um 3 bis 4 Prozentpunkte. Bei einem Browse-Workload mit einer Ausgangs-Aufrufrate von 86 Prozent erhöhte derselbe Anstoß die Nutzung ohne Einbußen bei der Aufgabenleistung.

Um bei einer bestimmten Anfrage eine Konsultation zu erzwingen, statt einen Anstoß zu geben, setze tool_choice auf {"type": "tool", "name": "advisor"}, vorbehaltlich der Einschränkungen unter Tool-Nutzung erzwingen. Erzwungene Tool-Nutzung kann nicht mit manuellem erweitertem Nachdenken (thinking: {type: "enabled"}) kombiniert werden: Die API gibt einen 400 invalid_request_error zurück, wenn du beides aktivierst. Adaptives Nachdenken unterstützt erzwungene Tool-Nutzung. Executors vom Typ Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 und Claude Mythos 5.1 lehnen die tool_choice-Typen tool und any ab, verwende bei diesen Modellen daher stattdessen den Prompt-Anstoß.

Streaming

Die Advisor-Sub-Inferenz wird nicht gestreamt. Der Stream des Executors pausiert, während der Advisor läuft. Anschließend kommt das vollständige Ergebnis in einem einzigen Event an.

Der server_tool_use-Block mit name: "advisor" zeigt an, dass ein Advisor-Aufruf beginnt. Die Pause beginnt, wenn dieser Block geschlossen wird (content_block_stop). Während der Pause sendet der Stream nur die standardmäßigen SSE-ping-Keepalives, etwa alle 30 Sekunden. Bei kurzen Advisor-Aufrufen erscheinen möglicherweise gar keine Pings.

Wenn der Advisor fertig ist, kommt das advisor_tool_result vollständig in einem einzigen content_block_start-Event an (ohne Deltas). Danach wird die Ausgabe des Executors weiter gestreamt.

Anschließend folgt ein message_delta-Event. Sein aktualisiertes usage.iterations-Array enthält die Token-Zahlen des Advisors.

Nutzung und Abrechnung

Advisor-Aufrufe laufen als separate Sub-Inferenz und werden zu den Preisen des Advisor-Modells abgerechnet. Die Nutzung wird im Array usage.iterations[] gemeldet:

{
  "usage": {
    "input_tokens": 1760,
    "cache_read_input_tokens": 412,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-5",
        "input_tokens": 823,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "cache_creation_input_tokens": 0,
        "output_tokens": 442
      }
    ]
  }
}

Die usage-Felder auf oberster Ebene enthalten nur Executor-Tokens. Advisor-Tokens fließen nicht in diese Gesamtsummen ein, weil sie zu einem anderen Preis abgerechnet werden. Iterationen mit type: "advisor_message" werden zu den Preisen des Advisor-Modells abgerechnet, Iterationen mit type: "message" zu den Preisen des Executor-Modells.

Jedes usage-Feld auf oberster Ebene ist die Summe dieses Felds über alle Executor-Iterationen. Das gilt auch für input_tokens, output_tokens und cache_read_input_tokens. Jede Executor-Iteration sendet die wachsende Konversation erneut, sodass die Eingaben späterer Iterationen die Ausgaben früherer Iterationen enthalten. Die summierten input_tokens sind deshalb größer als jeder einzelne Prompt. Wenn du Logik zur Kostenverfolgung erstellst, verwende usage.iterations für eine vollständige Aufschlüsselung pro Iteration.

Die Advisor-Ausgabe umfasst typischerweise 400 bis 700 Text-Tokens bzw. insgesamt 1.400 bis 1.800 Tokens einschließlich Nachdenken. Die Kosteneinsparung entsteht, weil nicht der Advisor deine vollständige finale Ausgabe generiert, sondern der Executor zu seinem niedrigeren Preis.

Das max_tokens auf oberster Ebene gilt nur für die Executor-Ausgabe und begrenzt die Tokens der Advisor-Sub-Inferenz nicht. Um die Advisor-Ausgabe direkt zu begrenzen, setze max_tokens in der Tool-Definition. Die Tokens des Advisors werden außerdem nicht von einem Task-Budget des Executors abgezogen.

Priority Tier gilt für jedes Modell separat. Eine Priority-Tier-Zusage für das Executor-Modell gilt nicht für den Advisor. Advisor-Aufrufe laufen nur dann im Priority Tier, wenn deine Organisation auch für das Advisor-Modell eine Zusage hat.

Advisor-Prompt-Caching

Es gibt zwei unabhängige Caching-Ebenen.

Caching auf Executor-Seite

Der advisor_tool_result-Block lässt sich wie jeder andere Content-Block cachen. Ein cache_control-Breakpoint, den du in einem nachfolgenden Turn hinter diesem Block platzierst, erzielt einen Cache-Treffer. Der Prompt des Executors enthält den Ratschlag immer im Klartext, unabhängig davon, ob dein Client text oder encrypted_content erhalten hat. Das Caching-Verhalten ist daher für beide Ergebnisvarianten identisch.

Advisor-seitiges Caching

Setze caching in der Tool-Definition, um Prompt-Caching für das eigene Transkript des Advisors über Aufrufe innerhalb derselben Konversation hinweg zu aktivieren:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

Der Prompt des Advisors beim N-ten Aufruf ist der Prompt des (N-1)-ten Aufrufs mit einem zusätzlich angehängten Segment, sodass das Präfix über Aufrufe hinweg stabil ist. Mit aktiviertem caching schreibt jeder Advisor-Aufruf einen Cache-Eintrag, und der nächste Aufruf liest bis zu diesem Punkt und zahlt nur für das Delta. Du wirst sehen, dass cache_read_input_tokens bei der zweiten und späteren advisor_message-Iterationen ungleich null wird.

Wann du es aktivieren solltest: Das Schreiben in den Cache kostet mehr, als die Lesevorgänge einsparen, wenn der Advisor zweimal oder seltener pro Konversation aufgerufen wird. Caching rechnet sich ab etwa drei Advisor-Aufrufen und wird von da an besser. Aktiviere es für lange Agenten-Schleifen und lass es bei kurzen Aufgaben deaktiviert.

Bleib konsistent: Setze caching einmal und lass es für die gesamte Konversation bestehen. Wenn du es mitten in der Konversation aus- und wieder einschaltest, führt das zu Cache-Misses.

Kombination mit anderen Tools

Das Advisor-Tool lässt sich mit anderen serverseitigen und clientseitigen Tools kombinieren. Füge sie alle zum selben tools-Array hinzu:

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Der Executor kann im selben Turn im Web suchen, den Advisor aufrufen und deine benutzerdefinierten Tools verwenden. Der Plan des Advisors kann beeinflussen, zu welchen Tools der Executor als Nächstes greift.

Best Practices

Prompting für Coding- und Agent-Aufgaben

Das Advisor-Tool bringt eine eingebaute Beschreibung mit. Sie regt den Executor an, den Advisor zu Beginn komplexer Aufgaben und bei Schwierigkeiten aufzurufen. Für Rechercheaufgaben ist typischerweise kein zusätzliches Prompting nötig.

Bei Coding- und Agent-Aufgaben liefert der Advisor höhere Intelligenz bei ähnlichen Kosten, wenn er die Gesamtzahl der Tool-Aufrufe und die Länge der Konversation reduziert. Entscheidend dafür sind zwei Zeitpunkte:

1. Ein früher erster Advisor-Aufruf, sobald einige erkundende Lesevorgänge im Transkript stehen.
2. Bei schwierigen Aufgaben ein abschließender Advisor-Aufruf, sobald Dateischreibvorgänge und Testausgaben im Transkript stehen.

Stellt dein Agent weitere planerähnliche Tools bereit (zum Beispiel ein Todo-Listen-Tool), weise das Modell an, den Advisor vor diesen Tools aufzurufen. So fließt der Plan des Advisors in diese Tools ein. Der vorgeschlagene System-Prompt fördert den frühen Aufruf. Ergänze ihn um einen eigenen Satz, der auf die Planer-Tools deines Agents verweist.

Vorgeschlagener System-Prompt für Coding-Aufgaben

Ohne Steuerung über den System-Prompt ruft der Executor den Advisor in manchen Domänen zu selten auf, insbesondere bei Coding-Aufgaben. Für Coding-Aufgaben mit konsistentem Timing und etwa zwei bis drei Advisor-Aufrufen pro Aufgabe stellst du die folgenden Blöcke an den Anfang deines Executor-System-Prompts. Sie müssen vor allen anderen Sätzen stehen, die den Advisor erwähnen.

Hinweise zum Timing:

You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

Wie der Executor den Ratschlag behandeln soll (direkt nach dem Timing-Block platzieren):

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Alternativer System-Prompt für Haiku bei Coding-Workloads

Claude Haiku 4.5 setzt die Standard-Advisor-Anleitung zurückhaltend um. Bei Recherche- und Nachschlage-Workloads bleibt die Aufrufrate dadurch angemessen niedrig. Bei Coding-Workloads kostet das jedoch Qualität, denn dort zahlt sich eine frühe Advisor-Konsultation zuverlässig aus. In einem internen Coding-Benchmark erhöhte eine eng verwandte Variante des folgenden Blocks die Erfolgsquoten von Haiku um etwa 7,5 Prozentpunkte gegenüber dem eingebauten Standard. Die Ausnahme für reine Lesevorgänge in der Hard rule wurde erst nach dieser Messung hinzugefügt.

Verwende diesen Block anstelle der beiden vorherigen Blöcke (Timing und Umgang mit dem Ratschlag), wenn dein Haiku-Executor überwiegend Coding- oder Schreibaufgaben bearbeitet:

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Einschränkung: In einem internen Browse-Comprehension-Benchmark (n = 1.266) senkte eine eng verwandte Variante dieses Blocks die Genauigkeit um etwa 4 Prozentpunkte gegenüber dem eingebauten Standard. Wenn dein Workload Coding mit umfangreichen Nachschlage- oder Retrieval-Aufgaben mischt, bleib bei den vorgeschlagenen Blöcken. Alternativ kannst du den Austausch von einem Signal zum Workload-Typ abhängig machen, das du bereits berechnest.

Advisor-Aufrufe bei Opus-Executors erhöhen

Opus-Executors rufen den Advisor typischerweise auch ohne zusätzliches Prompting angemessen oft auf. Wenn dein Opus-Executor den Advisor bei deinem Workload zu selten aufruft, füge deinem System-Prompt den folgenden Checkpoint hinzu:

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Einschränkung: In Anthropics Tests erhöhte eine eng verwandte Variante dieses Blocks die Erfolgsquoten bei Aufgaben mit zu seltenen Aufrufen um etwa 7 bis 10 Prozentpunkte. Die Ausnahme für reine Lesevorgänge in der Hard rule wurde erst nach dieser Messung hinzugefügt. Gleichzeitig rief Opus den Advisor zu häufig auf, wenn die erste Aktion einer Aufgabe keine Planung erforderte. Bei einem gemischten Workload war der Nettoeffekt ungefähr neutral. Füge den Block nur hinzu, wenn du beobachtet hast, dass Opus den Advisor bei Aufgaben überspringt, bei denen eine Konsultation geholfen hätte. Verwende ihn nicht als Standard.

Länge der Advisor-Ausgabe kürzen

Die Ausgabe ist der größte Kostentreiber des Advisors, und das max_tokens auf oberster Ebene begrenzt sie nicht. Der Advisor sieht deinen System-Prompt und deine Benutzernachrichten als zitierten Kontext zur Aufgabe des Executors. Anweisungen, die den Advisor direkt ansprechen, befolgt er deshalb deutlich zuverlässiger als Beschreibungen in der dritten Person. Am wirksamsten war in Anthropics Tests eine Zeile in der Benutzernachricht:

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

Dein Agent-Framework kann diese Zeile vor dem Senden der Anfrage programmatisch voranstellen. Das Limit ist nur eine weiche Vorgabe, die der Advisor gelegentlich überschreitet. Fordere deshalb etwa 80 Prozent deiner tatsächlichen Obergrenze an.

Den besten Kompromiss zwischen Kosten und Qualität erzielst du, wenn du diesen Ansatz mit den Timing-Hinweisen unter Vorgeschlagener System-Prompt für Coding-Aufgaben kombinierst. Falls du stattdessen den alternativen Haiku-Block verwendest, kombiniere ihn mit diesem. Eine harte Obergrenze statt einer weichen Vorgabe beschreibt Advisor-Ausgabe begrenzen.

Advisor-Ausgabe begrenzen

Setze max_tokens in der Tool-Definition, um die gesamte Ausgabe des Advisors (Nachdenken plus Text) pro Aufruf zu begrenzen:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "max_tokens": 2048,
    }
]

Der Mindestwert ist 1024. Liegt max_tokens über der Ausgabeobergrenze des Advisor-Modells, gibt die API einen 400-Fehler zurück. Die Obergrenze gilt für jeden Advisor-Aufruf einzeln und wird nicht zwischen den Aufrufen einer Anfrage geteilt.

Die Ausgabe wird dabei nicht einfach hart abgeschnitten. Der Server teilt dem Advisor auch sein verbleibendes Token-Budget mit, sodass der Advisor seine Antwort daran anpasst.

Empfohlener Ausgangspunkt: max_tokens: 2048. Anthropic hat diesen Wert mit einem anspruchsvollen Reasoning-Benchmark getestet (n = 40 pro Konfiguration). Im Vergleich zu einer nicht gesetzten Obergrenze sank die durchschnittliche Advisor-Ausgabe auf etwa ein Siebtel. Dabei wurden fast keine Aufrufe gekürzt, und es gab keine erkennbaren Qualitätseinbußen. Mit dem Mindestwert 1024 sank die Ausgabe auf etwa ein Zehntel, allerdings wurden rund 10 Prozent der Aufrufe gekürzt. Die Genauigkeitsunterschiede zwischen den Konfigurationen lagen bei dieser Stichprobengröße im Rauschen. Validiere die Werte mit deinem eigenen Workload.

Bei anspruchsvollen Reasoning-Aufgaben fällt die Advisor-Ausgabe deutlich länger aus als die typischen 1.400 bis 1.800 Tokens, die weiter oben für leichtere Workloads genannt sind. Nutze die Tabelle, um das Einsparungsverhältnis abzuschätzen, nicht als allgemeingültigen Richtwert für die Länge der Advisor-Ausgabe.

Erreicht der Advisor die Obergrenze, enthält der Ergebnisblock stop_reason: "max_tokens". Das gilt für beide Ergebnisvarianten und unabhängig vom Advisor-Modell. Anhand von stop_reason erkennst du gekürzte Ratschläge. Du kannst dann entscheiden, ob du die Obergrenze erhöhst oder den Executor mit der unvollständigen Anleitung weiterarbeiten lässt.

Die API hängt außerdem [Advisor output truncated at max_tokens=2048.] an den Ratschlagstext an, wobei der Wert deiner Obergrenze entspricht. So sieht der Executor die Kürzung in seinem eigenen Kontext. Bei einem Advisor, der das Klartext-advisor_result zurückgibt, sieht auch dein Client diese Markierung. Beide Signale erscheinen nur, wenn du max_tokens in der Tool-Definition setzt.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

Wie nah ein Aufruf an seine Obergrenze herankam, siehst du an output_tokens im zugehörigen advisor_message-Eintrag in usage.iterations.

Anders als der Prompt-basierte Ansatz ist max_tokens eine harte Obergrenze statt einer weichen Vorgabe. Verwende max_tokens, wenn du eine garantierte Grenze für Kosten oder „latency" (Latenz) brauchst. Verwende den Prompt-basierten Ansatz (oder beide zusammen), wenn du kürzere Antworten erreichen möchtest, ohne zu riskieren, dass der Advisor mitten im Gedanken abgeschnitten wird.

Kombination mit Effort-Einstellungen

Für Coding-Aufgaben erreicht die Kombination eines Sonnet-Modells als „executor" (ausführendes Modell) mit mittlerem „effort" (Aufwand) und eines Opus-Modells als „advisor" (beratendes Modell) eine Intelligenz, die mit Sonnet bei Standard-Effort vergleichbar ist, und das zu geringeren Kosten. Für maximale Intelligenz belässt du den Executor beim Standard-Effort.

Kostenkontrolle

• Für Budgets auf Konversationsebene zählst du die Advisor-Aufrufe clientseitig. Wenn du dein Limit erreichst, entferne das Advisor-Tool aus tools. Du musst keine advisor_tool_result-Blöcke aus deinem Nachrichtenverlauf entfernen (siehe den Hinweis unter Multi-Turn-Konversationen).
• Aktiviere caching nur für Konversationen, in denen du drei oder mehr Advisor-Aufrufe erwartest.

Modellkompatibilität

Das Executor-Modell (das model-Feld auf oberster Ebene) und das Advisor-Modell (das model-Feld innerhalb der Tool-Definition) müssen ein gültiges Paar bilden. Der Advisor muss Claude Sonnet 4.6 oder ein leistungsfähigeres Modell sein, und er muss mindestens so leistungsfähig sein wie der Executor. Modelle mit gleicher Leistungsfähigkeit (zum Beispiel Claude Opus 4.7 und Claude Opus 4.8) können sich gegenseitig beraten.

Wenn du ein ungültiges Paar anforderst, gibt die API einen 400 invalid_request_error zurück, der die nicht unterstützte Kombination benennt.

Plattformverfügbarkeit

Das Advisor-Tool ist als Beta auf der Claude API und auf Claude Platform on AWS verfügbar. Auf Amazon Bedrock, Google Cloud und Microsoft Foundry ist es derzeit nicht verfügbar.

Advisor in Claude Managed Agents

Sessions in Claude Managed Agents unterstützen ebenfalls einen Advisor, der als Teil des Agenten statt als Tool-Definition konfiguriert wird: Setze "advisor": {"type": "enabled", "model": ...} im multiagent-Block des Agenten, und der primäre Thread der Session kann dieses Modell mitten im Turn konsultieren. Die Einstellung akzeptiert keine der Optionen max_uses, max_tokens oder caching, und Ratschläge werden als Thread-Events im Event-Stream der Session statt als advisor_tool_result-Blöcke in der Antwort geliefert. Siehe Der Session einen Advisor geben.

Nächste Schritte