Outil conseiller (advisor)

L'outil « advisor » (conseiller) permet à un executor model (modèle exécuteur) plus rapide et moins coûteux de consulter un advisor model (modèle conseiller) doté d'une intelligence supérieure en cours de génération pour obtenir des conseils stratégiques. Le conseiller lit la conversation complète, 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 multi-é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.



Quand l'utiliser

Le conseiller convient à ces configurations :

• Vous utilisez actuellement Sonnet sur des tâches complexes : ajoutez Opus comme conseiller pour un gain de qualité à un coût total similaire ou inférieur.
• Vous utilisez actuellement Haiku et souhaitez un niveau d'intelligence supérieur : ajoutez Opus comme conseiller. Attendez-vous à un coût plus élevé que Haiku seul, mais inférieur à celui du 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 est moins adapté aux questions-réponses en un seul tour (rien à planifier), aux sélecteurs de modèles en simple transfert 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 toute la capacité du modèle conseiller.



Compatibilité des modèles

Le modèle exécuteur (le champ model de niveau supérieur) et le modèle conseiller (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 capable, et il doit être au moins aussi capable que l'exécuteur. Les 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 invalide, l'API renvoie une erreur 400 invalid_request_error nommant la combinaison non prise en charge.



Disponibilité sur les plateformes

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.



Démarrage rapide

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-8",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)



Fonctionnement

Lorsque vous ajoutez l'outil conseiller à votre tableau tools, le modèle exécuteur détermine quand l'appeler, comme n'importe quel autre outil. Lorsque l'exécuteur invoque 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 s'exécute sous 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'à présent dans ce tour.
3. La réponse du conseiller revient à l'exécuteur sous la forme d'un bloc advisor_tool_result.
4. L'exécuteur continue à générer, éclairé par les conseils.

Tout cela se produit à l'intérieur 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 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 renvoyé. 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 d'arrêt. C'est un interrupteur marche/arrêt. Le serveur détermine où se situent les limites du cache.

L'outil conseiller accepte également les propriétés génériques disponibles sur toute définition d'outil : cache_control, allowed_callers, defer_loading et strict (couvertes dans les 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 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 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 :

Les conseillers Claude Fable 5 et Claude Mythos 5 renvoient advisor_redacted_result. Les autres modèles conseillers du tableau de compatibilité renvoient advisor_result.

Les deux variantes de résultat portent 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 du 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 des conseils lisibles 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 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 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 comme too_many_requests à l'intérieur du résultat de l'outil. Une limite de débit sur l'exécuteur fait échouer toute la requête avec un HTTP 429.



Conversations multi-tours

Transmettez le contenu complet de l'assistant, y compris les blocs advisor_tool_result, à l'API lors des tours suivants :

client = anthropic.Anthropic()

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

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Ajouter le contenu complet de la réponse, y compris les blocs advisor_tool_result éventuels
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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Si vous omettez l'outil conseiller de tools lors d'un tour de suivi alors que l'historique des messages contient encore des blocs advisor_tool_result, l'API renvoie une erreur 400 invalid_request_error.



Reprendre un tour en pause

Une réponse peut se terminer par 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 conseiller et le même en-tête bêta. Vous n'avez pas besoin d'ajouter un message utilisateur ou 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 en pause à nouveau. Si c'est le cas, répétez la même étape. Omettre l'outil conseiller de la requête de reprise renvoie une erreur 400 invalid_request_error. Si, à la place, l'exécuteur a appelé l'un de vos outils dans le même tour, la réponse se termine par 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. Voir Mélanger les outils serveur et les outils client dans un même tour.



Rappel en cours de conversation pour les exécuteurs qui sous-appellent

Si un exécuteur Haiku n'a pas appelé le conseiller lors de son premier tour d'assistant, ajoutez un court rappel sous la forme d'un 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 de l'appel 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-4-8"},
    # ... 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(
        b.type == "server_tool_use" and b.name == "advisor" for b in response.content
    )
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # 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 comme un message utilisateur à part entière après les résultats d'outils plutôt que comme un 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é maintient également le rappel clairement distinct 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 d'augmenter NUDGE_TURN à 3 afin que les tâches en deux tours se terminent avant que le rappel ne se déclenche, 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 véritables incertitudes »), omettez entièrement le rappel, car les deux instructions entrent en conflit.

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 se produit avant que votre exécuteur n'ait lu le problème ou rassemblé du contexte, l'appel au conseiller qui en résulte manque de contexte et peut remplacer un appel ultérieur mieux synchronisé. Mesurez le tour du 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 se produit 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 sur la performance des tâches.

Pour forcer une consultation sur une requête spécifique au lieu d'utiliser 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 : l'API renvoie une erreur 400 invalid_request_error si vous activez les deux.



Streaming

La sous-inférence du conseiller ne fait pas de streaming. Le flux de l'exécuteur se met en pause pendant que le conseiller 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 au conseiller démarre. La pause commence 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, l'advisor_tool_result arrive entièrement 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 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": 412,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-4-8",
        "input_tokens": 823,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "cache_creation_input_tokens": 0,
        "output_tokens": 442
      }
    ]
  }
}

Les champs usage de niveau supérieur ne reflètent que les tokens de l'exécuteur. Les tokens du conseiller ne sont pas intégrés dans les 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.

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. Les input_tokens et cache_read_input_tokens de niveau supérieur ne reflètent que la première itération de l'exécuteur. Les entrées des itérations suivantes de l'exécuteur ne sont pas additionnées à nouveau car elles incluent les tokens de sortie précédents. Utilisez usage.iterations pour une ventilation complète par itération lors de la construction 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 de coûts proviennent du fait que le conseiller ne génère pas votre sortie finale complète. 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 (niveau prioritaire) 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 n'importe quel autre bloc de contenu. Un point d'arrêt cache_control placé après lui lors d'un tour suivant produit un hit. Le prompt de l'exécuteur contient toujours le conseil en texte 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-4-8",
        "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 pour 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 dans le cache coûte plus cher que ce que les lectures économisent lorsque le conseiller est appelé deux fois ou moins par conversation. La mise en cache atteint le seuil de rentabilité à 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 laissez-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 conseiller 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-8",
    },
    {
        "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 le conseiller et utiliser vos outils personnalisés dans le même tour. Le plan du conseiller peut éclairer les outils que l'exécuteur utilisera ensuite.



Bonnes pratiques



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

L'outil conseiller 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 à un coût similaire lorsqu'il réduit le nombre total d'appels d'outils et la longueur de la conversation. Deux moments déterminent 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), incitez le modèle à appeler le conseiller avant ces outils afin que le plan du conseiller s'y déverse. L'invite système suggérée renforce le schéma d'appel précoce. Ajoutez votre propre phrase d'acheminement 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 à sous-appeler 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 au conseiller cohérent et environ deux à trois appels pour chaque tâche, ajoutez les blocs suivants au début de votre invite système d'exécuteur, avant toute autre phrase mentionnant le conseiller.

Directives de synchronisation :

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 synchronisation) :

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 les directives 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 la qualité sur les charges de travail de codage, où une consultation précoce du conseiller est rentable de manière fiable. Sur un benchmark de codage interne, une variante proche du bloc suivant (l'exception en lecture seule dans la règle Hard 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 de synchronisation et de conseil précédents lorsque votre exécuteur Haiku exécute principalement des charges de travail de codage ou de tâches 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 de 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 importante de consultation ou de récupération, restez avec 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 sous-appelle 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 Hard a été ajoutée après la mesure) a augmenté les taux de réussite sur les tâches sous-appelantes d'environ 7 à 10 points de pourcentage, mais a amené Opus à sur-appeler 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é Opus ignorer le conseiller sur des tâches où une consultation aurait aidé. 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é sur 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 préfixée de manière programmatique 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 aux directives de synchronisation de l'invite système suggérée pour les tâches de codage (ou du bloc alternatif pour Haiku si vous l'avez substitué) pour 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-4-8",
        "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 seulement 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 qu'elle tienne.

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 à 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 dimensionner le ratio d'économies, pas comme référence universelle pour la sortie du conseiller.

Lorsque le conseiller atteint effectivement le plafond, le bloc de résultat porte stop_reason: "max_tokens". 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. Utilisez stop_reason pour détecter les conseils tronqués et décider s'il faut augmenter le plafond ou laisser l'exécuteur poursuivre avec des directives partielles. 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_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

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 pleine réflexion.



Association avec les paramètres d'effort

Pour les tâches de codage, associer un exécuteur Sonnet à un effort moyen avec un conseiller Opus permet d'atteindre une intelligence comparable à Sonnet à l'effort par défaut, à un coût inférieur. Pour une 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 au conseiller côté client. Lorsque vous atteignez votre plafond, retirez l'outil conseiller de tools et supprimez tous les blocs advisor_tool_result de votre historique de messages pour éviter une erreur 400 invalid_request_error (voir la note dans Conversations multi-tours).
• Activez caching uniquement pour les conversations où vous prévoyez trois appels au conseiller ou plus.



Prochaines étapes