Exécution de code et Files API

Deux fonctionnalités se complètent ici. La Files API permet de téléverser un fichier une fois et de le citer ensuite par un identifiant. L’outil d’exécution de code permet à Claude d’écrire et de lancer du code dans un conteneur isolé. Ensemble, elles permettent de confier à Claude une analyse de données complète : on lui donne un fichier, il l’explore, calcule, trace des graphiques, et on récupère les fichiers produits.

La Files API

Au lieu d’encoder une image ou un PDF en base64 dans chaque requête, on le téléverse une fois et on reçoit un file_id :

file_object = client.files.upload(
    file=("streaming.csv", open("streaming.csv", "rb"), "text/csv"),
)
print(file_object.id)   # par exemple "file_011CNha8iCJcU1wXNR6q4V8w"

La Files API est sortie de bêta : plus besoin d’en-tête bêta, et le SDK passe par client.files au lieu de client.beta.files. Quelques repères de la documentation :

• un fichier pèse au plus 500 Mo, et une organisation dispose de 1 To ;
• téléverser, lister, télécharger et supprimer sont gratuits ; le contenu utilisé dans une requête est facturé comme des jetons d’entrée ;
• un fichier reste disponible jusqu’à sa suppression ou sa date d’expiration ;
• les fichiers sont partagés par tout l’espace de travail : n’acceptez jamais un file_id venu d’une source non fiable ;
• on ne télécharge que les fichiers produits par l’exécution de code ou par les Skills, pas ceux que l’on a téléversés.

L’outil d’exécution de code

C’est un outil serveur, comme la recherche web : on le déclare, et Anthropic exécute le code.

tools = [{"type": "code_execution_20250825", "name": "code_execution"}]

Le cours officiel utilise code_execution_20250522, une version ancienne limitée à Python. La version code_execution_20250825 ajoute les commandes Bash et la manipulation de fichiers ; code_execution_20260120 et code_execution_20260521 y ajoutent un état persistant entre les cellules Python et l’appel programmatique d’outils. Aucune version ne demande d’en-tête bêta.

Le conteneur :

• Python 3.11 sous Linux, avec les bibliothèques courantes de science des données préinstallées ;
• 5 Gio de mémoire, 5 Gio d’espace disque, un processeur ;
• aucun accès à Internet : impossible d’installer un paquet ou d’appeler une API pendant l’exécution ;
• une durée de vie de 30 jours.

Analyser un fichier

Le conteneur n’ayant pas accès au réseau, la Files API est le moyen d’y faire entrer des données et d’en faire sortir des résultats. On cite le fichier dans un bloc container_upload :

response = client.messages.create(
    model=model,
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": (
                "Analyse en détail les principaux facteurs de résiliation des abonnés. "
                "Produis au moins un graphique qui résume tes conclusions."
            )},
            {"type": "container_upload", "file_id": file_object.id},
        ],
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Claude écrit du code, l’exécute, lit le résultat, et recommence autant que nécessaire avant de conclure. La réponse contient :

• des blocs text, ses explications et ses conclusions ;
• des blocs server_tool_use, le code ou la commande lancés ;
• des blocs bash_code_execution_tool_result, avec stdout, stderr, return_code et la liste des fichiers produits.

Une analyse longue peut s’arrêter avec stop_reason à pause_turn : renvoyez alors la conversation telle quelle pour qu’elle reprenne, comme pour la recherche web.

Récupérer les fichiers produits

Chaque commande Bash dispose d’un dossier vide, $OUTPUT_DIR : les fichiers qu’elle y laisse sont capturés et renvoyés sous forme de file_id. Si votre application attend un fichier, demandez explicitement à Claude de l’enregistrer dans $OUTPUT_DIR.

for block in response.content:
    if block.type == "bash_code_execution_tool_result" and block.content.type == "bash_code_execution_result":
        for output in block.content.content:
            metadata = client.files.retrieve_metadata(output.file_id)
            client.files.download(output.file_id).write_to_file(metadata.filename)
            print("Téléchargé :", metadata.filename)

Le coût

L’exécution de code est facturée au temps, à part des jetons : chaque organisation dispose de 1 550 heures gratuites par mois, puis paie 0,05 dollar par heure et par conteneur, avec un minimum de 5 minutes par exécution. Si la requête contient des fichiers, ce temps est facturé même si l’outil n’est pas appelé, car les fichiers sont chargés dans le conteneur. L’exécution de code est gratuite quand la requête inclut aussi la recherche web ou la lecture de pages web dans leurs versions récentes.

Au-delà de l’analyse de données

Le même couple sert au traitement d’images, à la conversion ou à l’analyse de documents, aux calculs et aux modèles numériques, ou à la production de rapports mis en forme. Vous gardez la main sur ce qui entre et ce qui sort, par la Files API ; Claude fait le travail de programmation et d’itération entre les deux.

À vous de jouer

Une analyse de bout en bout. Téléversez un fichier CSV de votre choix, demandez une analyse avec au moins un graphique enregistré dans $OUTPUT_DIR, puis téléchargez les fichiers produits. Relisez les blocs server_tool_use pour voir le code exécuté, et vérifiez un chiffre de la conclusion en le recalculant vous-même.

Sources officielles : Code execution and the Files API (Claude Academy) · Code execution tool (documentation Claude : versions, conteneur, réponses, tarifs) · Files API (documentation Claude : limites, cycle de vie, sortie de bêta)

Points clés à retenir

• La Files API téléverse un fichier une fois et le cite par file_id ; elle n’est plus en bêta.
• L’exécution de code est un outil serveur : code_execution_20250825 exécute Bash et Python dans un conteneur sans Internet.
• On fait entrer un fichier avec un bloc container_upload, et on récupère les fichiers produits dans $OUTPUT_DIR.
• La réponse alterne texte, code lancé et résultats d’exécution.
• 1 550 heures gratuites par mois et par organisation, puis 0,05 dollar l’heure par conteneur.