Outil advisor

L'outil advisor permet à un modèle exécuteur plus rapide et moins coûteux de consulter un modèle conseiller de plus haute intelligence en cours de génération pour obtenir des conseils 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 schéma 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 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 s'effectue aux tarifs du modèle exécuteur.



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 le 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 est moins adapté 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 coût/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 conseils du conseiller. Avec Claude Opus 5, Claude Fable 5 ou Claude Mythos 5 comme conseiller, 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 advisor_result en texte clair. Consultez Variantes de résultat pour les deux formes 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 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 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 forme de bloc advisor_tool_result.
4. L'exécuteur continue de générer, informé par le conseil.

Tout cela se produit au sein d'une seule requête /v1/messages, sans allers-retours supplémentaires 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 de 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 d'arrêt. 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ées dans sorties structurées). Consultez la Référence des outils pour leur sémantique.



Structure de la réponse



Appel au conseiller réussi

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 advisor_result en texte clair 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.

{
  "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 n'atteint le 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 Opus 5, 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 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 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 un conseil lisible par l'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 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 contient 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 conseil supplémentaire. 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 l'ensemble de la requête avec HTTP 429.



Conversations multi-tours

Transmettez l'intégralité du contenu de l'assistant, y compris les blocs advisor_tool_result, à l'API lors des tours suivants. Cet exemple utilise claude-opus-4-8 comme conseiller afin que le conseil en texte clair soit visible dans response.content ; la mécanique est identique pour tout modèle conseiller.

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-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

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

# Poursuivez 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 toujours 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, à la place, 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 Mélanger outils serveur et 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 bref 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 de timing d'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 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 dispatch 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 comme son propre message utilisateur 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é permet également de distinguer clairement le rappel de la sortie d'outil.

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 à 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 cas de véritable incertitude »), omettez entièrement 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 % (Sonnet) à 98 % (Haiku) des tentatives avec rappel dans les tests d'Anthropic ont appelé le conseiller immédiatement au tour 2. Si cela arrive avant que votre exécuteur n'ait lu le problème ou rassemblé du contexte, l'appel au conseiller qui en résulte est pauvre en 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 arrive généralement au tour N, définissez NUDGE_TURN supérieur à N. Dans les tests d'Anthropic, un rappel au tour 2 sur des charges de travail où le premier appel de référence était au tour 7 ou plus tard était corrélé à une baisse de performance de tâche 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 %, le même rappel a augmenté l'engagement sans coût de performance de tâche.

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 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 d'outils forcée.



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 que le conseiller s'exécute ; puis le résultat complet arrive en un seul événement.

Le bloc server_tool_use avec name: "advisor" signale qu'un appel au conseiller commence. 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, le 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 comptages 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 cumulé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.

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 antérieures, de sorte que la somme des input_tokens dépasse la taille de tout prompt individuel. 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 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 d'arrêt cache_control placé après lui lors d'un tour suivant est atteint. 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-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 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 du 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 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-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 que l'exécuteur utilisera 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 au 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 clés favorisent 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 alimente ceux-ci. 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 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 timing cohérent du conseiller et environ deux à trois appels par tâche, ajoutez les blocs suivants au début de votre invite système de l'exécuteur, avant toute autre phrase mentionnant le conseiller.

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 le conseil (à 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.



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

Claude Haiku 4.5 applique les conseils 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 pour les opérations 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 de timing et de conseil précédents 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 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 le codage avec une part substantielle de consultation ou de récupération, conservez les blocs suggérés, ou conditionnez le changement à 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 pour les opérations 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 sous-appelées 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. N'ajoutez ce bloc que si vous avez observé Opus ignorer le conseiller sur des tâches où une consultation aurait été utile. Ne l'ajoutez pas par défaut.



Réduire la longueur de 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 beaucoup plus fiablement que les descriptions à la troisième personne. Le placement 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 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 % de votre plafond réel.

Associez cette approche aux conseils de timing de Invite système suggérée pour les tâches de codage (ou au bloc alternatif pour Haiku si vous l'avez substitué) 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-4-8",
        "max_tokens": 2048,
    }
]

La valeur minimale est 1024. Définir max_tokens au-dessus du plafond de sortie propre au 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 de la même requête.

Il ne s'agit pas d'une simple troncature brute. 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 % des appels. Les différences de précision entre toutes les configurations étaient dans la marge de bruit à cette taille d'échantillon. Validez sur votre propre charge de travail.

Les tâches de raisonnement difficile suscitent une sortie du conseiller substantiellement plus longue que les 1 400 à 1 800 tokens typiques cités précédemment pour les charges de travail plus légères. Utilisez ce tableau pour dimensionner le ratio d'économies, et non comme une 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.] (indiquant votre plafond) au texte du conseil, afin que l'exécuteur voie la troncature dans son propre contexte. Utilisez stop_reason pour détecter un conseil tronqué et décider s'il faut augmenter le plafond ou laisser l'exécuteur continuer avec des conseils partiels. 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 pensée.



Association avec les paramètres d'effort

Pour les tâches de codage, associer un exécuteur Sonnet à effort moyen avec un conseiller Opus atteint une intelligence comparable à 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 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 performant, et il doit être au moins aussi performant que l'exécuteur. Des modèles de capacité équivalente (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 indiquant la combinaison non prise en charge.



Disponibilité par 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 comme une définition d'outil : ajoutez une entrée {"type": "advisor", "model": ...} à la liste multiagent 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.



Prochaines étapes