Advisor-Tool

Das Advisor-Tool ermöglicht es einem schnelleren, kostengünstigeren „executor model" (Executor-Modell), mitten in der Generierung ein intelligenteres „advisor model" (Advisor-Modell) für strategische Anleitung zu konsultieren. 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 langfristige agentische Workloads (Coding-Agenten, Computernutzung, mehrstufige Recherche-Pipelines), bei denen die meisten Schritte mechanisch sind, ein exzellenter Plan aber entscheidend ist. Du erreichst nahezu die Qualität eines reinen Advisor-Einsatzes, während der Großteil der Token-Generierung zu den Raten des Executor-Modells erfolgt.



Wann du es verwenden solltest

Der Advisor passt zu diesen Konfigurationen:

• Du verwendest derzeit Sonnet für komplexe Aufgaben: Füge Opus als Advisor hinzu, um eine Qualitätssteigerung bei ähnlichen oder niedrigeren Gesamtkosten zu erzielen.
• Du verwendest derzeit Haiku und möchtest einen Intelligenzsprung: Füge Opus als 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 anhand deines eigenen Workloads.

Der Advisor ist weniger geeignet für Einzelrunden-Q&A (nichts zu planen), reine Pass-Through-Modellauswahlen, bei denen deine Nutzer bereits ihren eigenen Kompromiss zwischen Kosten und Qualität wählen, oder Workloads, bei denen jeder Schritt tatsächlich die volle Leistungsfähigkeit des Advisor-Modells erfordert.



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 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 in der Beta auf der Claude API und auf der Claude Platform on AWS verfügbar. Es ist derzeit nicht auf Amazon Bedrock, Google Cloud oder Microsoft Foundry verfügbar.



Schnellstart

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    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.",
        }
    ],
)

print(response)



Funktionsweise

Wenn du das Advisor-Tool zu deinem tools-Array hinzufügst, entscheidet das Executor-Modell wie bei jedem anderen Tool, wann es aufgerufen wird. 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 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 und erhält das vollständige Transkript des Executors als zitierten Kontext in seiner Eingabe. Dieses Transkript umfasst deinen System-Prompt, die Tool-Definitionen, die vorherigen Runden und Tool-Ergebnisse sowie den Text, den der Executor in dieser Runde bisher erzeugt hat.
3. Die Antwort des Advisors kehrt als advisor_tool_result-Block zum Executor zurück.
4. Der Executor generiert weiter, informiert durch den Ratschlag.

All dies geschieht innerhalb einer einzigen /v1/messages-Anfrage, ohne zusätzliche Roundtrips auf deiner Seite. Die Ausnahme ist eine Runde, die mitten im Aufruf pausiert und die du mit einer Folgeanfrage fortsetzt (siehe Fortsetzen einer pausierten Runde).

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 auf Content-Blöcken ist dies kein Breakpoint-Marker. Es ist ein Ein/Aus-Schalter. Der Server bestimmt, wo die 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 strukturierten 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 Inhalt des Assistenten:

{
  "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 einträgt, 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 Fable 5- und Claude Mythos 5-Advisor 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-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 menschenlesbare Ratschläge. Bei advisor_redacted_result enthält das Feld encrypted_content einen undurchsichtigen Blob, den du nicht lesen kannst. In der nächsten Runde entschlüsselt der Server ihn und rendert den Klartext in den Prompt des Executors.

In beiden Fällen gib den Inhalt in nachfolgenden Runden wortgetreu zurück. Wenn du das Advisor-Modell mitten in der Konversation wechselst, verzweige anhand von 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 weitere Ratschläge fort. Die Anfrage selbst schlägt nicht fehl.

Advisor-Ratenlimits stammen aus demselben Pro-Modell-Kontingent wie direkte Aufrufe des Advisor-Modells. 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.



Mehrrunden-Konversationen

Übergib den vollständigen Assistenten-Inhalt, einschließlich der advisor_tool_result-Blöcke, in nachfolgenden Runden zurück an die API:

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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Füge 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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Wenn du das Advisor-Tool in einer Folgerunde aus tools weglässt, während der Nachrichtenverlauf noch advisor_tool_result-Blöcke enthält, gibt die API einen 400 invalid_request_error zurück.



Fortsetzen einer pausierten Runde

Eine Antwort kann mit stop_reason: "pause_turn" enden, während ein Advisor-Aufruf noch aussteht. Wenn das passiert, enthält die Antwort den server_tool_use-Block des Advisors ohne zugehöriges advisor_tool_result. Um fortzusetzen, hänge diese Assistenten-Nachricht mit unverändertem Inhalt 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 Benutzernachricht oder einen tool_result-Block hinzufügen. Die API führt den ausstehenden Advisor-Aufruf aus und setzt die Runde des Executors in der neuen Antwort fort. Eine fortgesetzte Runde 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. Wenn der Executor stattdessen in derselben Runde 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 läuft zu Beginn dieser nächsten Anfrage. Siehe Mischen von Server-Tools und Client-Tools in einer Runde.



Nudge mitten in der Konversation für Executoren, die zu selten aufrufen

Wenn ein Haiku-Executor den Advisor in seiner ersten Assistenten-Runde nicht aufgerufen hat, hänge vor der zweiten Assistenten-Runde eine kurze Erinnerung als zusätzliche Benutzernachricht an. In Anthropics interner Verhaltensevaluierung erhöhte dies die Erfolgsraten bei Aufgaben auf Haiku-Executoren um etwa 7 Prozentpunkte. Auf Sonnet-Executoren hatte der Klartext-Nudge in Anthropics Tests keinen messbaren Effekt. Die folgenden Überlegungen zum Aufrufzeitpunkt sind besonders für Sonnet relevant. Wende den Nudge nicht auf Opus-Executoren an: Auf Opus senkte er die Erfolgsraten leicht.

Mit dem Standardwert 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-4-8"},
    # ... 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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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 das Modell bereits anweist, sparsam aufzurufen.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

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

Kompromisse: Der Nudge erhöht die Aufrufrate, was trivial einfache Aufgaben in eine unnötige Konsultation treiben kann. Wenn dein Workload einfache und komplexe Aufgaben mischt, erwäge, NUDGE_TURN auf 3 zu erhöhen, damit Zwei-Runden-Aufgaben abgeschlossen werden, bevor der Nudge auslöst, oder steuere den Nudge über ein Aufgabenkomplexitätssignal, das du bereits berechnest. Wenn dein System-Prompt bereits zurückhaltende Formulierungen enthält („reserviere den Advisor für echte Unsicherheit"), lass den Nudge ganz weg, weil die beiden Anweisungen in Konflikt stehen.

Der Klartext-Nudge ist auf Haiku- und Sonnet-Executoren hochgradig salient: 74 Prozent (Sonnet) bis 98 Prozent (Haiku) der genudgten Versuche in Anthropics Tests riefen den Advisor sofort in Runde 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 die Baseline-Runde 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 in Runde N erfolgt, setze NUDGE_TURN größer als N. In Anthropics Tests korrelierte ein Runde-2-Nudge bei Workloads, bei denen der Baseline-Erstaufruf in Runde 7 oder später lag, mit einem Rückgang der Aufgabenleistung 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 für die Aufgabenleistung.

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 Erzwingen von Tool-Nutzung. Das Erzwingen von Tool-Nutzung kann nicht mit erweitertem Denken kombiniert werden: Die API gibt einen 400 invalid_request_error zurück, wenn du beides aktivierst.



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-Zahlen 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": 412,
    "cache_read_input_tokens": 0,
    "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-4-8",
        "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 spiegeln nur Executor-Token wider. Advisor-Token werden nicht in die Gesamtsummen auf oberster Ebene eingerechnet, weil 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.

Die Aggregationsregeln unterscheiden sich je nach Feld. output_tokens auf oberster Ebene ist die Summe aller Executor-Iterationen. input_tokens und cache_read_input_tokens auf oberster Ebene spiegeln nur die erste Executor-Iteration wider. Die Eingaben nachfolgender Executor-Iterationen werden nicht erneut summiert, weil sie vorherige Ausgabe-Token enthalten. Verwende usage.iterations für eine vollständige Aufschlüsselung pro Iteration, wenn du Kostenverfolgungslogik baust.

Die Advisor-Ausgabe umfasst typischerweise 400 bis 700 Text-Token oder insgesamt 1.400 bis 1.800 Token einschließlich Thinking. Die Kosteneinsparungen entstehen dadurch, dass der Advisor nicht deine vollständige finale Ausgabe generiert. Das erledigt der Executor zu seiner niedrigeren Rate.

Das max_tokens auf oberster Ebene gilt nur für die Executor-Ausgabe. Es begrenzt nicht die Token der Advisor-Sub-Inferenz. Um die Advisor-Ausgabe direkt zu begrenzen, setze max_tokens in der Tool-Definition. Die Token des Advisors werden auch nicht von einem auf den Executor angewendeten Task-Budget abgezogen.

Priority Tier gilt für jedes Modell unabhängig. Eine Priority-Tier-Verpflichtung für das Executor-Modell erstreckt sich nicht auf den Advisor. Advisor-Aufrufe laufen nur dann im Priority Tier, wenn deine Organisation auch eine Verpflichtung 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 in einer nachfolgenden Runde 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-4-8",
        "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 Schreiben des Caches kostet mehr, als die Lesevorgänge einsparen, wenn der Advisor zwei- oder weniger Mal pro Konversation aufgerufen wird. Caching erreicht die Gewinnschwelle bei etwa drei Advisor-Aufrufen und verbessert sich von dort aus. Aktiviere es für lange Agenten-Schleifen 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 zum selben tools-Array hinzu:

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

Der Executor kann in derselben Runde 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 Agenten-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 Agenten-Aufgaben erzeugt der Advisor höhere Intelligenz bei ähnlichen Kosten, wenn er die Gesamtzahl der Tool-Aufrufe und die Konversationslänge reduziert. Zwei Zeitpunkte treiben diese Verbesserung:

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

Wenn dein Agent andere planerähnliche Tools bereitstellt (zum Beispiel ein Todo-Listen-Tool), weise das Modell an, 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 Steuerung über den System-Prompt neigt der Executor dazu, den Advisor in einigen Domänen zu selten aufzurufen, insbesondere bei Coding-Aufgaben. Für Coding-Aufgaben, bei denen du ein 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 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 wendet die Standard-Advisor-Anleitung konservativ an. Das hält seine Aufrufrate bei Recherche- und Lookup-Workloads angemessen niedrig, gibt aber Qualität bei Coding-Workloads auf, wo sich eine frühe Advisor-Konsultation zuverlässig auszahlt. In 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-Erfolgsraten um etwa 7,5 Prozentpunkte gegenüber dem eingebauten Standard.

Verwende diesen Block anstelle der früheren Timing- und Ratschlag-Blö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: In 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 steuere den Austausch über ein Workload-Typ-Signal, das du bereits berechnest.



Erhöhen der Advisor-Aufrufe bei Opus-Executoren

Opus-Executoren 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 Erfolgsraten 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 häufig aufrief. Der Nettoeffekt war bei einem gemischten Workload ungefähr 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 max_tokens auf oberster Ebene begrenzt sie nicht. Der Advisor sieht sowohl deinen System-Prompt als auch deine Benutzernachrichten 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 Benutzernachricht:

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

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

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 Kompromiss zwischen Kosten und Qualität. Für eine harte Obergrenze statt einer weichen Anforderung 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 das eigene Ausgabelimit des Advisor-Modells hinaus gibt einen 400-Fehler zurück. Die Obergrenze gilt für jeden Advisor-Aufruf unabhängig und wird nicht über Aufrufe in derselben Anfrage hinweg 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 gestaltet.

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

Schwierige Reasoning-Aufgaben erzeugen deutlich längere Advisor-Ausgaben als die typischen 1.400 bis 1.800 Token, die zuvor für leichtere Workloads genannt wurden. Verwende diese Tabelle, um das Einsparungsverhältnis abzuschätzen, nicht als universelle Baseline für Advisor-Ausgaben.

Wenn der Advisor die Obergrenze erreicht, enthält der Ergebnisblock stop_reason: "max_tokens". Die API hängt außerdem [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ürzte Ratschläge 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 im 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 Anforderung. 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 Abbruch mitten im Gedanken zu riskieren.



Kombination mit Effort-Einstellungen

Für Coding-Aufgaben erreicht die Kombination eines Sonnet-Executors mit mittlerem Effort und 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 und entferne alle advisor_tool_result-Blöcke aus deinem Nachrichtenverlauf, um einen 400 invalid_request_error zu vermeiden (siehe den Hinweis in Mehrrunden-Konversationen).
• Aktiviere caching nur für Konversationen, bei denen du drei oder mehr Advisor-Aufrufe erwartest.



Nächste Schritte