Advisor-Tool

Das „advisor tool" (Berater-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 Orientierung 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 agentische Workloads mit langem Horizont (Coding-Agenten, Computer Use, mehrstufige Recherche-Pipelines), bei denen die meisten Turns mechanisch sind, ein exzellenter Plan aber entscheidend ist. Du erreichst nahezu die Qualität des Advisors allein, während der Großteil der Token-Generierung zu den Raten des Executor-Modells erfolgt. Gemessene Ergebnisse, einschließlich der Frage, wie der Nutzen schrumpft, wenn sich die eigene Fähigkeit des Executors der des Advisors annähert, findest du unter Optimierung für Kosten und Intelligenz.



Wann du es verwenden solltest

Der Advisor passt zu diesen 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 Schritt mehr Intelligenz: Füge einen Opus- oder Fable-Advisor hinzu. Rechne mit höheren Kosten als bei Haiku allein, aber niedrigeren als beim Wechsel des Executors zu einem größeren Modell.

Die Ergebnisse sind aufgabenabhängig. Evaluiere mit 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 Kompromiss zwischen Kosten und Qualität wählen, oder Workloads, bei denen jeder Turn tatsächlich die volle Fä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, der die Orientierung des Advisors trägt. Mit claude-opus-5 als Advisor, wie in diesem Schnellstart, ist das content-Feld des Blocks eine advisor_redacted_result-Variante (verschlüsselt; der Executor liest sie serverseitig, dein Client jedoch 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 nebeneinander und welche Advisor-Modelle welche zurückgeben, sowie Modellkompatibilität für die vollständige Liste gültiger Paare.



So funktioniert es

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 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 seiner Eingabe. 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 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 ein Turn, der mitten im Aufruf pausiert und den du mit einer Folgeanfrage fortsetzt (siehe Einen pausierten Turn fortsetzen).

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 außerdem 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 ihre Semantik.



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 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 für beide Formen nebeneinander.

{
  "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 schreibt, 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:

Hier ist dieselbe Anfrage zweimal gesendet, identisch bis auf das Advisor-model in der Tool-Definition, um beide Varianten zu zeigen.

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 tragen ein stop_reason-Feld, wenn du max_tokens in der Tool-Definition setzt, und lassen es weg, wenn du das nicht tust. Es enthält den Stop-Grund des Advisor-Sub-Aufrufs, 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 rendert den Klartext in den Prompt des Executors.

In beiden Fällen gibst du den Content 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 behandeln.



Fehlerergebnisse

Wenn der Advisor-Aufruf fehlschlägt, trägt 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 schöpfen aus demselben modellspezifischen Bucket wie direkte Aufrufe des Advisor-Modells. Ein „rate limit" (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

Gib den vollständigen Assistenten-Content, einschließlich der advisor_tool_result-Blöcke, in nachfolgenden Turns an die API zurück. Gib die Ergebnisblöcke unverändert zurück: Bei einem Claude Opus 5-Advisor ist der content des Ergebnisblocks die verschlüsselte Variante advisor_redacted_result, und der Server entschlüsselt sie und rendert den Ratschlag im nächsten Turn in den Prompt des Executors (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 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 in 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.



Einen pausierten Turn fortsetzen

Eine Antwort kann mit stop_reason: "pause_turn" enden, während ein Advisor-Aufruf noch aussteht. Wenn das geschieht, enthält die Antwort den server_tool_use-Block des Advisors ohne zugehöriges advisor_tool_result. Zum Fortsetzen hängst du diese Assistenten-Nachricht mit unverändertem Content an messages an, behältst den server_tool_use-Block bei und sendest die Anfrage erneut mit demselben Advisor-Tool und Beta-Header. Du musst keine User-Nachricht und keinen 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 in der Fortsetzungsanfrage gibt einen 400 invalid_request_error zurück, weil der ausstehende server_tool_use-Block keine Tool-Definition hat, gegen die er laufen kann; füge das Tool immer ein, 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 läuft zu Beginn dieser nächsten Anfrage. Siehe Server-Tools und Client-Tools in einem Turn mischen.



Anstoß mitten in der Konversation für zu selten aufrufende Executors

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 Erfolgsquoten bei Aufgaben auf Haiku-Executors um etwa 7 Prozentpunkte. Auf Sonnet-Executors hatte der Klartext-Anstoß in Anthropics Tests keinen messbaren Effekt. Die folgenden Überlegungen zum Aufruf-Timing sind besonders für Sonnet relevant. Wende den Anstoß nicht auf Opus-Executors an: Auf Opus senkte er die Erfolgsquoten leicht.

Mit dem Standardwert NUDGE_TURN von 2 trifft die Erinnerung typischerweise ein, nachdem sich das Modell mit der Aufgabe vertraut gemacht 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 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 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 Anstoß als eigene User-Nachricht nach den Tool-Ergebnissen an, statt als Geschwisterblock in derselben Nachricht. Aufeinanderfolgende User-Nachrichten sind gültig. In Anthropics Tests auf Haiku- und Sonnet-Executors verhielten sie sich äquivalent zu einem Geschwisterblock. Die Form als separate Nachricht hält die Erinnerung außerdem klar von der Tool-Ausgabe getrennt.

Abwägungen: Der Anstoß 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 sind, bevor der Anstoß ausgelöst wird, oder knüpfe den Anstoß an ein Signal für Aufgabenkomplexität, das du bereits berechnest. Wenn dein System-Prompt bereits zurückhaltende Formulierungen enthält („reserviere den Advisor für echte Unsicherheit"), lass den Anstoß ganz weg, da die beiden Anweisungen in Konflikt stehen.

Der Klartext-Anstoß ist auf Haiku- und Sonnet-Executors sehr auffällig: 74 Prozent (Sonnet) bis 98 Prozent (Haiku) der angestoßenen Versuche in Anthropics Tests riefen den Advisor sofort in 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 Anstoß hinzufügst. Wenn der Executor den Advisor bereits zuverlässig aufruft und sein erster Aufruf typischerweise in Turn N landet, setze NUDGE_TURN größer als N. In Anthropics Tests korrelierte ein Turn-2-Anstoß bei Workloads, deren Baseline-Erstaufruf in Turn 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 Anstoß das Engagement ohne Kosten für die Aufgabenleistung.

Um bei einer bestimmten Anfrage eine Konsultation zu erzwingen statt anzustoßen, setze tool_choice auf {"type": "tool", "name": "advisor"}, vorbehaltlich der Einschränkungen in Tool-Nutzung erzwingen. Erzwungene 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 Denken unterstützt erzwungene Tool-Nutzung.



Streaming

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

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 ruhig, abgesehen von standardmäßigen SSE-ping-Keepalives, die etwa alle 30 Sekunden gesendet werden. Kurze Advisor-Aufrufe zeigen möglicherweise keine Pings.

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

Es folgt ein message_delta-Event 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 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 spiegeln nur Executor-Token wider. Advisor-Token werden nicht in die Gesamtsummen auf oberster Ebene 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 usage-Feld auf oberster Ebene ist die Summe dieses Feldes ü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 Eingaben späterer Iterationen die Ausgabe 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, wenn du Logik zur Kostenverfolgung baust.

Die Advisor-Ausgabe beträgt typischerweise 400 bis 700 Text-Token oder 1.400 bis 1.800 Token insgesamt einschließlich Thinking. Die Kostenersparnis entsteht dadurch, dass der Advisor nicht deine vollständige endgültige 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 schöpfen auch nicht aus einem Task-Budget, das auf den Executor angewendet wird.

Priority Tier gilt für jedes Modell unabhängig. Eine Priority-Tier-Zusage für das Executor-Modell erstreckt sich nicht auf den Advisor. Advisor-Aufrufe laufen nur dann im Priority Tier, wenn deine Organisation auch eine Zusage 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 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" (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: Der Cache-Schreibvorgang kostet mehr, als die Lesevorgänge sparen, wenn der Advisor zweimal oder seltener pro Konversation aufgerufen wird. Caching erreicht die Gewinnschwelle bei etwa drei Advisor-Aufrufen und verbessert sich von da an. 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 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, nach 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 anstößt, es nahe dem Beginn komplexer Aufgaben und bei Schwierigkeiten aufzurufen. Für Recherche-Aufgaben ist typischerweise kein zusätzliches Prompting nötig.

Bei Coding- und Agenten-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:

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 Einfließ-Satz hinzu, der auf die Planer-Tools verweist, die dein Agent bereitstellt.



Vorgeschlagener System-Prompt für Coding-Aufgaben

Ohne Steuerung durch den System-Prompt neigt der Executor in manchen Domänen dazu, den Advisor 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-Orientierung:

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-Orientierung konservativ an. Das hält seine Aufrufrate bei Recherche- und Lookup-Workloads angemessen niedrig, gibt aber bei Coding-Workloads Qualität auf, wo sich eine frühe Advisor-Konsultation zuverlässig auszahlt. Auf einem internen Coding-Benchmark erhöhte eine nahe Variante des folgenden Blocks (die Read-only-Ausnahme in der Hard rule wurde nach der Messung hinzugefügt) die Haiku-Erfolgsquoten 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: Auf einem internen Browse-Comprehension-Benchmark (n = 1.266) kostete eine nahe Variante dieses Blocks etwa 4 Prozentpunkte Genauigkeit gegenüber dem eingebauten Standard. Wenn dein Workload Coding mit erheblichem Lookup oder Retrieval mischt, bleibe bei den vorgeschlagenen Blöcken oder knüpfe den Austausch an ein Workload-Typ-Signal, das du bereits berechnest.



Advisor-Aufrufe auf Opus-Executors erhöhen

Opus-Executors rufen den Advisor typischerweise ohne zusätzliches Prompting in angemessener 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 rule wurde nach der Messung hinzugefügt) die Erfolgsquoten bei zu selten aufrufenden Aufgaben 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.



Länge der Advisor-Ausgabe kürzen

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 User-Nachrichten als zitierten Kontext über die Aufgabe des Executors, sodass Anweisungen, die den Advisor direkt ansprechen, deutlich 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 Agenten-Framework programmatisch vorangestellt werden, bevor die Anfrage gesendet wird. Das Limit ist eine weiche Einschränkung. Der Advisor überschreitet es gelegentlich, also bitte um etwa 80 Prozent deiner tatsächlichen Obergrenze.

Kombiniere diesen Ansatz mit der Timing-Orientierung in Vorgeschlagener System-Prompt für Coding-Aufgaben (oder dem alternativen Haiku-Block, falls du ihn eingesetzt hast) für den stärksten Kompromiss zwischen Kosten und Qualität. Für eine harte Obergrenze statt einer weichen Bitte siehe Advisor-Ausgabe begrenzen.



Advisor-Ausgabe begrenzen

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

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

Der Mindestwert ist 1024. Das Setzen von max_tokens über die eigene Ausgabe-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 hinweg geteilt.

Dies ist nicht allein eine harte Abschneidung. 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 gegenüber einer nicht gesetzten Obergrenze, bei nahezu null Abschneidungen und keiner erkennbaren Qualitätsverschlechterung. Der Mindestwert von 1024 reduzierte die Ausgabe um etwa das 10-Fache, schnitt aber rund 10 Prozent der Aufrufe ab. Die Genauigkeitsunterschiede über alle Konfigurationen lagen bei dieser Stichprobengröße im Rauschen. Validiere mit deinem eigenen Workload.

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

Wenn der Advisor die Obergrenze tatsächlich erreicht, trägt der Ergebnisblock stop_reason: "max_tokens" bei beiden Ergebnisvarianten, unabhängig davon, welches Advisor-Modell du verwendest. Verwende stop_reason, um abgeschnittenen Ratschlag zu erkennen und zu entscheiden, ob du die Obergrenze erhöhst oder den Executor mit teilweiser Orientierung fortfahren lässt. Die API hängt außerdem [Advisor output truncated at max_tokens=2048.] (mit deiner Obergrenze) an den Ratschlagstext an, sodass der Executor die Abschneidung in seinem eigenen Kontext sieht; bei einem Klartext-advisor_result-Advisor ist dieser Marker auch für deinen Client sichtbar. 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"
  }
}

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

Im Vergleich zum promptbasierten Ansatz ist max_tokens eine harte Obergrenze statt einer weichen Bitte. Verwende max_tokens, wenn du eine garantierte Grenze für Kosten oder Latenz brauchst. Verwende den promptbasierten Ansatz (oder beide zusammen), wenn du zur 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 mit mittlerem Effort und einem Opus-Advisor eine Intelligenz, die mit Sonnet bei Standard-Effort vergleichbar ist, zu 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 keine advisor_tool_result-Blöcke aus deinem Nachrichtenverlauf entfernen (siehe den Hinweis in 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 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 auf AWS verfügbar. Es ist derzeit nicht auf Amazon Bedrock, Google Cloud oder Microsoft Foundry verfügbar.



Advisor auf Claude Managed Agents

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



Nächste Schritte