Advisor-Tool

Das Advisor-Tool ermöglicht es einem schnelleren, kostengünstigeren Executor-Modell, während der Generierung ein intelligenteres Advisor-Modell zu konsultieren, um strategische Anleitung zu erhalten. Der Advisor liest die vollständige Konversation, erstellt einen Plan oder eine Kurskorrektur (typischerweise 400 bis 700 Text-Token, 1.400 bis 1.800 Token insgesamt einschließlich Thinking) und der Executor setzt die Aufgabe fort.

Dieses Muster passt zu langfristigen agentengesteuerten Workloads (Coding-Agenten, Computer-Nutzung, mehrstufige Forschungs-Pipelines), bei denen die meisten Durchläufe mechanisch sind, aber ein ausgezeichneter Plan entscheidend ist. Sie erhalten eine Qualität nahe der des reinen Advisors, während die meiste Token-Generierung mit den Raten des Executor-Modells erfolgt.

Wann sollte man es verwenden

Frühe Benchmarks zeigen bedeutende Verbesserungen für diese Konfigurationen:

• Sie verwenden derzeit Sonnet für komplexe Aufgaben: Fügen Sie Opus als Advisor hinzu, um eine Qualitätsverbesserung bei ähnlichen oder niedrigeren Gesamtkosten zu erhalten.
• Sie verwenden derzeit Haiku und möchten eine Steigerung der Intelligenz: Fügen Sie Opus als Advisor hinzu. Erwarten Sie höhere Kosten als nur Haiku, aber niedriger als ein Wechsel des Executors zu einem größeren Modell.

Die Ergebnisse sind aufgabenabhängig. Evaluieren Sie auf Ihrer eigenen Workload.

Der Advisor ist eine schwächere Lösung für Single-Turn-Q&A (nichts zu planen), reine Pass-Through-Modell-Picker, bei denen Ihre Benutzer bereits ihren eigenen Kosten- und Qualitäts-Tradeoff wählen, oder Workloads, bei denen jeder Durchlauf wirklich die volle Leistung des Advisor-Modells erfordert.

Modellkompatibilität

Das Executor-Modell (das Top-Level-Feld model) und das Advisor-Modell (das Feld model innerhalb der Tool-Definition) müssen ein gültiges Paar bilden. Der Advisor muss mindestens so leistungsfähig sein wie der Executor.

Wenn Sie ein ungültiges Paar anfordern, 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-Phase auf der Claude API (Anthropic) verfügbar.

Schnellstart

Wie es funktioniert

Wenn Sie das Advisor-Tool zu Ihrem tools-Array hinzufügen, entscheidet das Executor-Modell, wann es aufgerufen wird, genau wie jedes andere Tool. Wenn der Executor den Advisor aufruft:

1. Der Executor gibt einen server_tool_use-Block mit name: "advisor" und einer leeren input aus. Der Executor signalisiert das Timing; der Server liefert den Kontext.
2. Anthropic führt einen separaten Inferenz-Durchlauf auf dem Advisor-Modell-Server durch und übergibt das vollständige Transkript des Executors. Der Advisor sieht die System-Eingabeaufforderung, alle Tool-Definitionen, alle vorherigen Durchläufe und alle vorherigen Tool-Ergebnisse.
3. Die Antwort des Advisors wird an den Executor als advisor_tool_result-Block zurückgegeben.
4. Der Executor setzt die Generierung fort, informiert durch die Beratung.

All dies geschieht innerhalb einer einzelnen /v1/messages-Anfrage. Keine zusätzlichen Roundtrips auf Ihrer Seite.

Der Advisor selbst läuft ohne Tools und ohne Kontextverwaltung. Seine Thinking-Blöcke werden vor der Rückgabe des Ergebnisses gelöscht; nur der Beratungstext erreicht den Executor.

Tool-Parameter

Das caching-Objekt hat die Form {"type": "ephemeral", "ttl": "5m" | "1h"}. Im Gegensatz zu cache_control auf Content-Blöcken ist dies kein Breakpoint-Marker; es ist ein Ein-/Ausschalter. Der Server entscheidet, wo Cache-Grenzen liegen.

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..."
    }
  ]
}

Die server_tool_use.input ist immer leer. Der Server konstruiert die Ansicht des Advisors aus dem vollständigen Transkript automatisch; nichts, was der Executor in input einfügt, erreicht den Advisor.

Ergebnisvarianten

Das Feld advisor_tool_result.content ist eine diskriminierte Union. Welche Variante Sie erhalten, hängt vom Advisor-Modell ab:

Mit advisor_result enthält das Feld text menschenlesbare Beratung. Mit advisor_redacted_result enthält das Feld encrypted_content einen undurchsichtigen Blob, den Sie nicht lesen können; beim nächsten Durchlauf entschlüsselt der Server ihn und rendert den Klartext in die Eingabeaufforderung des Executors.

In beiden Fällen geben Sie den Inhalt bei nachfolgenden Durchläufen wörtlich zurück. Wenn Sie Advisor-Modelle mid-Konversation wechseln, verzweigen Sie auf content.type, um beide Formen zu handhaben.

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 setzt fort, ohne weitere Beratung. Die Anfrage selbst schlägt nicht fehl.

Advisor-Ratenlimits stammen aus demselben Pro-Modell-Bucket wie direkte Aufrufe des Advisor-Modells. Ein Ratenlimit auf dem Advisor erscheint als too_many_requests innerhalb des Tool-Ergebnisses; ein Ratenlimit auf dem Executor schlägt die gesamte Anfrage mit HTTP 429 fehl.

Multi-Turn-Konversationen

Übergeben Sie den vollständigen Assistent-Inhalt, einschließlich advisor_tool_result-Blöcke, bei nachfolgenden Durchläufen an die API:

import anthropic

client = anthropic.Anthropic()

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

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,
)

# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
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 Sie das Advisor-Tool bei einem nachfolgenden Durchlauf aus tools weglassen, während die Nachrichtenhistorie immer noch advisor_tool_result-Blöcke enthält, gibt die API einen 400 invalid_request_error zurück.

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 einzelnen 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 ruhig, außer für Standard-SSE-ping-Keepalives, die ungefähr alle 30 Sekunden ausgegeben werden; kurze Advisor-Aufrufe zeigen möglicherweise keine Pings.

Wenn der Advisor fertig ist, kommt der advisor_tool_result vollständig in einem einzelnen content_block_start-Event an (keine Deltas). Die Executor-Ausgabe wird dann wieder gestreamt.

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 Array usage.iterations[] 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-7",
        "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-Token wider. Advisor-Token werden nicht in die Top-Level-Summen eingerechnet, da sie zu einem anderen Satz abgerechnet werden. Iterationen mit type: "advisor_message" werden zu den Raten des Advisor-Modells abgerechnet; Iterationen mit type: "message" werden zu den Raten des Executor-Modells abgerechnet.

Die Aggregationsregeln unterscheiden sich je nach Feld. Top-Level-output_tokens ist die Summe aller Executor-Iterationen. Top-Level-input_tokens und cache_read_input_tokens spiegeln nur die erste Executor-Iteration wider; nachfolgende Executor-Iterationen' Eingaben werden nicht neu summiert, da sie vorherige Output-Token enthalten. Verwenden Sie usage.iterations für eine vollständige Pro-Iterations-Aufschlüsselung beim Erstellen von Kostenverfolgungs-Logik.

Die Advisor-Ausgabe beträgt typischerweise 400 bis 700 Text-Token oder 1.400 bis 1.800 Token insgesamt einschließlich Thinking. Die Kosteneinsparungen kommen daher, dass der Advisor nicht Ihre vollständige endgültige Ausgabe generiert; der Executor macht das zu seiner niedrigeren Rate.

Das Top-Level-max_tokens gilt nur für die Executor-Ausgabe. Es begrenzt nicht die Advisor-Sub-Inferenz-Token. Die Token des Advisors werden auch nicht aus einem auf den Executor angewendeten Task-Budget gezogen.

Advisor-Prompt-Caching

Es gibt zwei unabhängige Caching-Schichten.

Executor-seitiges Caching

Der advisor_tool_result-Block ist wie jeder andere Content-Block cachebar. Ein cache_control-Breakpoint, der bei einem nachfolgenden Durchlauf danach platziert wird, wird treffen. Die Eingabeaufforderung des Executors enthält immer den Klartext-Rat, unabhängig davon, ob Ihr Client text oder encrypted_content erhalten hat, daher ist das Caching-Verhalten für beide Ergebnisvarianten identisch.

Advisor-seitiges Caching

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

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

Die Eingabeaufforderung des Advisors beim N-ten Aufruf ist die Eingabeaufforderung des (N-1)-ten Aufrufs mit einem weiteren Segment angehängt, daher ist das Präfix über Aufrufe hinweg stabil. Mit aktiviertem caching schreibt jeder Advisor-Aufruf einen Cache-Eintrag; der nächste Aufruf liest bis zu diesem Punkt und zahlt nur für das Delta. Sie sehen cache_read_input_tokens bei der zweiten und späteren advisor_message-Iterationen ungleich Null werden.

Wann sollte man es aktivieren: Der Cache-Schreibaufwand ist größer als die Leseeinsparungen, wenn der Advisor zwei oder weniger Mal pro Konversation aufgerufen wird. Caching amortisiert sich bei ungefähr drei Advisor-Aufrufen und verbessert sich von dort an. Aktivieren Sie es für lange Agent-Schleifen; halten Sie es aus für kurze Aufgaben.

Halten Sie es konsistent: Setzen Sie caching einmal und lassen Sie es für die ganze Konversation. Das Umschalten aus und ein mid-Konversation verursacht Cache-Misses.

Kombination mit anderen Tools

Das Advisor-Tool setzt sich mit anderen Server-seitigen und Client-seitigen Tools zusammen. Fügen Sie 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-7",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Der Executor kann das Web durchsuchen, den Advisor aufrufen und Ihre benutzerdefinierten Tools im selben Durchlauf verwenden. Der Plan des Advisors kann informieren, welche Tools der Executor als nächstes erreicht.

Best Practices

Prompting für Coding- und Agent-Aufgaben

Das Advisor-Tool wird mit einer integrierten Beschreibung ausgeliefert, die den Executor dazu drängt, es nahe am Anfang komplexer Aufgaben und bei Schwierigkeiten aufzurufen. Für Forschungsaufgaben ist normalerweise keine zusätzliche Eingabeaufforderung erforderlich.

Bei Coding- und Agent-Aufgaben erzeugt 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 ein paar explorative Lesevorgänge im Transkript sind.
2. Für schwierige Aufgaben ein letzter Advisor-Aufruf nach Dateischreibvorgängen und Test-Ausgaben im Transkript.

Wenn Ihr Agent andere Planer-ähnliche Tools verfügbar macht (z. B. ein Todo-Listen-Tool), fordern Sie das Modell auf, den Advisor vor diesen Tools aufzurufen, damit der Plan des Advisors in sie fließt. Die vorgeschlagene System-Eingabeaufforderung unten verstärkt das Early-Call-Muster; fügen Sie Ihren eigenen Funneling-Satz hinzu, der auf die Planner-Tools verweist, die Ihr Agent verfügbar macht.

Vorgeschlagene System-Eingabeaufforderung für Coding-Aufgaben

Für Coding-Aufgaben, bei denen Sie konsistentes Advisor-Timing und etwa zwei bis drei Aufrufe pro Aufgabe möchten, stellen Sie die folgenden Blöcke Ihrer Executor-System-Eingabeaufforderung voran, bevor andere Sätze, die den Advisor erwähnen. Bei internen Coding-Evaluierungen erzeugte dieses Muster die höchste Intelligenz bei nahezu Sonnet-Kosten.

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 die Beratung 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.

Trimmen der Advisor-Ausgabelänge

Die Advisor-Ausgabe ist der größte Kostentreiber des Advisors. Um diese Kosten zu reduzieren, stellen Sie eine einzelne Prägnanz-Anweisung der System-Eingabeaufforderung voran, bevor ein anderer Satz, der den Advisor erwähnt. Bei internen Tests reduzierte die folgende Zeile die gesamten Advisor-Output-Token um ungefähr 35 bis 45 Prozent, ohne die Aufruffrequenz zu ändern:

The advisor should respond in under 100 words and use enumerated steps, not explanations.

Koppeln Sie dies mit dem Timing-Block oben für den stärksten Kosten-gegen-Qualitäts-Tradeoff.

Pairing mit Effort-Einstellungen

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

Kostenkontrolle

• Für Konversations-Budgets zählen Sie Advisor-Aufrufe client-seitig. Wenn Sie Ihre Obergrenze erreichen, entfernen Sie das Advisor-Tool aus tools und entfernen Sie alle advisor_tool_result-Blöcke aus Ihrer Nachrichtenhistorie, um einen 400 invalid_request_error zu vermeiden.
• Aktivieren Sie caching nur für Konversationen, bei denen Sie drei oder mehr Advisor-Aufrufe erwarten.

Einschränkungen

• Advisor-Ausgabe streamt nicht. Erwarten Sie eine Pause im Stream, während die Sub-Inferenz läuft.
• Keine integrierte Konversations-Obergrenze für Advisor-Aufrufe. Verfolgen und begrenzen Sie sie client-seitig.
• max_tokens gilt nur für die Executor-Ausgabe. Es begrenzt nicht die Advisor-Token.
• Anthropic Priority Tier wird pro Modell berücksichtigt. Priority Tier auf dem Executor-Modell erstreckt sich nicht auf den Advisor; Sie benötigen Priority Tier speziell auf dem Advisor-Modell.