Outil advisor

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

Ce schéma 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 utilisé 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, notamment la façon dont le bénéfice diminue à mesure que les capacités propres de l'exécuteur se rapprochent de celles 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.1 maximise le gain de qualité.
• Vous utilisez actuellement Haiku et souhaitez un niveau d'intelligence supérieur : ajoutez un conseiller Opus ou Fable. Attendez-vous à un coût plus élevé qu'avec 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 en un seul tour (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 directement le texte du conseil 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 n'importe quel 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 avec sa propre invite système fournie par Anthropic et reçoit la transcription complète de l'exécuteur sous forme de 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, é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 s'exécute 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 texte 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 dans 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 premier niveau 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 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 (« rate limits ») 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). La mécanique 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 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 pas de 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 des outils serveur et des outils client dans un même tour.

Relance 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 la forme d'un message utilisateur supplémentaire avant le deuxième tour d'assistant. Dans l'évaluation comportementale interne d'Anthropic sur des exécuteurs Claude Haiku 4.5, cela a augmenté les taux de réussite des tâches d'environ 7 points de pourcentage. Sur les exécuteurs Sonnet, la relance en texte brut n'a eu aucun effet mesurable lors des tests d'Anthropic. Les considérations sur le moment des appels qui suivent sont particulièrement pertinentes pour Sonnet. N'appliquez pas la relance aux exécuteurs Opus : sur Opus, elle a légèrement réduit les taux de réussite.

Avec la valeur par défaut de NUDGE_TURN fixée à 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 propre 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-5-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 == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it
    if response.stop_reason != "tool_use":
        break  # end_turn, or a stop such as max_tokens that needs handling (see below)

    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 demande déjà au modèle d'appeler les outils avec parcimonie.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

La boucle se termine sur toute raison d'arrêt autre que tool_use ou pause_turn. Si max_tokens interrompt une réponse, retirez le tour d'assistant tronqué de messages et réessayez avec un max_tokens plus élevé. Lorsque ce tour ne contient aucun bloc tool_use, vous pouvez à la place le conserver et poursuivre la réponse avec un nouveau message utilisateur. Renvoyer le tour d'assistant tronqué comme dernier message constitue un préremplissage, que Claude 4.6 et les modèles ultérieurs rejettent.

Ajoutez la relance sous la forme d'un message utilisateur distinct 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. Lors des tests d'Anthropic sur des exécuteurs Claude Haiku 4.5 et Sonnet, ils se sont comportés de manière équivalente à un bloc frère. La forme en message séparé permet également de bien distinguer le rappel de la sortie des outils.

Compromis : la relance augmente le taux d'appel, ce qui peut entraîner une consultation inutile pour des tâches trivialement simples. 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 de la relance, ou conditionnez la relance à un signal de complexité de tâche que vous calculez déjà. Si votre invite système contient déjà des formulations de retenue (« réservez le conseiller aux véritables incertitudes »), ignorez complètement la relance, car les deux instructions sont contradictoires.

La relance en texte brut est très saillante sur les exécuteurs Claude Haiku 4.5 et Sonnet : de 74 % (Sonnet) à 98 % (Claude Haiku 4.5) des tentatives relancées lors des 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 remplacer un appel ultérieur mieux placé. Mesurez le tour de premier appel de référence de votre exécuteur avant d'ajouter la relance. 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. Lors des tests d'Anthropic, une relance au tour 2 sur des charges de travail où le premier appel de référence survenait au tour 7 ou plus tard était corrélée à une baisse de 3 à 4 points de pourcentage des performances sur les tâches. Sur une charge de travail de navigation où le taux d'appel de référence était de 86 %, la même relance a augmenté l'engagement sans coût sur les performances des tâches.

Pour forcer une consultation sur une requête spécifique au lieu d'utiliser une relance, 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. Les exécuteurs Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 et Claude Mythos 5.1 rejettent les types tool_choice tool et any ; utilisez donc plutôt la relance par prompt sur ces modèles.

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 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 n'afficher aucun ping.

Lorsque le conseiller termine, l'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 premier niveau reflètent uniquement les tokens de l'exécuteur. Les tokens du conseiller ne sont pas intégrés aux totaux de premier niveau, 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 premier niveau 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 lorsque vous construisez 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 premier niveau 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 n'importe quel 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 dans la définition de l'outil pour activer la mise en cache des prompts pour la propre transcription du conseiller d'un appel à l'autre au sein d'une même conversation :

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

Le prompt du conseiller lors du Nᵉ appel est le prompt du (N-1)ᵉ appel auquel un segment supplémentaire est ajouté ; le préfixe est donc stable d'un appel à l'autre. 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 en cache coûte plus que ce que les lectures font économiser lorsque le conseiller est appelé deux fois ou moins par conversation. La mise en cache devient rentable à partir d'environ trois appels au conseiller et s'améliore ensuite. 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 seule fois et conservez ce réglage pendant toute la conversation. Le désactiver puis le réactiver 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 le choix des outils que l'exécuteur utilisera ensuite.

Bonnes pratiques

Prompts 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 prompt 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'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 à 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 les orientations par défaut du conseiller de manière conservatrice. Cela maintient son taux d'appel à un niveau convenablement bas 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 en 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 prompt 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 sous-appelées d'environ 7 à 10 points de pourcentage, mais a amené Opus à trop 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é 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 son principal facteur de coût, et le max_tokens de premier niveau 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 aux orientations 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 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-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 en conséquence.

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 la marge de bruit 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 estimer 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 par 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 par 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 programmation, associer un exécuteur Sonnet avec un effort moyen à un conseiller Opus permet d'atteindre une intelligence comparable à celle de Sonnet avec l'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 conseiller 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 dans lesquelles vous prévoyez trois appels au conseiller ou plus.

Compatibilité des modèles

Le modèle exécuteur (le champ model de premier niveau) et le modèle conseiller (le champ model dans 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é sur les plateformes

L'outil conseiller est disponible en 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 : définissez "advisor": {"type": "enabled", "model": ...} dans le bloc multiagent de l'agent, et le fil principal de la session peut consulter ce modèle en cours de tour. Ce paramètre n'accepte aucune option max_uses, max_tokens ou caching, et les conseils sont transmis sous forme d'événements de fil dans 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