Appel d'outils programmatique

L'appel d'outils programmatique permet à Claude d'écrire du code qui appelle vos outils de manière programmatique dans un conteneur d'exécution de code, plutôt que de nécessiter des allers-retours via le modèle pour chaque invocation d'outil. Cela réduit la latence pour les flux de travail multi-outils et diminue la consommation de tokens en permettant à Claude de filtrer ou de traiter les données avant qu'elles n'atteignent la fenêtre de contexte du modèle. Sur des benchmarks de recherche agentique comme BrowseComp et DeepSearchQA, qui testent la recherche web en plusieurs étapes et la récupération d'informations complexes, l'ajout de l'appel d'outils programmatique par-dessus les outils de recherche de base a été le facteur clé qui a pleinement libéré les performances des agents.

La différence s'amplifie rapidement dans les flux de travail réels. Considérez la vérification de la conformité budgétaire pour 20 employés : l'approche traditionnelle nécessite 20 allers-retours séparés avec le modèle, en extrayant des milliers de lignes de dépenses dans le contexte au passage. Avec l'appel d'outils programmatique, un seul script effectue les 20 recherches, filtre les résultats et ne renvoie que les employés ayant dépassé leurs limites, réduisant ce que Claude doit analyser de centaines de kilo-octets à quelques lignes.

Compatibilité des modèles

Pour les détails de compatibilité des modèles et des versions d'outils, voir la Référence des outils. L'appel d'outils programmatique est disponible via l'API Claude et Microsoft Foundry.

Démarrage rapide

Voici un exemple simple où Claude interroge programmatiquement une base de données plusieurs fois et agrège les résultats :

Fonctionnement de l'appel d'outils programmatique

Lorsque vous configurez un outil pour qu'il soit appelable depuis l'exécution de code et que Claude décide d'utiliser cet outil :

1. Claude écrit du code Python qui invoque l'outil comme une fonction, pouvant inclure plusieurs appels d'outils et une logique de pré/post-traitement
2. Claude exécute ce code dans un conteneur sandbox via l'exécution de code
3. Lorsqu'une fonction d'outil est appelée, l'exécution de code s'interrompt et l'API renvoie un bloc tool_use
4. Vous fournissez le résultat de l'outil, et l'exécution de code continue (les résultats intermédiaires ne sont pas chargés dans la fenêtre de contexte de Claude)
5. Une fois toute l'exécution de code terminée, Claude reçoit la sortie finale et continue à travailler sur la tâche

Cette approche est particulièrement utile pour :

• Le traitement de grandes quantités de données : Filtrer ou agréger les résultats des outils avant qu'ils n'atteignent le contexte de Claude
• Les flux de travail en plusieurs étapes : Économiser des tokens et réduire la latence en appelant les outils en série ou en boucle sans solliciter Claude entre les appels d'outils
• La logique conditionnelle : Prendre des décisions basées sur les résultats intermédiaires des outils

Concepts fondamentaux

Le champ allowed_callers

Le champ allowed_callers spécifie quels contextes peuvent invoquer un outil :

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

Valeurs possibles :

• ["direct"] - Seul Claude peut appeler cet outil directement (valeur par défaut si omis)
• ["code_execution_20260120"] - Uniquement appelable depuis l'exécution de code
• ["direct", "code_execution_20260120"] - Appelable à la fois directement et depuis l'exécution de code

Le champ caller dans les réponses

Chaque bloc d'utilisation d'outil inclut un champ caller indiquant comment il a été invoqué :

Invocation directe (utilisation traditionnelle des outils) :

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

Invocation programmatique :

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

Le tool_id fait référence à l'outil d'exécution de code qui a effectué l'appel programmatique.

Cycle de vie du conteneur

L'appel d'outils programmatique utilise les mêmes conteneurs que l'exécution de code :

• Création du conteneur : Un nouveau conteneur est créé pour chaque session, sauf si vous réutilisez un conteneur existant
• Expiration : Les conteneurs ont une durée de vie maximale de 30 jours et sont nettoyés après 4,5 minutes d'inactivité
• ID du conteneur : Renvoyé dans les réponses via le champ container
• Réutilisation : Passez l'ID du conteneur pour maintenir l'état entre les requêtes

Exemple de flux de travail

Voici comment fonctionne un flux complet d'appel d'outils programmatique :

Étape 1 : Requête initiale

Envoyez une requête avec l'exécution de code et un outil qui autorise l'appel programmatique. Pour activer l'appel programmatique, ajoutez le champ allowed_callers à la définition de votre outil.

La forme de la requête est identique à l'exemple du Démarrage rapide : incluez code_execution dans votre liste d'outils, ajoutez allowed_callers: ["code_execution_20260120"] à tout outil que vous souhaitez que Claude invoque depuis le code, et envoyez votre message utilisateur.

Étape 2 : Réponse de l'API avec appel d'outil

Claude écrit du code qui appelle votre outil. L'API s'interrompt et renvoie :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Étape 3 : Fournir le résultat de l'outil

Incluez l'historique complet de la conversation ainsi que le résultat de votre outil :

Étape 4 : Prochain appel d'outil ou fin d'exécution

L'exécution du code continue et traite les résultats. Si des appels d'outils supplémentaires sont nécessaires, répétez l'étape 3 jusqu'à ce que tous les appels d'outils soient satisfaits.

Étape 5 : Réponse finale

Une fois l'exécution du code terminée, Claude fournit la réponse finale :

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

Modèles avancés

Traitement par lots avec des boucles

Claude peut écrire du code qui traite plusieurs éléments efficacement :

async def _claude_code():
    regions = ["West", "East", "Central", "North", "South"]
    results = {}
    for region in regions:
        data = await query_database(f"<sql for {region}>")
        results[region] = sum(row["revenue"] for row in data)

    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Ce modèle :

• Réduit les allers-retours avec le modèle de N (un par région) à 1
• Traite les grands ensembles de résultats de manière programmatique avant de les renvoyer à Claude
• Économise des tokens en ne renvoyant que des conclusions agrégées au lieu des données brutes

Arrêt anticipé

Claude peut arrêter le traitement dès que les critères de succès sont atteints :

async def _claude_code():
    endpoints = ["us-east", "eu-west", "apac"]
    for endpoint in endpoints:
        status = await check_health(endpoint)
        if status == "healthy":
            print(f"Found healthy endpoint: {endpoint}")
            break  # Stop early, don't check remaining

Sélection conditionnelle d'outils

async def _claude_code():
    file_info = await get_file_info(path)
    if file_info["size"] < 10000:
        content = await read_full_file(path)
    else:
        content = await read_file_summary(path)
    print(content)

Filtrage des données

async def _claude_code():
    logs = await fetch_logs(server_id)
    errors = [log for log in logs if "ERROR" in log]
    print(f"Found {len(errors)} errors")
    for error in errors[-10:]:  # Only return last 10 errors
        print(error)

Format de réponse

Appel d'outil programmatique

Lorsque l'exécution du code appelle un outil :

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

Gestion du résultat de l'outil

Le résultat de votre outil est transmis au code en cours d'exécution :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

Fin de l'exécution du code

Lorsque tous les appels d'outils sont satisfaits et que le code se termine :

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

Gestion des erreurs

Erreurs courantes

Expiration du conteneur pendant un appel d'outil

Si votre outil met trop de temps à répondre, l'exécution du code reçoit une TimeoutError. Claude voit cela dans stderr et effectue généralement une nouvelle tentative :

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
    "return_code": 0,
    "content": []
  }
}

Pour éviter les délais d'expiration :

• Surveillez le champ expires_at dans les réponses
• Implémentez des délais d'expiration pour l'exécution de votre outil
• Envisagez de diviser les longues opérations en morceaux plus petits

Erreurs d'exécution d'outil

Si votre outil renvoie une erreur :

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Le code de Claude reçoit cette erreur et peut la gérer de manière appropriée.

Contraintes et limitations

Incompatibilités de fonctionnalités

• Sorties structurées : Les outils avec strict: true ne sont pas pris en charge avec l'appel programmatique
• Choix d'outil : Vous ne pouvez pas forcer l'appel programmatique d'un outil spécifique via tool_choice
• Utilisation parallèle d'outils : disable_parallel_tool_use: true n'est pas pris en charge avec l'appel programmatique

Restrictions sur les outils

Les outils suivants ne peuvent pas actuellement être appelés de manière programmatique, mais la prise en charge pourrait être ajoutée dans les versions futures :

• Les outils fournis par un connecteur MCP

Restrictions de formatage des messages

Lors de la réponse aux appels d'outils programmatiques, des exigences de formatage strictes s'appliquent :

Réponses contenant uniquement des résultats d'outils : S'il y a des appels d'outils programmatiques en attente de résultats, votre message de réponse doit contenir uniquement des blocs tool_result. Vous ne pouvez pas inclure de contenu textuel, même après les résultats des outils.

Invalide - Impossible d'inclure du texte lors de la réponse aux appels d'outils programmatiques :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Valide - Uniquement des résultats d'outils lors de la réponse aux appels d'outils programmatiques :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Cette restriction s'applique uniquement lors de la réponse aux appels d'outils programmatiques (exécution de code). Pour les appels d'outils côté client classiques, vous pouvez inclure du contenu textuel après les résultats des outils.

Limites de débit

Les appels d'outils programmatiques sont soumis aux mêmes limites de débit que les appels d'outils classiques. Chaque appel d'outil provenant de l'exécution de code compte comme une invocation distincte.

Valider les résultats des outils avant utilisation

Lors de l'implémentation d'outils définis par l'utilisateur qui seront appelés de manière programmatique :

• Les résultats des outils sont renvoyés sous forme de chaînes : Ils peuvent contenir n'importe quel contenu, y compris des extraits de code ou des commandes exécutables qui peuvent être traités par l'environnement d'exécution.
• Validez les résultats des outils externes : Si votre outil renvoie des données provenant de sources externes ou accepte des entrées utilisateur, soyez conscient des risques d'injection de code si la sortie sera interprétée ou exécutée en tant que code.

Efficacité des tokens

L'appel d'outil programmatique peut réduire considérablement la consommation de tokens :

• Les résultats des outils provenant d'appels programmatiques ne sont pas ajoutés au contexte de Claude - seule la sortie finale du code l'est
• Le traitement intermédiaire se fait dans le code - le filtrage, l'agrégation, etc. ne consomment pas de tokens du modèle
• Plusieurs appels d'outils dans une seule exécution de code - réduit la surcharge par rapport aux tours de modèle séparés

Par exemple, appeler 10 outils directement utilise environ 10 fois plus de tokens que de les appeler de manière programmatique et de renvoyer un résumé.

Utilisation et tarification

L'appel d'outil programmatique utilise la même tarification que l'exécution de code. Consultez la tarification de l'exécution de code pour plus de détails.

Bonnes pratiques

Conception des outils

• Fournissez des descriptions de sortie détaillées : Puisque Claude désérialise les résultats des outils dans le code, documentez clairement le format (structure JSON, types de champs, etc.)
• Renvoyez des données structurées : JSON ou d'autres formats facilement analysables fonctionnent mieux pour le traitement programmatique
• Gardez les réponses concises : Ne renvoyez que les données nécessaires pour minimiser la surcharge de traitement

Quand utiliser l'appel programmatique

Bons cas d'utilisation :

• Traitement de grands ensembles de données où vous n'avez besoin que d'agrégats ou de résumés
• Flux de travail en plusieurs étapes avec 3 appels d'outils dépendants ou plus
• Opérations nécessitant le filtrage, le tri ou la transformation des résultats des outils
• Tâches où les données intermédiaires ne devraient pas influencer le raisonnement de Claude
• Opérations parallèles sur de nombreux éléments (par exemple, vérification de 50 points de terminaison)

Cas d'utilisation moins idéaux :

• Appels d'outils uniques avec des réponses simples
• Outils nécessitant un retour immédiat de l'utilisateur
• Opérations très rapides où la surcharge de l'exécution de code dépasserait le bénéfice

Optimisation des performances

• Réutilisez les conteneurs lors de plusieurs requêtes liées pour maintenir l'état
• Regroupez les opérations similaires dans une seule exécution de code lorsque c'est possible

Dépannage

Problèmes courants

Erreur "Tool not allowed"

• Vérifiez que la définition de votre outil inclut "allowed_callers": ["code_execution_20260120"]

Expiration du conteneur

• Assurez-vous de répondre aux appels d'outils avant que le conteneur ne devienne inactif (4,5 minutes d'inactivité ; maximum absolu de 30 jours)
• Surveillez le champ expires_at dans les réponses
• Envisagez d'implémenter une exécution d'outil plus rapide

Résultat de l'outil non analysé correctement

• Assurez-vous que votre outil renvoie des données de type chaîne que Claude peut désérialiser
• Fournissez une documentation claire sur le format de sortie dans la description de votre outil

Conseils de débogage

1. Enregistrez tous les appels d'outils et leurs résultats pour suivre le flux
2. Vérifiez le champ caller pour confirmer l'invocation programmatique
3. Surveillez les identifiants de conteneur pour assurer une réutilisation correcte
4. Testez les outils indépendamment avant d'activer l'appel programmatique

Pourquoi l'appel d'outil programmatique fonctionne

La formation de Claude inclut une exposition extensive au code, ce qui le rend efficace pour raisonner et enchaîner les appels de fonctions. Lorsque les outils sont présentés comme des fonctions appelables dans un environnement d'exécution de code, Claude peut tirer parti de cette force pour :

• Raisonner naturellement sur la composition des outils : Enchaîner les opérations et gérer les dépendances aussi naturellement qu'en écrivant n'importe quel code Python
• Traiter efficacement les grands résultats : Filtrer les grandes sorties d'outils, extraire uniquement les données pertinentes, ou écrire les résultats intermédiaires dans des fichiers avant de renvoyer des résumés dans la fenêtre de contexte
• Réduire significativement la latence : Éliminer la surcharge liée au ré-échantillonnage de Claude entre chaque appel d'outil dans les flux de travail en plusieurs étapes

Cette approche permet des flux de travail qui seraient impraticables avec l'utilisation traditionnelle des outils (comme le traitement de fichiers de plus d'1 million de tokens) en permettant à Claude de travailler avec les données de manière programmatique plutôt que de tout charger dans le contexte de la conversation.

Implémentations alternatives

L'appel d'outil programmatique est un modèle généralisable qui peut être implémenté en dehors de l'exécution de code gérée par Anthropic. Voici un aperçu des approches :

Exécution directe côté client

Fournissez à Claude un outil d'exécution de code et décrivez les fonctions disponibles dans cet environnement. Lorsque Claude invoque l'outil avec du code, votre application l'exécute localement là où ces fonctions sont définies.

Avantages :

• Simple à implémenter avec une refactorisation minimale
• Contrôle total sur l'environnement et les instructions

Inconvénients :

• Exécute du code non fiable en dehors d'un bac à sable
• Les invocations d'outils peuvent être des vecteurs d'injection de code

À utiliser lorsque : Votre application peut exécuter du code arbitraire en toute sécurité, vous souhaitez une solution simple, et l'offre gérée d'Anthropic ne correspond pas à vos besoins.

Exécution en bac à sable auto-géré

Même approche du point de vue de Claude, mais le code s'exécute dans un conteneur en bac à sable avec des restrictions de sécurité (par exemple, pas d'accès réseau sortant). Si vos outils nécessitent des ressources externes, vous aurez besoin d'un protocole pour exécuter les appels d'outils en dehors du bac à sable.

Avantages :

• Appel d'outil programmatique sécurisé sur votre propre infrastructure
• Contrôle total sur l'environnement d'exécution

Inconvénients :

• Complexe à construire et à maintenir
• Nécessite la gestion à la fois de l'infrastructure et de la communication inter-processus

À utiliser lorsque : La sécurité est critique et la solution gérée d'Anthropic ne correspond pas à vos exigences.

Exécution gérée par Anthropic

L'appel d'outil programmatique d'Anthropic est une version gérée de l'exécution en bac à sable avec un environnement Python opinionné optimisé pour Claude. Anthropic gère la gestion des conteneurs, l'exécution du code et la communication sécurisée des invocations d'outils.

Avantages :

• Sécurisé par défaut
• Facile à activer avec une configuration minimale
• Environnement et instructions optimisés pour Claude

Envisagez d'utiliser la solution gérée d'Anthropic si vous utilisez l'API Claude.

Conservation des données

L'appel d'outil programmatique est construit sur l'infrastructure d'exécution de code et utilise les mêmes conteneurs en bac à sable. Les données des conteneurs, y compris les artefacts d'exécution et les sorties, sont conservées jusqu'à 30 jours.

Pour l'éligibilité ZDR sur toutes les fonctionnalités, consultez API et conservation des données.

Fonctionnalités associées