Claude Advisor Tool : intégration Python et TypeScript pour PME 2026

Q: Comment monitorer le coût réel d'une requête Advisor Tool en production ?

La réponse API expose un champ `usage.iterations[]` qui détaille chaque sub-inférence : `type: "message"` pour l'executor, `type: "advisor_message"` pour l'advisor (avec le modèle utilisé). Chaque iteration contient `input_tokens`, `output_tokens`, `cache_read_input_tokens`. Pour calculer le coût d'une requête : multipliez les tokens de chaque iteration par le tarif du modèle correspondant (Sonnet ou Opus 4.7), additionnez. Important : les top-level `output_tokens` ne reflètent que l'executor — les tokens advisor sont billés à part au tarif Opus, c'est volontaire.

Q: Quand activer le `caching` de l'advisor (TTL 5m ou 1h) ?

Le break-even du caching advisor est ~3 appels par conversation. En dessous, le coût d'écriture du cache excède l'économie sur les lectures. Au-dessus, l'économie devient nette. Recommandation pratique : activer `caching: {"type": "ephemeral", "ttl": "5m"}` pour les agents long-running coding ou recherche multi-tour, garder `null` pour les pipelines mono-turn. À noter : l'option `clear_thinking` avec une valeur de `keep` autre que `"all"` casse le cache advisor — pour les modèles Opus 4.5+/Sonnet 4.6+, le défaut est déjà `keep: all`, c'est OK ; sur les modèles antérieurs, il faut le configurer explicitement.

L’Advisor Tool d’Anthropic, en beta publique depuis le 9 avril 2026, change la manière concrète dont une PME peut intégrer Opus 4.7 dans une boucle d’agent piloté par Sonnet 4.6 ou Haiku 4.5. Au lieu de router au niveau applicatif (un appel API à Sonnet, puis un autre à Opus, puis un retour à Sonnet), c’est désormais un server-side tool call géré par Anthropic — l’executor décide quand consulter l’advisor, le serveur Anthropic exécute la sub-inférence, et la réponse revient dans le même flux /v1/messages. Pour une PME qui a déjà un agent Claude en production, intégrer l’Advisor Tool prend littéralement quinze lignes de code Python ou TypeScript. Voici les détails opérationnels.

Ce qui change dans le contrat API

L’Advisor Tool n’est pas un nouveau modèle ni un nouveau endpoint — c’est un tool type que vous ajoutez à votre tableau tools dans /v1/messages, avec deux paramètres obligatoires :

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-7"
}

Côté requête, deux choses à savoir :

Header beta obligatoire : anthropic-beta: advisor-tool-2026-03-01 (ou betas: ["advisor-tool-2026-03-01"] côté SDK).
Pairage executor/advisor strict : seules quatre combinaisons sont valides en mai 2026 — l’advisor doit être au moins aussi capable que l’executor.

Modèle exécuteur	Modèle advisor possible
Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)	Claude Opus 4.7 (`claude-opus-4-7`)
Claude Sonnet 4.6 (`claude-sonnet-4-6`)	Claude Opus 4.7 (`claude-opus-4-7`)
Claude Opus 4.6 (`claude-opus-4-6`)	Claude Opus 4.7 (`claude-opus-4-7`)
Claude Opus 4.7 (`claude-opus-4-7`)	Claude Opus 4.7 (`claude-opus-4-7`)

Une combinaison invalide retourne 400 invalid_request_error avec le nom de la paire interdite.

Quickstart Python — 15 lignes en production

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

Pas de boucle agent à écrire, pas de routing manuel. L’executor (Sonnet 4.6 ici) décide quand invoquer l’advisor sur la base de son built-in tool description. Le serveur Anthropic exécute Opus 4.7 sur le transcript complet — system prompt, tool definitions, tous les tours précédents et tous les tool results — et l’executor continue informé.

Quickstart TypeScript — équivalent

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

Le SDK officiel @anthropic-ai/sdk gère automatiquement le header beta et le typage strict des tool params.

Comment ça se déroule côté serveur

Quand l’executor décide d’invoquer l’advisor, la mécanique interne est la suivante :

sequenceDiagram
    participant Client
    participant Executor as Executor (Sonnet 4.6)
    participant Server as Anthropic server
    participant Advisor as Advisor (Opus 4.7)

    Client->>Executor: messages.create with advisor tool
    Executor->>Server: server_tool_use (name: advisor, input: {})
    Server->>Advisor: full transcript transmis
    Advisor->>Server: advice text (400-700 tokens)
    Server->>Executor: advisor_tool_result block
    Executor->>Client: text response continue

Quatre étapes :

L’executor émet un server_tool_use avec name: "advisor" et input: {} vide. C’est l’executor qui décide du timing ; le serveur fournit le contexte.
Anthropic exécute une sub-inférence séparée sur Opus 4.7, en passant tout le transcript de l’executor (system prompt, tools, prior turns, tool results).
La réponse de l’advisor revient sous forme d’un advisor_tool_result block.
L’executor continue sa génération, informé par l’advice.

Le tout dans un seul appel /v1/messages. Pas de round trip supplémentaire côté client.

Monitoring de coût : la mécanique `usage.iterations`

C’est probablement le détail le plus important pour une PME : la facturation Advisor Tool est transparente et auditable. Chaque réponse expose un tableau usage.iterations[] qui détaille les tokens par sub-inférence :

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

Lecture clé :

Les iterations type: "message" sont billées au tarif executor (Sonnet 4.6 dans cet exemple).
Les iterations type: "advisor_message" sont billées au tarif advisor (Opus 4.7) et incluent le model utilisé pour audit.
Les top-level input_tokens et output_tokens ne reflètent que l’executor — les tokens advisor sont comptabilisés à part car billés à un tarif différent.

Code Python pour calculer le coût total d’une réponse

def estimate_cost(usage, executor_model="claude-sonnet-4-6", advisor_model="claude-opus-4-7"):
    # Tarifs officiels Anthropic 2026 ($/MTok). Vérifiez sur platform.claude.com/docs/en/about-claude/pricing
    rates = {
        "claude-sonnet-4-6":  {"input": 3,  "output": 15},
        "claude-opus-4-7":    {"input": 5,  "output": 25},  # identique à Opus 4.6
        "claude-haiku-4-5-20251001": {"input": 1, "output": 5},
    }
    total = 0.0
    for it in usage.iterations:
        if it.type == "message":
            r = rates[executor_model]
            total += it.input_tokens / 1e6 * r["input"]
            total += it.output_tokens / 1e6 * r["output"]
        elif it.type == "advisor_message":
            r = rates[it.model]
            total += it.input_tokens / 1e6 * r["input"]
            total += it.output_tokens / 1e6 * r["output"]
    return total

Patch ce helper dans votre code de monitoring (LangFuse, Helicone, Datadog), et vous obtenez un coût par requête au cent près. Pour des patterns plus larges sur la maîtrise des coûts API Claude en PME, voir le guide coût Claude API monitoring budgets.

Cost control concret en 2026

Anthropic documente trois mécaniques de cost control natives :

1. `max_uses` sur la tool definition

Cap le nombre d’appels advisor par requête :

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

Au-delà du cap, les appels suivants retournent error_code: "max_uses_exceeded" et l’executor continue sans advice.

2. Caching ephemeral pour les conversations longues

tools=[{
    "type": "advisor_20260301",
    "name": "advisor",
    "model": "claude-opus-4-7",
    "caching": {"type": "ephemeral", "ttl": "5m"},  # ou "1h"
}]

Break-even ≈ 3 appels par conversation. Sous ce seuil, le coût d’écriture cache excède l’économie sur les lectures. Au-dessus, l’économie devient nette. Pour un agent long-running coding qui consulte l’advisor 5-10 fois sur une session, l’activation se justifie. Le pattern advisor cohabite proprement avec le prompt caching natif Claude API côté executor.

3. Cap conversation-level côté client

L’API ne fournit pas de cap conversation-level natif (juste request-level via max_uses). Pour une borne globale, comptez côté client et retirez le tool de votre tools array dès que vous atteignez votre plafond — en pensant à strip aussi les blocks advisor_tool_result de l’historique pour éviter un 400 invalid_request_error.

Sécurité et validation prompt injection

Une question fréquente côté PME : est-ce que l’advisor est exposé au prompt injection ? Réponse nuancée :

L’advisor reçoit le transcript complet de l’executor — donc oui, si un user message ou un tool result contient une instruction adversaire, elle est visible par l’advisor.
L’advisor n’a pas accès aux tools lui-même (seulement le transcript). Il ne peut donc pas lui-même déclencher d’action néfaste — il peut seulement recommander une action néfaste à l’executor.
C’est l’executor qui exécute les actions. La même surface de prompt injection que dans n’importe quel agent Claude s’applique — la mitigation se fait au niveau executor (output filtering, sandboxing, validation tool calls).

Pour les patterns de défense complets contre la prompt injection en production PME, voir notre guide prompt injection Claude MCP PME 2026 — le pattern advisor n’augmente pas la surface d’attaque, mais ne la réduit pas non plus.

Combinaison avec les autres outils

L’Advisor Tool composent proprement avec les autres tools server-side ou client-side. Configuration multi-tool typique :

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

L’executor peut faire web search, consulter l’advisor, exécuter du bash dans le même tour. Le plan de l’advisor peut piloter quels tools l’executor utilise ensuite.

Streaming : ce qu’il faut savoir

L’advisor sub-inférence ne stream pas. Le stream de l’executor met en pause pendant l’exécution advisor, puis le résultat arrive en un seul event :

server_tool_use block (name: advisor) → début de la pause
Pause silencieuse (avec keepalive SSE ping toutes ~30 s)
content_block_start avec le advisor_tool_result complet
message_delta avec usage.iterations mis à jour
L’output executor reprend son streaming

Pour une UI en streaming, prévoir un indicateur « consultation expert » pendant la pause améliore l’UX.

Best practices de prompting Advisor

La doc officielle inclut un prompt système recommandé pour les tâches de coding qui peut directement être copié en PME. Deux principes :

Appeler l’advisor TÔT — après les premiers reads exploratoires, avant tout travail substantiel.
Appeler l’advisor une dernière fois avant de déclarer fini — mais après avoir rendu durable le livrable (fichier écrit, commit fait).

Suggested system prompt blocks (Anthropic) :
"Call advisor BEFORE substantive work — before writing, before committing
to an interpretation, before building on an assumption. Orientation is
not substantive work. Writing, editing, and declaring an answer are.
Also call advisor: when stuck, when considering a change of approach,
when you believe the task is complete (after making it durable)."

Anthropic documente aussi qu’ajouter une instruction de concision — « The advisor should respond in under 100 words and use enumerated steps, not explanations » — réduit le coût total advisor de 35-45 % sans changer la fréquence d’appel.

Pairage avec les Effort settings

Pour les tâches coding, Anthropic recommande explicitement le pairage Sonnet executor en effort medium + Opus advisor. Cette combinaison atteint une intelligence comparable à Sonnet en effort default, à coût inférieur. Pour la plus haute intelligence absolue, garder l’executor en effort default.

client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    extra_headers={"anthropic-effort": "medium"},  # syntaxe selon SDK
    tools=[{"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7"}],
    messages=[...]
)

Limites à connaître en mai 2026

Beta : header advisor-tool-2026-03-01 requis ; comportements peuvent évoluer entre releases.
Pas de stream sur l’advisor : la sub-inférence est atomique.
Pas de cap conversation-level natif : à compter côté client.
max_tokens ne borne que l’executor : l’advisor a son propre quota interne.
Anthropic Priority Tier non transitif : Priority Tier sur l’executor ne s’étend pas à l’advisor — il faut Priority Tier sur Opus 4.7 pour bénéficier de la priorité advisor.

Trois recommandations pour intégrer l’Advisor Tool en PME 2026

Démarrer sur un workload coding ou recherche multi-step — c’est là que l’Advisor Tool brille. Anthropic publie des gains de +2,7 points sur SWE-bench Multilingual (Sonnet 4.6 + Opus 4.6 advisor : 74,8 % vs 72,1 % Sonnet seul) à −11,9 % de coût par tâche agentique selon les benchmarks publiés à la formalisation de l’Advisor Tool en avril 2026. Pour les patterns multi-agents complets, voir le guide architecture multi-agents Haiku 4.5 + Sonnet 4.6 cost-perf qui couvre le routing global au-delà de l’advisor.
Instrumenter usage.iterations dès le 1er appel en prod — le helper Python ci-dessus dans votre logger / dashboard donne un coût par requête au cent près. Sans ça, vous perdez la visibilité fine que l’API expose nativement.
Activer le caching advisor au-delà de 3 appels par conversation — pour les agents codeur ou recherche long-running, c’est l’optimisation la plus simple à activer (1 ligne JSON), avec ROI net immédiat.

Le pattern advisor-executor existait conceptuellement en 2025 (deux appels API distincts orchestrés côté client). Sa formalisation sous forme de tool server-side managé par Anthropic en avril 2026 supprime le boilerplate et expose le contexte complet à l’advisor — c’est ce qui le rend opérationnellement décisif pour des PME qui ne veulent pas écrire un orchestrateur custom.

FAQ

L’Advisor Tool est-il éligible Zero Data Retention pour une PME RGPD-sensible ?

Oui. La documentation officielle Anthropic le confirme explicitement : « This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned ». Pour les PME en secteur santé, finance ou légal, c’est un point différenciateur fort par rapport à Managed Agents (où la situation ZDR n’est pas explicite à ce stade). Un contrat ZDR avec Anthropic reste un prérequis commercial.

Comment monitorer le coût réel d’une requête Advisor Tool en production ?

La réponse API expose un champ usage.iterations[] qui détaille chaque sub-inférence : type: "message" pour l’executor, type: "advisor_message" pour l’advisor (avec le modèle utilisé). Chaque iteration contient input_tokens, output_tokens, cache_read_input_tokens. Pour calculer le coût d’une requête : multipliez les tokens de chaque iteration par le tarif du modèle correspondant (Sonnet ou Opus 4.7), additionnez. Important : les top-level output_tokens ne reflètent que l’executor — les tokens advisor sont billés à part au tarif Opus, c’est volontaire.

Quand activer le `caching` de l’advisor (TTL 5m ou 1h) ?

Le break-even du caching advisor est environ 3 appels par conversation. En dessous, le coût d’écriture du cache excède l’économie sur les lectures. Au-dessus, l’économie devient nette. Recommandation pratique : activer caching: {"type": "ephemeral", "ttl": "5m"} pour les agents long-running coding ou recherche multi-tour, garder null pour les pipelines mono-turn. À noter : l’option clear_thinking avec une valeur de keep autre que "all" casse le cache advisor — pour les modèles Opus 4.5+/Sonnet 4.6+, le défaut est déjà keep: all, c’est OK ; sur les modèles antérieurs, il faut le configurer explicitement.

L’Advisor Tool fonctionne-t-il avec les Anthropic Managed Agents ?

À ce jour (mai 2026), la documentation officielle indique que l’Advisor Tool est exposé sur la Messages API. Sur Managed Agents, le harness gère sa propre orchestration via Agent + Environment + Session — l’intégration directe de l’Advisor Tool dans Managed Agents n’est pas explicitement documentée. Pour un workflow PME en production : si vous utilisez la Messages API directement, l’Advisor Tool est immédiat ; si vous utilisez Managed Agents, validez d’abord avec le support Anthropic la compatibilité advisor + agent toolset 20260401.

Quelle est la différence pratique entre Advisor Tool et un appel API à Opus en parallèle ?

L’Advisor Tool fait économiser deux choses : (1) le boilerplate d’orchestration côté votre code (vous n’avez plus à gérer une boucle « si confiance < seuil → appeler Opus → re-injecter dans Sonnet ») ; (2) le passage du contexte complet — l’advisor reçoit automatiquement le transcript sans que vous ayez à le sérialiser et le repasser. En contrepartie, vous perdez en flexibilité : vous ne contrôlez pas le système prompt de l’advisor, pas le timing exact d’invocation (c’est l’executor qui décide). Pour une intégration production rapide, l’Advisor Tool est plus simple ; pour un contrôle fin, l’orchestration manuelle reste valable.