Advisor-Tool

Das Advisor-Tool ermöglicht es einem schnelleren, kostengünstigeren Executor-Modell, während der Generierung ein intelligenteres Advisor-Modell für strategische Anleitung zu konsultieren. Der Advisor liest die gesamte Konversation, erstellt einen Plan oder eine Kurskorrektur, und der Executor fährt mit der Aufgabe fort.

Dieses Muster eignet sich für langfristige agentische Workloads (Coding-Agenten, Computer-Nutzung, mehrstufige Recherche-Pipelines), bei denen die meisten Turns mechanisch sind, aber ein exzellenter Plan entscheidend ist. Du erhältst eine Qualität, die nahe an der eines alleinigen Advisors liegt, während der Großteil der Token-Generierung zu den Raten des Executor-Modells erfolgt.



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. Opus hält die Gesamtkosten ähnlich oder niedriger; Claude Fable 5 maximiert den Qualitätsgewinn.
• Du verwendest derzeit Haiku und möchtest einen Intelligenzsprung: Füge einen Opus- oder Fable-Advisor hinzu. Erwarte höhere Kosten als mit Haiku allein, aber niedrigere als beim Wechsel des Executors zu einem größeren Modell.

Die Ergebnisse sind aufgabenabhängig. Evaluiere auf deinem eigenen Workload.

Der Advisor eignet sich weniger für Single-Turn-Q&A (nichts zu planen), reine Pass-Through-Modellauswahlen, bei denen deine Nutzer bereits ihren eigenen Kosten-Qualitäts-Kompromiss wählen, oder Workloads, bei denen jeder Turn tatsächlich 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. Mit Claude Opus 5, Claude Fable 5 oder Claude Mythos 5 als Advisor ist das content-Feld des Blocks eine advisor_redacted_result-Variante (verschlüsselt; der Executor liest sie serverseitig, aber dein Client nicht). Um den Ratschlagstext direkt in deiner Antwort zu sehen, verwende stattdessen claude-opus-4-8 als Advisor-Modell, das die Klartext-Variante advisor_result zurückgibt. Siehe Ergebnisvarianten für beide Formen und Modellkompatibilität für die vollständige Liste gültiger Paare.



Funktionsweise

Wenn du das Advisor-Tool zu deinem tools-Array hinzufügst, bestimmt das Executor-Modell, wann es aufgerufen wird, wie bei jedem anderen Tool. Wenn der Executor den Advisor aufruft:

1. Der Executor gibt einen server_tool_use-Block mit name: "advisor" und einem leeren input aus. Der Executor signalisiert das Timing, 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 und erhält das vollständige Transkript des Executors als zitierten Kontext in seinem Input. Dieses Transkript umfasst deinen System-Prompt, die Tool-Definitionen, die vorherigen Turns und Tool-Ergebnisse sowie den Text, den der Executor bisher in diesem Turn produziert hat.
3. Die Antwort des Advisors kehrt als advisor_tool_result-Block zum Executor zurück.
4. Der Executor setzt die Generierung fort, informiert durch 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 und den du mit einer Folgeanfrage fortsetzt (siehe Fortsetzen eines pausierten Turns).

Der Advisor selbst läuft ohne Tools und ohne Kontextverwaltung. Seine Thinking-Blöcke werden verworfen, bevor das Ergebnis zurückkehrt. 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 dies kein Breakpoint-Marker. Es ist ein Ein/Aus-Schalter. Der Server bestimmt, wo Cache-Grenzen liegen.

Das Advisor-Tool akzeptiert auch die generischen Eigenschaften, die für jede Tool-Definition verfügbar sind: cache_control, allowed_callers, defer_loading und strict (behandelt in strukturierte Ausgaben). Siehe die Tool-Referenz für deren Semantik.



Antwortstruktur



Erfolgreicher Advisor-Aufruf

Wenn der Advisor aufgerufen wird, folgt auf einen server_tool_use-Block ein advisor_tool_result-Block im Content des Assistenten. Das folgende Beispiel zeigt die Klartext-Variante advisor_result, die von einem Claude Opus 4.8-Advisor zurückgegeben wird. Der Schnellstart verwendet Claude Opus 5, das stattdessen die verschlüsselte Variante advisor_redacted_result zurückgibt; siehe 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..."
    }
  ]
}

Das server_tool_use.input ist immer leer. Der Server konstruiert die Sicht des Advisors automatisch aus dem vollständigen Transkript. Nichts, was der Executor in input setzt, erreicht den Advisor.



Ergebnisvarianten

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

Claude Opus 5-, Claude Fable 5- und Claude Mythos 5-Advisors geben advisor_redacted_result zurück. Die anderen Advisor-Modelle in der Kompatibilitätstabelle geben advisor_result zurück.

Beide Ergebnisvarianten enthalten ein stop_reason-Feld, wenn du max_tokens in der Tool-Definition setzt, und lassen es weg, wenn nicht. Es enthält den Stop-Reason des Advisor-Sub-Aufrufs, typischerweise "end_turn" oder "max_tokens", wenn die Obergrenze erreicht wird. Die Werte entsprechen dem Top-Level-stop_reason der Messages API.

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

In beiden Fällen sende den Content bei nachfolgenden Turns unverändert zurück. Wenn du mitten in der Konversation das Advisor-Modell wechselst, verzweige auf content.type, um beide Formen zu behandeln.



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 weiteren Ratschlag fort. Die Anfrage selbst schlägt nicht fehl.

Advisor-Ratenlimits ziehen aus demselben modellspezifischen Bucket wie direkte Aufrufe an das Advisor-Modell. Ein Ratenlimit beim Advisor erscheint als too_many_requests innerhalb des Tool-Ergebnisses. Ein Ratenlimit beim Executor lässt die gesamte Anfrage mit HTTP 429 fehlschlagen.



Multi-Turn-Konversationen

Übergib den vollständigen Assistenten-Content, einschließlich advisor_tool_result-Blöcken, bei nachfolgenden Turns zurück an die API. Dieses Beispiel verwendet claude-opus-4-8 als Advisor, damit der Klartext-Ratschlag in response.content sichtbar ist; die Mechanik ist für jedes Advisor-Modell identisch.

client = anthropic.Anthropic()

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

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 Konversation 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 bei einem Folge-Turn aus tools entfernen, während 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 nicht aufrufen. Du musst weiterhin den Beta-Header advisor-tool-2026-03-01 senden, damit diese Verlaufsblöcke akzeptiert werden.



Fortsetzen eines pausierten Turns

Eine Antwort kann mit stop_reason: "pause_turn" enden, während ein Advisor-Aufruf noch aussteht. In diesem Fall enthält die Antwort den server_tool_use-Block des Advisors ohne zugehöriges advisor_tool_result. Um fortzufahren, hänge diese Assistenten-Nachricht mit unverändertem Content an messages an, behalte den server_tool_use-Block bei und sende die Anfrage erneut mit demselben Advisor-Tool und Beta-Header. Du musst keine User-Nachricht oder einen tool_result-Block 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. Wenn das passiert, wiederhole denselben Schritt. Das Weglassen des Advisor-Tools aus der Fortsetzungsanfrage gibt einen 400 invalid_request_error zurück, weil der ausstehende server_tool_use-Block keine Tool-Definition hat, gegen die er ausgeführt werden kann; füge das Tool immer hinzu, wenn ein Aufruf aussteht. Wenn der Executor stattdessen im selben Turn eines deiner Tools aufgerufen hat, endet die Antwort mit stop_reason: "tool_use", während der Advisor-Aufruf noch aussteht. Sende die tool_result-Blöcke wie gewohnt, und der ausstehende Advisor-Aufruf wird zu Beginn dieser nächsten Anfrage ausgeführt. Siehe Mischen von Server-Tools und Client-Tools in einem Turn.



Nudge 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 User-Nachricht an. In Anthropics interner Verhaltensevaluierung erhöhte dies die Task-Pass-Raten bei Haiku-Executors um etwa 7 Prozentpunkte. Bei Sonnet-Executors hatte der Klartext-Nudge in Anthropics Tests keinen messbaren Effekt. Die folgenden Überlegungen zum Aufruf-Timing sind besonders relevant für Sonnet. Wende den Nudge nicht auf Opus-Executors an: Bei Opus senkte er die Pass-Raten leicht.

Mit dem Standard-NUDGE_TURN von 2 kommt die Erinnerung typischerweise an, nachdem sich das Modell an 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 deinen Tool-Dispatch. Gibt einen tool_result-Block pro tool_use-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-4-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 == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    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 dem Modell bereits sagt, sparsam aufzurufen.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Hänge den Nudge als eigene User-Nachricht nach den Tool-Ergebnissen an, statt als Geschwister-Block in derselben Nachricht. Aufeinanderfolgende User-Nachrichten sind gültig. In Anthropics Tests mit Haiku- und Sonnet-Executors verhielten sie sich äquivalent zu einem Geschwister-Block. Die Form als separate Nachricht hält die Erinnerung auch klar von der Tool-Ausgabe getrennt.

Trade-offs: Der Nudge erhöht die Aufrufrate, was trivial einfache Aufgaben in eine unnötige Konsultation drängen kann. Wenn dein Workload einfache und komplexe Aufgaben mischt, erwäge, NUDGE_TURN auf 3 zu erhöhen, damit Zwei-Turn-Aufgaben abgeschlossen werden, bevor der Nudge ausgelöst wird, oder mache den Nudge von einem Aufgabenkomplexitätssignal abhängig, das du bereits berechnest. Wenn dein System-Prompt bereits Zurückhaltungsformulierungen enthält („reserviere den Advisor für echte Unsicherheit"), überspringe den Nudge vollständig, da die beiden Anweisungen in Konflikt stehen.

Der Klartext-Nudge ist bei Haiku- und Sonnet-Executors sehr auffällig: 74 Prozent (Sonnet) bis 98 Prozent (Haiku) der genudgten Versuche in Anthropics Tests riefen den Advisor sofort bei Turn 2 auf. Wenn das eintrifft, 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 Baseline-Turn des ersten Aufrufs deines Executors, bevor du den Nudge hinzufügst. Wenn der Executor den Advisor bereits zuverlässig aufruft und sein erster Aufruf typischerweise bei Turn N landet, setze NUDGE_TURN größer als N. In Anthropics Tests korrelierte ein Turn-2-Nudge bei Workloads, bei denen der Baseline-Erstaufruf bei Turn 7 oder später lag, mit einem Rückgang der Task-Performance um 3 bis 4 Prozentpunkte. Bei einem Browse-Workload, bei dem die Baseline-Aufrufrate 86 Prozent betrug, erhöhte derselbe Nudge das Engagement ohne Kosten bei der Task-Performance.

Um eine Konsultation bei einer bestimmten Anfrage zu erzwingen statt zu nudgen, setze tool_choice auf {"type": "tool", "name": "advisor"}, vorbehaltlich der Einschränkungen in Tool-Nutzung erzwingen. Das Erzwingen der Tool-Nutzung kann nicht mit manuellem erweitertem Denken (thinking: {type: "enabled"}) kombiniert werden: Die API gibt einen 400 invalid_request_error zurück, wenn du beides aktivierst. Adaptives Thinking unterstützt erzwungene Tool-Nutzung.



Streaming

Die Advisor-Sub-Inferenz streamt nicht. Der Stream des Executors pausiert, während der Advisor läuft; dann kommt das vollständige Ergebnis in einem einzigen Event an.

Der server_tool_use-Block mit name: "advisor" signalisiert, dass ein Advisor-Aufruf beginnt. Die Pause beginnt, wenn dieser Block schließt (content_block_stop). Während der Pause ist der Stream still, abgesehen von standardmäßigen SSE-ping-Keepalives, die etwa alle 30 Sekunden ausgegeben werden. Kurze Advisor-Aufrufe zeigen möglicherweise keine Pings.

Wenn der Advisor fertig ist, kommt das advisor_tool_result vollständig geformt in einem einzigen content_block_start-Event an (keine Deltas). Die Executor-Ausgabe setzt dann das Streaming fort.

Ein message_delta-Event folgt mit dem aktualisierten usage.iterations-Array, das die Token-Zählungen des Advisors widerspiegelt.



Nutzung und Abrechnung

Advisor-Aufrufe laufen als separate Sub-Inferenz, die zu den Raten des Advisor-Modells abgerechnet wird. Die Nutzung wird im usage.iterations[]-Array 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
      }
    ]
  }
}

Top-Level-usage-Felder spiegeln nur Executor-Tokens wider. Advisor-Tokens werden nicht in die Top-Level-Summen eingerechnet, da sie zu einer anderen Rate abgerechnet werden. Iterationen mit type: "advisor_message" werden zu den Raten des Advisor-Modells abgerechnet, und Iterationen mit type: "message" werden zu den Raten des Executor-Modells abgerechnet.

Jedes Top-Level-usage-Feld ist die Summe dieses Felds über alle Executor-Iterationen, einschließlich input_tokens, output_tokens und cache_read_input_tokens. Da jede Executor-Iteration die wachsende Konversation erneut sendet, enthalten die Inputs späterer Iterationen die Outputs früherer Iterationen, sodass die summierten input_tokens die Größe jedes einzelnen Prompts übersteigen. Verwende usage.iterations für eine vollständige Aufschlüsselung pro Iteration beim Erstellen von Kostenverfolgungslogik.

Die Advisor-Ausgabe beträgt typischerweise 400 bis 700 Text-Tokens oder 1.400 bis 1.800 Tokens insgesamt einschließlich Thinking. Die Kosteneinsparungen ergeben sich daraus, dass der Advisor nicht deine vollständige finale Ausgabe generiert. Das macht der Executor zu seiner niedrigeren Rate.

Das Top-Level-max_tokens gilt nur für die Executor-Ausgabe. Es begrenzt nicht die Tokens der Advisor-Sub-Inferenz. Um die Advisor-Ausgabe direkt zu begrenzen, setze max_tokens in der Tool-Definition. Die Tokens des Advisors ziehen auch nicht von einem Task-Budget ab, das auf den Executor angewendet wird.

Priority Tier gilt für jedes Modell unabhängig. Ein Priority-Tier-Commitment für das Executor-Modell erstreckt sich nicht auf den Advisor. Advisor-Aufrufe laufen nur dann auf Priority Tier, wenn deine Organisation auch ein Commitment für das Advisor-Modell hält.



Advisor-Prompt-Caching

Es gibt zwei unabhängige Caching-Ebenen.



Executor-seitiges Caching

Der advisor_tool_result-Block ist wie jeder andere Content-Block cachebar. Ein cache_control-Breakpoint, der bei einem nachfolgenden Turn danach platziert wird, trifft. Der Prompt des Executors enthält immer den Klartext-Ratschlag, unabhängig davon, ob dein Client text oder encrypted_content erhalten hat, sodass das Caching-Verhalten für beide Ergebnisvarianten identisch ist.



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 weiteren 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 Cache-Schreiben kostet mehr, als die Lesevorgänge einsparen, wenn der Advisor zwei oder weniger Mal pro Konversation aufgerufen wird. Caching erreicht den Break-even bei etwa drei Advisor-Aufrufen und verbessert sich von dort aus. Aktiviere es für lange Agent-Loops und lass es für kurze Aufgaben aus.

Halte es konsistent: Setze caching einmal und belasse es für die gesamte Konversation. Das Aus- und Einschalten mitten in der Konversation verursacht Cache-Misses.



Kombination mit anderen Tools

Das Advisor-Tool lässt sich mit anderen serverseitigen und clientseitigen Tools kombinieren. Füge sie alle demselben 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 das Web durchsuchen, 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 wird mit einer eingebauten Beschreibung ausgeliefert, die den Executor dazu anregt, es zu Beginn komplexer Aufgaben und bei Schwierigkeiten aufzurufen. Für Recherche-Aufgaben ist typischerweise kein zusätzliches Prompting erforderlich.

Bei Coding- und Agent-Aufgaben liefert der Advisor höhere Intelligenz bei ähnlichen Kosten, wenn er die Gesamtzahl der Tool-Aufrufe und die Konversationslänge reduziert. Zwei Timings treiben diese Verbesserung an:

1. Ein früher erster Advisor-Aufruf, nachdem einige explorative Lesevorgänge im Transkript sind.
2. Bei schwierigen Aufgaben ein finaler Advisor-Aufruf, nachdem Dateischreibvorgänge und Testausgaben im Transkript sind.

Wenn dein Agent andere planerähnliche Tools bereitstellt (z. B. ein Todo-Listen-Tool), prompte das Modell, den Advisor vor diesen Tools aufzurufen, damit der Plan des Advisors in sie einfließt. Der vorgeschlagene System-Prompt verstärkt das Muster des frühen Aufrufs. Füge deinen eigenen Einleitungssatz hinzu, der auf die Planer-Tools verweist, die dein Agent bereitstellt.



Vorgeschlagener System-Prompt für Coding-Aufgaben

Ohne System-Prompt-Steuerung neigt der Executor dazu, den Advisor in einigen Domänen zu selten aufzurufen, insbesondere bei Coding-Aufgaben. Für Coding-Aufgaben, bei denen du konsistentes Advisor-Timing und etwa zwei bis drei Aufrufe pro Aufgabe möchtest, stelle die folgenden Blöcke deinem Executor-System-Prompt voran, vor allen anderen Sätzen, die den Advisor erwähnen.

Timing-Anleitung:

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 sollte (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 wendet die Standard-Advisor-Anleitung konservativ an. Das hält seine Aufrufrate bei Recherche- und Lookup-Workloads angemessen niedrig, verschenkt aber Qualität bei Coding-Workloads, bei denen sich eine frühe Advisor-Konsultation zuverlässig auszahlt. Bei einem internen Coding-Benchmark erhöhte eine nahe Variante des folgenden Blocks (die Read-only-Ausnahme in der Hard-Regel wurde nach der Messung hinzugefügt) die Haiku-Pass-Raten um etwa 7,5 Prozentpunkte gegenüber dem eingebauten Standard.

Verwende diesen Block anstelle der früheren Timing- und Ratschlagsblöcke, wenn dein Haiku-Executor überwiegend Coding- oder Schreibaufgaben-Workloads ausführt:

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.

Vorbehalt: Bei einem internen Browse-Comprehension-Benchmark (n = 1.266) kostete eine nahe Variante dieses Blocks etwa 4 Prozentpunkte Genauigkeit im Vergleich zum eingebauten Standard. Wenn dein Workload Coding mit erheblichem Lookup oder Retrieval mischt, bleibe bei den vorgeschlagenen Blöcken oder mache den Wechsel von einem Workload-Typ-Signal abhängig, das du bereits berechnest.



Erhöhen der Advisor-Aufrufe bei Opus-Executors

Opus-Executors rufen den Advisor typischerweise ohne zusätzliches Prompting mit einer angemessenen Rate auf. Wenn dein Opus-Executor bei deinem Workload zu selten aufruft, füge den folgenden Checkpoint zu deinem System-Prompt 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.

Vorbehalt: In Anthropics Tests erhöhte eine nahe Variante dieses Blocks (die Read-only-Ausnahme in der Hard-Regel wurde nach der Messung hinzugefügt) die Pass-Raten bei Aufgaben mit zu seltenen Aufrufen um etwa 7 bis 10 Prozentpunkte, führte aber dazu, dass Opus bei Aufgaben, deren erste Aktion keine Planung benötigt, zu oft aufrief. Der Nettoeffekt war bei einem gemischten Workload etwa neutral. Füge ihn nur hinzu, wenn du beobachtet hast, dass Opus den Advisor bei Aufgaben überspringt, bei denen eine Konsultation geholfen hätte. Füge ihn nicht als Standard hinzu.



Kürzen der Advisor-Ausgabelänge

Die Advisor-Ausgabe ist der größte Kostentreiber des Advisors, und das Top-Level-max_tokens begrenzt sie nicht. Der Advisor sieht sowohl deinen System-Prompt als auch deine User-Nachrichten als zitierten Kontext über die Aufgabe des Executors, sodass Anweisungen, die den Advisor direkt ansprechen, viel zuverlässiger befolgt werden als Beschreibungen in der dritten Person. Die effektivste Platzierung, die Anthropic getestet hat, ist eine Zeile in der User-Nachricht:

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

Diese Zeile kann von deinem Agent-Framework programmatisch vorangestellt werden, bevor die Anfrage gesendet wird. Das Limit ist eine weiche Einschränkung. Der Advisor überschreitet es gelegentlich, also frage nach etwa 80 Prozent deiner tatsächlichen Obergrenze.

Kombiniere diesen Ansatz mit der Timing-Anleitung in Vorgeschlagener System-Prompt für Coding-Aufgaben (oder dem alternativen Haiku-Block, falls du ihn eingetauscht hast) für den stärksten Kosten-Qualitäts-Kompromiss. Für eine harte Obergrenze statt einer weichen Anfrage siehe Begrenzen der Advisor-Ausgabe.



Begrenzen der Advisor-Ausgabe

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

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

Der Mindestwert ist 1024. Das Setzen von max_tokens über die eigene Output-Obergrenze des Advisor-Modells gibt einen 400-Fehler zurück. Die Obergrenze gilt für jeden Advisor-Aufruf unabhängig und wird nicht über Aufrufe in derselben Anfrage geteilt.

Dies ist nicht nur eine harte Kürzung. Der Server übergibt dem Advisor auch sein verbleibendes Token-Budget, sodass der Advisor seine Antwort passend formt.

Empfohlener Ausgangspunkt: max_tokens: 2048. In Anthropics Tests bei einem schwierigen Reasoning-Benchmark (n = 40 pro Konfiguration) reduzierte dies die mittlere Advisor-Ausgabe um etwa das 7-Fache im Vergleich zum Nicht-Setzen der Obergrenze, mit nahezu null Kürzung und keiner erkennbaren Qualitätsverschlechterung. Der Mindestwert von 1024 reduzierte die Ausgabe um etwa das 10-Fache, kürzte aber etwa 10 Prozent der Aufrufe. Genauigkeitsunterschiede über alle Konfigurationen lagen bei dieser Stichprobengröße innerhalb des Rauschens. Validiere auf deinem eigenen Workload.

Schwierige Reasoning-Aufgaben rufen wesentlich längere Advisor-Ausgaben hervor als die typischen 1.400 bis 1.800 Tokens, die zuvor für leichtere Workloads angegeben wurden. Verwende diese Tabelle, um das Einsparungsverhältnis zu dimensionieren, nicht als universelle Baseline für Advisor-Ausgabe.

Wenn der Advisor die Obergrenze erreicht, trägt der Ergebnisblock stop_reason: "max_tokens". Die API hängt auch [Advisor output truncated at max_tokens=2048.] (mit deiner Obergrenze) an den Ratschlagstext an, sodass der Executor die Kürzung in seinem eigenen Kontext sieht. Verwende stop_reason, um gekürzten Ratschlag zu erkennen und zu entscheiden, ob du die Obergrenze erhöhst oder den Executor mit teilweiser Anleitung fortfahren lässt. 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_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

Prüfe output_tokens beim entsprechenden advisor_message-Eintrag in usage.iterations, um zu sehen, wie nah jeder Aufruf an seine Obergrenze kam.

Im Vergleich zum prompt-basierten Ansatz ist max_tokens eine harte Obergrenze statt einer weichen Anfrage. Verwende max_tokens, wenn du eine garantierte Grenze für Kosten oder Latenz benötigst. Verwende den prompt-basierten Ansatz (oder beide zusammen), wenn du zu Kürze tendieren möchtest, ohne einen Schnitt mitten im Gedanken zu riskieren.



Kombination mit Effort-Einstellungen

Für Coding-Aufgaben erreicht die Kombination eines Sonnet-Executors bei mittlerem Effort mit einem Opus-Advisor eine Intelligenz, die mit Sonnet bei Standard-Effort vergleichbar ist, bei niedrigeren Kosten. Für maximale Intelligenz belasse den Executor bei Standard-Effort.



Kostenkontrolle

• Für Budgets auf Konversationsebene zähle Advisor-Aufrufe clientseitig. Wenn du deine Obergrenze erreichst, entferne das Advisor-Tool aus tools; du musst advisor_tool_result-Blöcke nicht aus deinem Nachrichtenverlauf entfernen (siehe den Hinweis in Multi-Turn-Konversationen).
• Aktiviere caching nur für Konversationen, bei 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 mindestens so leistungsfähig 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 über die Claude API und über Claude Platform on AWS verfügbar. Es ist derzeit nicht auf Amazon Bedrock, Google Cloud oder Microsoft Foundry verfügbar.



Advisor bei Claude Managed Agents

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



Nächste Schritte