Outil Advisor

L'outil advisor permet à un modèle exécuteur plus rapide et moins coûteux de consulter un modèle advisor plus intelligent en cours de génération pour obtenir des conseils stratégiques. L'advisor lit la conversation complète, produit un plan ou une correction de trajectoire (généralement 400 à 700 jetons de texte, 1 400 à 1 800 jetons au total incluant la réflexion), et l'exécuteur continue avec la tâche.

Ce modèle convient aux charges de travail agentiques à long horizon (agents de codage, utilisation d'ordinateur, pipelines de recherche multi-étapes) où la plupart des tours sont mécaniques mais avoir un excellent plan est crucial. Vous obtenez une qualité proche de celle du seul advisor tandis que la majorité de la génération de jetons se fait aux tarifs du modèle exécuteur.

Quand l'utiliser

Les premiers benchmarks montrent des gains significatifs pour ces configurations :

• Vous utilisez actuellement Sonnet pour les tâches complexes : Ajoutez Opus comme advisor pour une amélioration de qualité à un coût similaire ou inférieur.
• Vous utilisez actuellement Haiku et voulez une amélioration de l'intelligence : Ajoutez Opus comme advisor. Attendez-vous à un coût plus élevé que Haiku seul, mais inférieur à passer l'exécuteur à un modèle plus grand.

Les résultats dépendent de la tâche. Évaluez sur votre propre charge de travail.

L'advisor est un ajustement plus faible pour les Q&A à tour unique (rien à planifier), les sélecteurs de modèles purs qui passent simplement où vos utilisateurs choisissent déjà leur propre compromis coût-qualité, ou les charges de travail où chaque tour nécessite réellement la capacité complète du modèle advisor.

Compatibilité des modèles

Le modèle exécuteur (le champ model de niveau supérieur) et le modèle advisor (le champ model à l'intérieur de la définition de l'outil) doivent former une paire valide. L'advisor doit être au moins aussi capable que l'exécuteur.

Si vous demandez une paire invalide, l'API retourne une 400 invalid_request_error nommant la combinaison non supportée.

Disponibilité de la plateforme

L'outil advisor est disponible en bêta sur Claude API (Anthropic).

Démarrage rapide

Comment ça fonctionne

Lorsque vous ajoutez l'outil advisor à votre tableau tools, le modèle exécuteur décide quand l'appeler, comme n'importe quel autre outil. Lorsque l'exécuteur invoque l'advisor :

1. L'exécuteur émet un bloc server_tool_use avec name: "advisor" et une input vide. L'exécuteur signale le timing ; le serveur fournit le contexte.
2. Anthropic exécute une passe d'inférence séparée sur le serveur du modèle advisor, en passant la transcription complète de l'exécuteur. L'advisor voit l'invite système, toutes les définitions d'outils, tous les tours précédents et tous les résultats d'outils précédents.
3. La réponse de l'advisor revient à l'exécuteur sous la forme d'un bloc advisor_tool_result.
4. L'exécuteur continue à générer, informé par les conseils.

Tout cela se passe dans une seule requête /v1/messages. Pas de trajets supplémentaires de votre côté.

L'advisor lui-même s'exécute sans outils et sans gestion du contexte. Ses blocs de réflexion sont supprimés avant que le résultat ne soit retourné ; seul le texte des conseils atteint l'exécuteur.

Paramètres de l'outil

L'objet caching a la forme {"type": "ephemeral", "ttl": "5m" | "1h"}. Contrairement à cache_control sur les blocs de contenu, ce n'est pas un marqueur de point d'arrêt ; c'est un interrupteur marche/arrêt. Le serveur décide où les limites du cache se situent.

Structure de la réponse

Appel advisor réussi

Lorsque l'advisor est invoqué, un bloc server_tool_use est suivi d'un bloc advisor_tool_result dans le contenu de l'assistant :

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

Le server_tool_use.input est toujours vide. Le serveur construit la vue de l'advisor à partir de la transcription complète automatiquement ; rien de ce que l'exécuteur met dans input n'atteint l'advisor.

Variantes de résultats

Le champ advisor_tool_result.content est une union discriminée. La variante que vous recevez dépend du modèle advisor :

Avec advisor_result, le champ text contient des conseils lisibles par l'homme. Avec advisor_redacted_result, le champ encrypted_content contient un blob opaque que vous ne pouvez pas lire ; au tour suivant, le serveur le déchiffre et rend le texte brut dans l'invite de l'exécuteur.

Dans les deux cas, renvoyez le contenu verbatim aux tours suivants. Si vous changez de modèle advisor en cours de conversation, branchez sur content.type pour gérer les deux formes.

Résultats d'erreur

Si l'appel advisor échoue, le résultat porte une erreur :

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

L'exécuteur voit l'erreur et continue sans conseils supplémentaires. La requête elle-même ne échoue pas.

Les limites de débit advisor proviennent du même compartiment par modèle que les appels directs au modèle advisor. Une limite de débit sur l'advisor apparaît comme too_many_requests à l'intérieur du résultat de l'outil ; une limite de débit sur l'exécuteur échoue la requête entière avec HTTP 429.

Conversations multi-tours

Passez le contenu complet de l'assistant, y compris les blocs advisor_tool_result, à l'API aux tours suivants :

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

Si vous omettez l'outil advisor de tools à un tour de suivi tandis que l'historique des messages contient toujours des blocs advisor_tool_result, l'API retourne une 400 invalid_request_error.

Streaming

La sous-inférence advisor ne fait pas de streaming. Le flux de l'exécuteur s'interrompt pendant que l'advisor s'exécute, puis le résultat complet arrive dans un seul événement.

Le bloc server_tool_use avec name: "advisor" signale qu'un appel advisor commence. La pause commence lorsque ce bloc se ferme (content_block_stop). Pendant la pause, le flux est silencieux sauf pour les ping SSE standard émis environ toutes les 30 secondes ; les appels advisor courts peuvent ne montrer aucun ping.

Lorsque l'advisor termine, le advisor_tool_result arrive complètement formé dans un seul événement content_block_start (pas de deltas). La sortie de l'exécuteur reprend ensuite le streaming.

Un événement message_delta suit avec le tableau usage.iterations mis à jour reflétant les comptes de jetons de l'advisor.

Utilisation et facturation

Les appels advisor s'exécutent comme une sous-inférence séparée facturée aux tarifs du modèle advisor. L'utilisation est rapportée dans le tableau usage.iterations[] :

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

Les champs usage de niveau supérieur reflètent uniquement les jetons de l'exécuteur. Les jetons advisor ne sont pas intégrés aux totaux de niveau supérieur car ils sont facturés à un taux différent. Les itérations avec type: "advisor_message" sont facturées aux tarifs du modèle advisor ; les itérations avec type: "message" sont facturées aux tarifs du modèle exécuteur.

Les règles d'agrégation diffèrent selon le champ. Le output_tokens de niveau supérieur est la somme de toutes les itérations de l'exécuteur. Le input_tokens de niveau supérieur et cache_read_input_tokens reflètent uniquement la première itération de l'exécuteur ; les entrées des itérations de l'exécuteur suivantes ne sont pas re-sommées car elles incluent les jetons de sortie précédents. Utilisez usage.iterations pour une ventilation complète par itération lors de la construction de la logique de suivi des coûts.

La sortie advisor est généralement 400 à 700 jetons de texte, ou 1 400 à 1 800 jetons au total incluant la réflexion. Les économies de coûts proviennent du fait que l'advisor ne génère pas votre sortie finale complète ; l'exécuteur le fait à son taux inférieur.

Le max_tokens de niveau supérieur s'applique uniquement à la sortie de l'exécuteur. Il ne limite pas les jetons de sous-inférence advisor. Les jetons de l'advisor ne tirent pas non plus d'un budget de tâche appliqué à l'exécuteur.

Mise en cache des invites Advisor

Il y a deux couches de mise en cache indépendantes.

Mise en cache côté exécuteur

Le bloc advisor_tool_result est cacheable comme n'importe quel autre bloc de contenu. Un point d'arrêt cache_control placé après lui à un tour suivant sera atteint. L'invite de l'exécuteur contient toujours les conseils en texte brut indépendamment du fait que votre client ait reçu text ou encrypted_content, donc le comportement de mise en cache est identique pour les deux variantes de résultats.

Mise en cache côté advisor

Définissez caching sur la définition de l'outil pour activer la mise en cache des invites pour la propre transcription de l'advisor entre les appels au sein de la même conversation :

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

L'invite de l'advisor au Nième appel est l'invite du (N-1)ième appel avec un segment supplémentaire ajouté, donc le préfixe est stable entre les appels. Avec caching activé, chaque appel advisor écrit une entrée de cache ; l'appel suivant lit jusqu'à ce point et ne paie que pour le delta. Vous verrez cache_read_input_tokens devenir non nul sur les deuxième et ultérieures itérations advisor_message.

Quand l'activer : Le coût d'écriture du cache est plus élevé que ce que les lectures économisent lorsque l'advisor est appelé deux fois ou moins par conversation. La mise en cache atteint l'équilibre à environ trois appels advisor et s'améliore à partir de là. Activez-la pour les boucles d'agent longues ; gardez-la désactivée pour les tâches courtes.

Gardez-la cohérente : Définissez caching une fois et laissez-la pour toute la conversation. L'activer et la désactiver en cours de conversation provoque des défauts de cache.

Combinaison avec d'autres outils

L'outil advisor se compose avec d'autres outils côté serveur et côté client. Ajoutez-les tous au même tableau tools :

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

L'exécuteur peut rechercher sur le web, appeler l'advisor et utiliser vos outils personnalisés dans le même tour. Le plan de l'advisor peut informer les outils que l'exécuteur utilise ensuite.

Meilleures pratiques

Invites pour les tâches de codage et d'agent

L'outil advisor est livré avec une description intégrée qui pousse l'exécuteur à l'appeler près du début des tâches complexes et lorsqu'il rencontre une difficulté. Pour les tâches de recherche, aucune invite supplémentaire n'est généralement nécessaire.

Sur les tâches de codage et d'agent, l'advisor produit une intelligence plus élevée à un coût similaire lorsqu'il réduit les appels d'outils totaux et la longueur de la conversation. Deux timings conduisent à cette amélioration :

1. Un premier appel advisor précoce, après quelques lectures exploratoires dans la transcription.
2. Pour les tâches difficiles, un appel advisor final après les écritures de fichiers et les sorties de test dans la transcription.

Si votre agent expose d'autres outils de type planificateur (par exemple, un outil de liste de tâches), invitez le modèle à appeler l'advisor avant ces outils afin que le plan de l'advisor les alimente. L'invite système suggérée ci-dessous renforce le modèle d'appel précoce ; ajoutez votre propre phrase d'alimentation pointant vers les outils de planificateur que votre agent expose.

Invite système suggérée pour les tâches de codage

Pour les tâches de codage où vous voulez un timing advisor cohérent et environ deux à trois appels par tâche, ajoutez les blocs suivants à votre invite système d'exécuteur avant toute autre phrase qui mentionne l'advisor. Sur les évaluations de codage internes, ce modèle a produit l'intelligence la plus élevée à un coût proche de Sonnet.

Conseils de timing :

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

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

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

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

Comment l'exécuteur doit traiter les conseils (placer directement après le bloc de timing) :

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.

Réduction de la longueur de la sortie advisor

La sortie advisor est le principal facteur de coût de l'advisor. Pour réduire ce coût, ajoutez une seule instruction de concision à l'invite système avant toute autre phrase qui mentionne l'advisor. Dans les tests internes, la ligne suivante a réduit les jetons de sortie advisor totaux d'environ 35 à 45 pour cent sans changer la fréquence d'appel :

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

Associez ceci au bloc de timing ci-dessus pour le meilleur compromis coût-qualité.

Appairage avec les paramètres d'effort

Pour les tâches de codage, l'appairage d'un exécuteur Sonnet à effort moyen avec un advisor Opus atteint une intelligence comparable à Sonnet à l'effort par défaut, à un coût inférieur. Pour l'intelligence maximale, gardez l'exécuteur à l'effort par défaut.

Contrôle des coûts

• Pour les budgets au niveau de la conversation, comptez les appels advisor côté client. Lorsque vous atteignez votre plafond, supprimez l'outil advisor de tools et supprimez tous les blocs advisor_tool_result de votre historique de messages pour éviter une 400 invalid_request_error.
• Activez caching uniquement pour les conversations où vous attendez trois appels advisor ou plus.

Limitations

• La sortie advisor ne fait pas de streaming. Attendez-vous à une pause dans le flux pendant que la sous-inférence s'exécute.
• Pas de plafond intégré au niveau de la conversation sur les appels advisor. Suivez et limitez-les côté client.
• max_tokens s'applique uniquement à la sortie de l'exécuteur. Il ne limite pas les jetons advisor.
• Anthropic Priority Tier est honoré par modèle. Priority Tier sur le modèle exécuteur ne s'étend pas à l'advisor ; vous avez besoin de Priority Tier sur le modèle advisor spécifiquement.