Outil advisor

L'outil advisor (conseiller) permet à un modèle exécuteur (« executor model ») plus rapide et moins coûteux de consulter un modèle conseiller (« advisor model ») plus intelligent en cours de génération pour obtenir des orientations stratégiques. Le conseiller lit l'intégralité de la conversation, produit un plan ou une correction de trajectoire, et l'exécuteur poursuit la tâche.

Ce modèle convient aux charges de travail agentiques à long horizon (agents de codage, utilisation de l'ordinateur, pipelines de recherche en plusieurs étapes) où la plupart des tours sont mécaniques, mais où disposer d'un excellent plan est crucial. Vous obtenez une qualité proche de celle du conseiller seul, tandis que l'essentiel de la génération de tokens se fait aux tarifs du modèle exécuteur. Pour des résultats mesurés, y compris la manière dont le bénéfice diminue à mesure que la capacité propre de l'exécuteur se rapproche de celle du conseiller, consultez Optimiser le coût et l'intelligence.



Quand l'utiliser

Le conseiller convient aux configurations suivantes :

• Vous utilisez actuellement Sonnet sur des tâches complexes : ajoutez un conseiller de niveau supérieur. Opus maintient un coût total similaire ou inférieur ; Claude Fable 5 maximise le gain de qualité.
• Vous utilisez actuellement Haiku et souhaitez un gain d'intelligence : ajoutez un conseiller Opus ou Fable. Attendez-vous à un coût plus élevé que Haiku seul, mais inférieur à celui d'un passage de l'exécuteur à un modèle plus grand.

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

Le conseiller convient moins bien aux questions-réponses à tour unique (rien à planifier), aux sélecteurs de modèles purement transparents où vos utilisateurs choisissent déjà leur propre compromis entre coût et qualité, ou aux charges de travail où chaque tour nécessite réellement la pleine capacité du modèle conseiller.



Démarrage rapide

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)

Le content de la réponse inclut un bloc advisor_tool_result contenant les orientations du conseiller. Avec claude-opus-5 comme conseiller, comme dans ce démarrage rapide, le champ content du bloc est une variante advisor_redacted_result (chiffrée ; l'exécuteur la lit côté serveur, mais pas votre client). Pour voir le texte du conseil directement dans votre réponse, utilisez plutôt claude-opus-4-8 comme modèle conseiller, qui renvoie la variante en clair advisor_result. Consultez Variantes de résultat pour voir les deux formes côte à côte et savoir quels modèles conseillers renvoient laquelle, et Compatibilité des modèles pour la liste complète des paires valides.



Fonctionnement

Lorsque vous ajoutez l'outil advisor à votre tableau tools, le modèle exécuteur détermine quand l'appeler, comme pour tout autre outil. Lorsque l'exécuteur appelle le conseiller :

1. L'exécuteur émet un bloc server_tool_use avec name: "advisor" et un input vide. L'exécuteur signale le moment, et le serveur fournit le contexte.
2. Anthropic exécute une passe d'inférence distincte sur le modèle conseiller côté serveur. Le conseiller fonctionne avec sa propre invite système fournie par Anthropic et reçoit la transcription complète de l'exécuteur comme contexte cité dans son entrée. Cette transcription inclut votre invite système, les définitions d'outils, les tours précédents et les résultats d'outils, ainsi que le texte que l'exécuteur a produit jusqu'ici dans ce tour.
3. La réponse du conseiller revient à l'exécuteur sous forme de bloc advisor_tool_result.
4. L'exécuteur continue à générer, éclairé par le conseil.

Tout cela se produit au sein d'une seule requête /v1/messages, sans aller-retour supplémentaire de votre côté. L'exception est un tour qui se met en pause en cours d'appel, que vous reprenez avec une requête de suivi (voir Reprendre un tour en pause).

Le conseiller lui-même fonctionne sans outils et sans gestion du contexte. Ses blocs de réflexion sont supprimés avant le retour du résultat. Seul le texte du conseil parvient à 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, il ne s'agit pas d'un marqueur de point de rupture. C'est un interrupteur marche/arrêt. Le serveur détermine où se situent les limites du cache.

L'outil advisor accepte également les propriétés génériques disponibles sur toute définition d'outil : cache_control, allowed_callers, defer_loading et strict (traité dans sorties structurées). Consultez la Référence des outils pour leur sémantique.



Structure de la réponse



Appel réussi au conseiller

Lorsque le conseiller est appelé, un bloc server_tool_use est suivi d'un bloc advisor_tool_result dans le contenu de l'assistant. L'exemple suivant montre la variante en clair advisor_result renvoyée par un conseiller Claude Opus 4.8. Le Démarrage rapide utilise Claude Opus 5, qui renvoie à la place la variante chiffrée advisor_redacted_result ; consultez Variantes de résultat pour voir les deux formes côte à côte.

{
  "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 automatiquement la vue du conseiller à partir de la transcription complète. Rien de ce que l'exécuteur place dans input ne parvient au conseiller.



Variantes de résultat

Le champ advisor_tool_result.content est une union discriminée. Pour les appels réussis, la variante dépend du modèle conseiller :

Voici la même requête envoyée deux fois, identique à l'exception du model du conseiller dans la définition de l'outil, montrant les deux variantes.

Avec "model": "claude-opus-4-8", le conseil est en clair :

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

Avec "model": "claude-opus-5", le conseil est chiffré :

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

Les deux variantes de résultat comportent un champ stop_reason lorsque vous définissez max_tokens sur la définition de l'outil, et l'omettent dans le cas contraire. Il contient la raison d'arrêt du sous-appel au conseiller, généralement "end_turn", ou "max_tokens" lorsque le plafond est atteint. Les valeurs correspondent au stop_reason de niveau supérieur de l'API Messages.

Avec advisor_result, le champ text contient un conseil lisible par un humain. 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 restitue le texte en clair dans le prompt de l'exécuteur.

Dans les deux cas, renvoyez le contenu tel quel lors des tours suivants. Si vous changez de modèle conseiller en cours de conversation, effectuez un branchement sur content.type pour gérer les deux formes.



Résultats d'erreur

Si l'appel au conseiller échoue, le résultat comporte 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 autre conseil. La requête elle-même n'échoue pas.

Les limites de débit du conseiller puisent dans le même compartiment par modèle que les appels directs au modèle conseiller. Une limite de débit sur le conseiller apparaît sous la forme too_many_requests dans le résultat de l'outil. Une limite de débit sur l'exécuteur fait échouer l'ensemble de la requête avec un HTTP 429.



Conversations multi-tours

Renvoyez l'intégralité du contenu de l'assistant, y compris les blocs advisor_tool_result, à l'API lors des tours suivants. Renvoyez les blocs de résultat tels quels : avec un conseiller Claude Opus 5, le content du bloc de résultat est la variante chiffrée advisor_redacted_result, et le serveur la déchiffre et restitue le conseil dans le prompt de l'exécuteur au tour suivant (voir Variantes de résultat). Le mécanisme est identique pour tout modèle conseiller.

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

# Ajouter le contenu complet de la réponse, y compris les blocs advisor_tool_result
messages.append({"role": "assistant", "content": response.content})

# Poursuivre la conversation
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,
)

Vous pouvez retirer l'outil advisor de tools lors d'un tour de suivi alors que l'historique des messages contient encore des blocs advisor_tool_result. La requête est acceptée et les blocs historiques sont préservés ; le modèle ne peut pas appeler le conseiller lors de ce tour. Vous devez tout de même envoyer l'en-tête bêta advisor-tool-2026-03-01 pour que ces blocs d'historique soient acceptés.



Reprendre un tour en pause

Une réponse peut se terminer avec stop_reason: "pause_turn" alors qu'un appel au conseiller est encore en attente. Lorsque cela se produit, la réponse contient le bloc server_tool_use du conseiller sans advisor_tool_result correspondant. Pour reprendre, ajoutez ce message de l'assistant à messages avec son contenu inchangé, en conservant le bloc server_tool_use, et renvoyez la requête avec le même outil advisor et le même en-tête bêta. Vous n'avez pas besoin d'ajouter un message utilisateur ni un bloc tool_result. L'API exécute l'appel au conseiller en attente et poursuit le tour de l'exécuteur dans la nouvelle réponse. Un tour repris peut se mettre à nouveau en pause. Si c'est le cas, répétez la même étape. Omettre l'outil advisor de la requête de reprise renvoie une erreur 400 invalid_request_error, car le bloc server_tool_use en attente n'a aucune définition d'outil sur laquelle s'exécuter ; incluez l'outil chaque fois qu'un appel est en attente. Si, au contraire, l'exécuteur a appelé l'un de vos outils dans le même tour, la réponse se termine avec stop_reason: "tool_use" alors que l'appel au conseiller est encore en attente. Envoyez les blocs tool_result comme d'habitude, et l'appel au conseiller en attente s'exécute au début de cette requête suivante. Consultez Combiner outils serveur et outils client dans un même tour.



Rappel en cours de conversation pour les exécuteurs qui appellent trop peu

Si un exécuteur Haiku n'a pas appelé le conseiller lors de son premier tour d'assistant, ajoutez un court rappel sous forme de message utilisateur supplémentaire avant le deuxième tour d'assistant. Dans l'évaluation comportementale interne d'Anthropic, cela a augmenté les taux de réussite des tâches d'environ 7 points de pourcentage sur les exécuteurs Haiku. Sur les exécuteurs Sonnet, le rappel en texte brut n'a eu aucun effet mesurable dans les tests d'Anthropic. Les considérations sur le moment des appels qui suivent sont particulièrement pertinentes pour Sonnet. N'appliquez pas le rappel aux exécuteurs Opus : sur Opus, il a légèrement réduit les taux de réussite.

Avec la valeur par défaut de NUDGE_TURN de 2, le rappel arrive généralement après que le modèle s'est orienté sur la tâche, mais avant qu'il ne se soit engagé dans une approche.

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):
    # Remplacez par votre répartition d'outils. Renvoie un bloc tool_result par bloc tool_use.
    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"},
    # ... vos autres outils
]
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})
    # Ignorez ceci si votre invite système indique déjà au modèle d'appeler avec parcimonie.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Ajoutez le rappel sous forme de message utilisateur distinct après les résultats d'outils plutôt que comme bloc frère dans le même message. Les messages utilisateur consécutifs sont valides. Dans les tests d'Anthropic sur les exécuteurs Haiku et Sonnet, ils se sont comportés de manière équivalente à un bloc frère. La forme en message séparé permet également de distinguer clairement le rappel de la sortie des outils.

Compromis : le rappel augmente le taux d'appel, ce qui peut pousser des tâches trivialement simples vers une consultation inutile. Si votre charge de travail mélange des tâches simples et complexes, envisagez de porter NUDGE_TURN à 3 afin que les tâches en deux tours se terminent avant le déclenchement du rappel, ou conditionnez le rappel à un signal de complexité de tâche que vous calculez déjà. Si votre invite système contient déjà un langage de retenue (« réservez le conseiller aux cas d'incertitude réelle »), ignorez complètement le rappel, car les deux instructions sont contradictoires.

Le rappel en texte brut est très saillant sur les exécuteurs Haiku et Sonnet : 74 pour cent (Sonnet) à 98 pour cent (Haiku) des tentatives avec rappel dans les tests d'Anthropic ont appelé le conseiller immédiatement au tour 2. Si cela survient avant que votre exécuteur n'ait lu le problème ou rassemblé du contexte, l'appel au conseiller qui en résulte dispose de peu de contexte et peut supplanter un appel ultérieur mieux placé. Mesurez le tour de premier appel de référence de votre exécuteur avant d'ajouter le rappel. Si l'exécuteur appelle déjà le conseiller de manière fiable et que son premier appel survient généralement au tour N, définissez NUDGE_TURN à une valeur supérieure à N. Dans les tests d'Anthropic, un rappel au tour 2 sur des charges de travail où le premier appel de référence se situait au tour 7 ou plus tard était corrélé à une baisse de performance des tâches de 3 à 4 points de pourcentage. Sur une charge de travail de navigation où le taux d'appel de référence était de 86 pour cent, le même rappel a augmenté l'engagement sans coût en performance des tâches.

Pour forcer une consultation sur une requête spécifique au lieu d'un rappel, définissez tool_choice sur {"type": "tool", "name": "advisor"}, sous réserve des contraintes décrites dans Forcer l'utilisation d'outils. Forcer l'utilisation d'outils ne peut pas être combiné avec la réflexion étendue manuelle (thinking: {type: "enabled"}) : l'API renvoie une erreur 400 invalid_request_error si vous activez les deux. La réflexion adaptative prend en charge l'utilisation forcée d'outils.



Streaming

La sous-inférence du conseiller n'est pas diffusée en streaming. Le flux de l'exécuteur se met en pause pendant l'exécution du conseiller ; puis le résultat complet arrive dans un seul événement.

Le bloc server_tool_use avec name: "advisor" signale qu'un appel au conseiller commence. La pause débute lorsque ce bloc se ferme (content_block_stop). Pendant la pause, le flux est silencieux, à l'exception des keepalives SSE ping standard émis environ toutes les 30 secondes. Les appels courts au conseiller peuvent ne montrer aucun ping.

Lorsque le conseiller termine, le advisor_tool_result arrive entièrement formé dans un seul événement content_block_start (sans deltas). La sortie de l'exécuteur reprend ensuite en streaming.

Un événement message_delta suit avec le tableau usage.iterations mis à jour reflétant les décomptes de tokens du conseiller.



Utilisation et facturation

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

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

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

Chaque champ usage de niveau supérieur est la somme de ce champ sur toutes les itérations de l'exécuteur, y compris input_tokens, output_tokens et cache_read_input_tokens. Comme chaque itération de l'exécuteur renvoie la conversation croissante, les entrées des itérations ultérieures incluent la sortie des itérations précédentes, de sorte que la somme des input_tokens dépasse la taille de n'importe quel prompt individuel. Utilisez usage.iterations pour une ventilation complète par itération lors de la création d'une logique de suivi des coûts.

La sortie du conseiller est généralement de 400 à 700 tokens de texte, ou de 1 400 à 1 800 tokens au total en incluant la réflexion. Les économies proviennent du fait que le conseiller ne génère pas l'intégralité de votre sortie finale. C'est l'exécuteur qui le fait, à son tarif inférieur.

Le max_tokens de niveau supérieur s'applique uniquement à la sortie de l'exécuteur. Il ne limite pas les tokens de la sous-inférence du conseiller. Pour plafonner directement la sortie du conseiller, définissez max_tokens sur la définition de l'outil. Les tokens du conseiller ne puisent pas non plus dans un éventuel budget de tâche appliqué à l'exécuteur.

Le Priority Tier s'applique à chaque modèle indépendamment. Un engagement Priority Tier sur le modèle exécuteur ne s'étend pas au conseiller. Les appels au conseiller s'exécutent en Priority Tier uniquement si votre organisation détient également un engagement sur le modèle conseiller.



Mise en cache des prompts du conseiller

Il existe deux couches de mise en cache indépendantes.



Mise en cache côté exécuteur

Le bloc advisor_tool_result peut être mis en cache comme tout autre bloc de contenu. Un point de rupture cache_control placé après lui lors d'un tour suivant produit un succès de cache. Le prompt de l'exécuteur contient toujours le conseil en clair, que votre client ait reçu text ou encrypted_content, de sorte que le comportement de mise en cache est identique pour les deux variantes de résultat.



Mise en cache côté conseiller

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

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

Le prompt du conseiller au Nième appel est le prompt du (N-1)ième appel avec un segment supplémentaire ajouté, de sorte que le préfixe est stable entre les appels. Avec caching activé, chaque appel au conseiller écrit une entrée de cache, et l'appel suivant lit jusqu'à ce point et ne paie que le delta. Vous verrez cache_read_input_tokens devenir non nul à partir de la deuxième itération advisor_message.

Quand l'activer : l'écriture en cache coûte plus que ce que les lectures économisent lorsque le conseiller est appelé deux fois ou moins par conversation. La mise en cache atteint l'équilibre à environ trois appels au conseiller et s'améliore au-delà. Activez-la pour les longues boucles d'agent et laissez-la désactivée pour les tâches courtes.

Restez cohérent : définissez caching une fois et conservez-le pour toute la conversation. L'activer et le désactiver en cours de conversation provoque des échecs de cache.



Combinaison avec d'autres outils

L'outil advisor se combine 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-5",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

L'exécuteur peut effectuer des recherches sur le web, appeler le conseiller et utiliser vos outils personnalisés dans le même tour. Le plan du conseiller peut orienter les outils vers lesquels l'exécuteur se tourne ensuite.



Bonnes pratiques



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

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

Sur les tâches de codage et d'agent, le conseiller produit une intelligence supérieure à coût similaire lorsqu'il réduit le nombre total d'appels d'outils et la longueur de la conversation. Deux moments sont à l'origine de cette amélioration :

1. Un premier appel précoce au conseiller, après que quelques lectures exploratoires figurent dans la transcription.
2. Pour les tâches difficiles, un dernier appel au conseiller après que les écritures de fichiers et les sorties de tests figurent 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 le conseiller avant ces outils afin que le plan du conseiller les alimente. L'invite système suggérée renforce le schéma d'appel précoce. Ajoutez votre propre phrase d'orientation pointant vers les outils de planification que votre agent expose.



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

Sans orientation par l'invite système, l'exécuteur a tendance à appeler trop peu le conseiller dans certains domaines, en particulier les tâches de codage. Pour les tâches de codage où vous souhaitez un moment d'appel cohérent et environ deux à trois appels par tâche, placez les blocs suivants au début de l'invite système de votre exécuteur, avant toute autre phrase mentionnant le conseiller.

Orientation sur le moment des appels :

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 le conseil (à placer directement après le bloc sur le moment des appels) :

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.



Invite système alternative pour Haiku sur les charges de travail de codage

Claude Haiku 4.5 applique l'orientation par défaut du conseiller de manière conservatrice. Cela maintient son taux d'appel à un niveau approprié sur les charges de travail de recherche et de consultation, mais sacrifie de la qualité sur les charges de travail de codage, où une consultation précoce du conseiller est systématiquement rentable. Sur un benchmark de codage interne, une variante proche du bloc suivant (l'exception en lecture seule dans la règle stricte a été ajoutée après la mesure) a augmenté les taux de réussite de Haiku d'environ 7,5 points de pourcentage par rapport à la valeur par défaut intégrée.

Utilisez ce bloc à la place des blocs précédents sur le moment des appels et le traitement des conseils lorsque votre exécuteur Haiku exécute principalement des charges de travail de codage ou d'écriture :

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.

Mise en garde : sur un benchmark interne de compréhension par navigation (n = 1 266), une variante proche de ce bloc a coûté environ 4 points de pourcentage de précision par rapport à la valeur par défaut intégrée. Si votre charge de travail mélange du codage avec une part substantielle de consultation ou de récupération, conservez les blocs suggérés, ou conditionnez le remplacement à un signal de type de charge de travail que vous calculez déjà.



Augmenter les appels au conseiller sur les exécuteurs Opus

Les exécuteurs Opus appellent généralement le conseiller à un rythme approprié sans prompting supplémentaire. Si votre exécuteur Opus appelle trop peu sur votre charge de travail, ajoutez le point de contrôle suivant à votre invite système :

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.

Mise en garde : dans les tests d'Anthropic, une variante proche de ce bloc (l'exception en lecture seule dans la règle stricte a été ajoutée après la mesure) a augmenté les taux de réussite sur les tâches avec trop peu d'appels d'environ 7 à 10 points de pourcentage, mais a amené Opus à appeler trop souvent sur les tâches dont la première action ne nécessite aucune planification. L'effet net était à peu près neutre sur une charge de travail mixte. Ne l'ajoutez que si vous avez observé qu'Opus ignore le conseiller sur des tâches où une consultation aurait été utile. Ne l'ajoutez pas par défaut.



Réduire la longueur de la sortie du conseiller

La sortie du conseiller est le principal facteur de coût du conseiller, et le max_tokens de niveau supérieur ne la limite pas. Le conseiller voit à la fois votre invite système et vos messages utilisateur comme contexte cité concernant la tâche de l'exécuteur, de sorte que les instructions qui s'adressent directement au conseiller sont suivies de manière beaucoup plus fiable que les descriptions à la troisième personne. L'emplacement le plus efficace testé par Anthropic est une ligne dans le message utilisateur :

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

Cette ligne peut être ajoutée en préfixe par programmation par votre framework d'agent avant l'envoi de la requête. La limite est une contrainte souple. Le conseiller la dépasse occasionnellement, demandez donc environ 80 pour cent de votre plafond réel.

Associez cette approche à l'orientation sur le moment des appels de l'Invite système suggérée pour les tâches de codage (ou du bloc alternatif pour Haiku si vous l'avez adopté) pour obtenir le meilleur compromis coût-qualité. Pour un plafond strict plutôt qu'une demande souple, consultez Plafonner la sortie du conseiller.



Plafonner la sortie du conseiller

Définissez max_tokens sur la définition de l'outil pour plafonner la sortie totale du conseiller (réflexion plus texte) par appel :

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

La valeur minimale est 1024. Définir max_tokens au-dessus du propre plafond de sortie du modèle conseiller renvoie une erreur 400. Le plafond s'applique à chaque appel au conseiller indépendamment et n'est pas partagé entre les appels d'une même requête.

Il ne s'agit pas uniquement d'une troncature stricte. Le serveur transmet également au conseiller son budget de tokens restant, de sorte que le conseiller adapte sa réponse pour s'y conformer.

Point de départ recommandé : max_tokens: 2048. Dans les tests d'Anthropic sur un benchmark de raisonnement difficile (n = 40 par configuration), cela a réduit la sortie moyenne du conseiller d'environ 7x par rapport à l'absence de plafond, avec une troncature quasi nulle et aucune dégradation de qualité détectable. La valeur minimale de 1024 a réduit la sortie d'environ 10x, mais a tronqué environ 10 pour cent des appels. Les différences de précision entre toutes les configurations se situaient dans le bruit statistique pour cette taille d'échantillon. Validez sur votre propre charge de travail.

Les tâches de raisonnement difficiles suscitent une sortie du conseiller nettement plus longue que les 1 400 à 1 800 tokens typiques cités plus haut pour des charges de travail plus légères. Utilisez ce tableau pour évaluer le ratio d'économies, et non comme référence universelle pour la sortie du conseiller.

Lorsque le conseiller atteint effectivement le plafond, le bloc de résultat comporte stop_reason: "max_tokens" sur les deux variantes de résultat, quel que soit le modèle conseiller utilisé. Utilisez stop_reason pour détecter les conseils tronqués et décider s'il faut relever le plafond ou laisser l'exécuteur poursuivre avec des orientations partielles. L'API ajoute également [Advisor output truncated at max_tokens=2048.] (en nommant votre plafond) au texte du conseil, de sorte que l'exécuteur voit la troncature dans son propre contexte ; avec un conseiller renvoyant un advisor_result en clair, ce marqueur est également visible pour votre client. Les deux signaux n'apparaissent que lorsque vous définissez max_tokens sur la définition de l'outil.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

Vérifiez output_tokens sur l'entrée advisor_message correspondante dans usage.iterations pour voir à quel point chaque appel s'est approché de son plafond.

Par rapport à l'approche basée sur le prompt, max_tokens est un plafond strict plutôt qu'une demande souple. Utilisez max_tokens lorsque vous avez besoin d'une limite garantie pour le coût ou la latence. Utilisez l'approche basée sur le prompt (ou les deux ensemble) lorsque vous souhaitez favoriser la concision sans risquer une coupure en plein raisonnement.



Association avec les paramètres d'effort

Pour les tâches de codage, associer un exécuteur Sonnet à effort moyen avec un conseiller Opus permet d'atteindre une intelligence comparable à celle de Sonnet à effort par défaut, à moindre coût. Pour une intelligence maximale, conservez l'exécuteur à l'effort par défaut.



Contrôle des coûts

• Pour les budgets au niveau de la conversation, comptez les appels au conseiller côté client. Lorsque vous atteignez votre plafond, retirez l'outil advisor de tools ; vous n'avez pas besoin de supprimer les blocs advisor_tool_result de votre historique de messages (voir la note dans Conversations multi-tours).
• Activez caching uniquement pour les conversations où vous prévoyez trois appels au conseiller ou plus.



Compatibilité des modèles

Le modèle « executor » (exécuteur), c'est-à-dire le champ model de premier niveau, et le modèle « advisor » (conseiller), c'est-à-dire le champ model à l'intérieur de la définition de l'outil, doivent former une paire valide. Le conseiller doit être Claude Sonnet 4.6 ou un modèle plus performant, et il doit être au moins aussi performant que l'exécuteur. Des modèles de capacité égale (par exemple, Claude Opus 4.7 et Claude Opus 4.8) peuvent se conseiller mutuellement.

Si vous demandez une paire non valide, l'API renvoie une erreur 400 invalid_request_error indiquant la combinaison non prise en charge.



Disponibilité selon la plateforme

L'outil conseiller est disponible en version bêta sur l'API Claude et sur Claude Platform sur AWS. Il n'est actuellement pas disponible sur Amazon Bedrock, Google Cloud ou Microsoft Foundry.



Conseiller sur Claude Managed Agents

Les sessions Claude Managed Agents prennent également en charge un conseiller, configuré dans le cadre de l'agent plutôt que sous forme de définition d'outil : ajoutez une entrée {"type": "advisor", "model": ...} à la liste multi-agents de l'agent, et le fil principal de la session pourra consulter ce modèle en cours de tour. L'entrée de la liste n'accepte pas les options max_uses, max_tokens ou caching, et les conseils sont transmis sous forme d'événements de fil sur le flux d'événements de la session plutôt que sous forme de blocs advisor_tool_result dans la réponse. Consultez Donner un conseiller à la session.



Étapes suivantes