Outil Claude Advisor : associez un exécuteur rapide à un planificateur plus intelligent

Vous disposez d’un agent de codage exécutant Sonnet. Il gère 90% des tours sans effort : lecture de fichiers, exécuter des tests, écrire un passe-partout. Mais lorsqu'il s'agit d'une décision d'architecture délicate ou d'une concurrence subtile bug, vous souhaiteriez qu'il puisse téléphoner à un ami.

C'est l'outil Conseiller. La nouvelle fonctionnalité API bêta d'Anthropic permet un modèle d'exécuteur plus rapide (Sonnet ou Haiku) appelons un modèle de conseiller en intelligence supérieure (Opus) de mi-génération. Le conseiller lit la transcription complète, produit un court plan ou une correction de cap, et l'exécuteur continue la tâche. Une requête API, deux modèles, une qualité proche de l'Opus au prix Sonnet.

Comment fonctionne l'outil de conseiller

Lorsque vous ajoutez l'outil de conseiller à votre tools tableau, l'exécuteur décide quand l'appeler, comme n'importe quel autre outil. Le flux :

1. L'exécuteur émet un server_tool_use bloquer avec name: "advisor" et un vide input.
2. Anthropic exécute une passe d'inférence distincte côté serveur du modèle de conseiller, transmettant la transcription complète de l'exécuteur (invite système, définitions d'outils, tous les tours et résultats précédents).
3. La réponse du conseiller revient sous la forme d'un advisor_tool_result bloc (généralement 400 à 700 jetons de texte).
4. L'exécuteur continue de générer, informé par l'avis.

Tout cela se passe dans un seul /v1/messages demande. Pas d’allers-retours supplémentaires de votre côté. Le conseiller fonctionne sans outils et sans gestion de contexte ; ses blocs de réflexion sont abandonnés et seulement le texte de l'avis parvient à l'exécuteur testamentaire.

Votre premier appel de conseiller : curl, Python et TypeScript

L'outil de conseiller est en version bêta. Inclure le advisor-tool-2026-03-01 en-tête bêta dans vos demandes. Voici l'appel le plus simple possible :

boucle

curl https://api.anthropic.com/v1/messages \\
  --header "x-api-key: \$ANTHROPIC_API_KEY" \\
  --header "anthropic-version: 2023-06-01" \\
  --header "anthropic-beta: advisor-tool-2026-03-01" \\
  --header "content-type: application/json" \\
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6"
      }
    ],
    "messages": [{
      "role": "user",
      "content": "Build a concurrent worker pool in Go with graceful shutdown."
    }]
  }'

Python

import anthropic

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-6",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

Manuscrit

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await 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-6",
    },
  ],
  messages: [
    {
      role: "user",
      content: "Build a concurrent worker pool in Go with graceful shutdown.",
    },
  ],
});

console.log(response);

À quoi ressemble la réponse

Un appel réussi au conseiller produit quatre blocs de contenu : le texte initial de l'exécuteur, le server_tool_use bloquer, le advisor_tool_result bloc, et celui de l'exécuteur résultat final éclairé par les conseils.

{
  "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. Close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation using a channel-based coordination pattern..."
    }
  ]
}

La advisor_tool_result le contenu a deux variantes : advisor_result avec texte en clair des conseils, et advisor_redacted_result avec du contenu crypté. Dans les deux cas, effectuez un aller-retour contenu textuellement lors des tours suivants.

Paires de modèles valides

Le conseiller doit être au moins aussi compétent que l'exécuteur testamentaire. Les paires invalides renvoient un 400 erreur.

L'endroit idéal pour la plupart des charges de travail : Sonnet comme exécuteur testamentaire, Opus comme conseiller. Vous bénéficiez d'un ascenseur de qualité à coût total similaire ou inférieur à celui de l'exécution d'Opus pour chaque jeton.

Conversations à plusieurs tours

Transmettez le contenu complet de l'assistant, y compris advisor_tool_result blocs, retour à l'API sur tours suivants. Si vous omettez l'outil de conseiller de tools lors d'un tour de suivi alors que le l'historique des messages contient toujours advisor_tool_result blocs, l'API renvoie un 400.

import anthropic

client = anthropic.Anthropic()

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

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

# First turn: executor calls advisor, builds the worker pool
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Pass back the full response content (including advisor_tool_result blocks)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

# Second turn: executor has context from first advisor call
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Ingénierie rapide pour les agents de codage

L'outil de conseil est livré avec une description intégrée qui incite l'exécuteur testamentaire à l'appeler au début. de tâches complexes. Pour les charges de travail de codage et d'agent, vous pouvez améliorer les résultats avec une invite système qui renforce deux timings :

• Un premier appel précoce d'un conseiller, après quelques lectures exploratoires figure dans la transcription
• Un dernier appel du conseiller après que les écritures du fichier et les résultats des tests soient dans la transcription

Voici le modèle d'invite système recommandé par Anthropic pour les tâches de codage. Il a produit le plus haut des renseignements à un coût proche de celui de Sonnet dans les évaluations internes :

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.

Call advisor BEFORE substantive work: before writing, before committing
to an interpretation, before building on an assumption.

Also call advisor:
- When you believe the task is complete (save your deliverable first)
- When stuck: errors recurring, approach not converging
- When considering a change of approach

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

Combinaison avec d'autres outils

L'outil Advisor compose avec la recherche sur le Web, l'exécution de code et vos outils personnalisés en même temps. tools tableau. L'exécuteur peut effectuer des recherches sur le Web, appeler le conseiller et utiliser vos outils dans le même tour. Le plan du conseiller peut indiquer les outils que l'exécuteur testamentaire utilisera ensuite.

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Mise en cache des invites du conseiller

Deux couches de mise en cache indépendantes sont disponibles. La mise en cache côté exécuteur fonctionne de la même manière que n'importe quel bloc de contenu : placer un cache_control point d'arrêt après un advisor_tool_result et ça frappe.

La mise en cache côté conseiller maintient la transcription du conseiller en cache pour tous les appels au sein de la même conversation. Activez-le avec un caching champ sur la définition de l'outil :

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

L'écriture dans le cache coûte plus cher que l'économie de lecture lorsque le conseiller est appelé deux fois ou moins. La mise en cache atteint le seuil de rentabilité après environ trois appels de conseiller et s'améliore à partir de là. Activez-le pendant longtemps boucles d'agents ; gardez-le pour des tâches courtes.

Répartition de l'utilisation et de la facturation

Les appels au conseiller s'exécutent comme une sous-inférence distincte facturée aux tarifs du modèle du conseiller. Le usage.iterations array vous donne une répartition par itération :

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-4-6",
        "input_tokens": 823,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "output_tokens": 442
      }
    ]
  }
}

Niveau supérieur usage les champs reflètent uniquement les jetons de l’exécuteur. Itérations avec type: "advisor_message" sont facturés aux tarifs du modèle conseiller. Utilisez le iterations tableau lors de la création d’une logique de suivi des coûts.

Maîtrise des coûts : plafonnement des appels aux conseillers

L’outil de conseiller n’a pas de plafond intégré au niveau des conversations. Utiliser max_uses sur l'outil définition des limites par demande. Pour les limites au niveau des conversations, comptez les appels côté client et désactivez le conseiller lorsque vous atteignez votre plafond :

# Track advisor calls client-side
advisor_count = 0
MAX_ADVISOR_CALLS = 5

for turn in conversation:
    response = client.beta.messages.create(...)

    # Count advisor calls in response
    for block in response.content:
        if block.type == "server_tool_use" and block.name == "advisor":
            advisor_count += 1

    if advisor_count >= MAX_ADVISOR_CALLS:
        # Remove advisor tool and strip advisor_tool_result blocks
        tools = [t for t in tools if t.get("name") != "advisor"]
        for msg in messages:
            if msg["role"] == "assistant":
                msg["content"] = [
                    b for b in msg["content"]
                    if b.get("type") not in ("server_tool_use", "advisor_tool_result")
                    or b.get("name") != "advisor"
                ]

Gestion des erreurs

Si l'appel du conseiller échoue, le résultat comporte un advisor_tool_result_error avec un error_code. L'exécuteur voit l'erreur et continue sans avis ; la demande lui-même n’échoue pas.

Comportement de streaming

La sous-inférence du conseiller n'est pas diffusée en continu. Le flux de l'exécuteur s'arrête pendant que le conseiller s'exécute, puis le plein advisor_tool_result arrive en un seul content_block_start événement. Les keepalives ping SSE se déclenchent toutes les 30 secondes pendant la pause. Prévoyez 2 à 5 secondes de silence par appel au conseiller, en fonction de la longueur de la transcription.

Quand le conseiller aide (et quand il ne l'aide pas)

Limites à connaître

• La sortie du conseiller n’est pas diffusée. Attendez-vous à une pause pendant la sous-inférence.
• Pas de limite intégrée de niveau de conversation sur les appels du conseiller. Suivez-les et limitez-les côté client.
• max_tokens s'applique uniquement à la sortie de l'exécuteur. Il ne limite pas les jetons de conseiller.
• Le niveau de priorité accordé à l'exécuteur testamentaire ne s'étend pas au conseiller ; vous en avez besoin sur les deux modèles.
• La fonctionnalité est en version bêta. Inclure anthropic-beta: advisor-tool-2026-03-01 dans chaque demande.