Exécution de code et API Fichiers : déléguer des tâches complexes

L’API Anthropic propose deux fonctionnalités puissantes qui fonctionnent remarquablement bien ensemble : l’API Fichiers (Files API) et l’exécution de code (Code Execution). Combinées, elles permettent de déléguer à Claude des tâches de calcul et d’analyse complexes.

L’API Fichiers (Files API)

L’API Fichiers offre une alternative à l’encodage base64 direct des fichiers dans vos messages. Le principe :

1. Uploader votre fichier (image, PDF, texte, etc.) vers Claude via un appel API séparé
2. Recevoir un objet de métadonnées contenant un identifiant unique du fichier
3. Référencer cet identifiant dans vos messages futurs au lieu d’inclure les données brutes

Cette approche est particulièrement utile quand :

• Vous voulez référencer le même fichier dans plusieurs requêtes
• Vous travaillez avec des fichiers volumineux qu’il serait penible d’inclure dans chaque requête

L’outil d’exécution de code

L’exécution de code est un outil côté serveur qui ne nécessite aucune implémentation de votre part. Vous incluez simplement un schéma d’outil predefini dans votre requête, et Claude peut exécuter du code Python dans un conteneur Docker isolé.

Caractéristiques clés de l’environnement d’exécution :

• Tourne dans un conteneur Docker isolé
• Pas d’accès réseau (impossible de faire des appels API externes)
• Claude peut exécuter du code plusieurs fois au cours d’une même conversation
• Les résultats sont captures et interprétés par Claude pour la réponse finale

Combiner les deux : la vraie puissance

La force de cette combinaison vient du fait que les conteneurs Docker n’ont pas d’accès réseau. L’API Fichiers devient donc le moyen principal de faire entrer et sortir des données de l’environnement d’exécution.

Workflow typique

1. Uploader votre fichier de données (ex: un CSV) via l’API Fichiers
2. Inclure un bloc container_upload dans votre message avec l’identifiant du fichier
3. Demander à Claude d’analyser les données
4. Claude écrit et exécute du code pour traiter votre fichier
5. Claude peut générer des sorties (graphiques, rapports) que vous pouvez télécharger

Exemple pratique : analyse de données streaming

Prenons un cas concret avec un fichier CSV contenant des données utilisateurs d’un service de streaming : niveaux d’abonnement, habitudes de visionnage, taux de désabonnement (churn).

Étape 1 : uploader le fichier

file_metadata = upload('streaming.csv')

Étape 2 : créer le message avec le fichier et la demande d’analyse

messages = []
add_user_message(
    messages,
    [
        {
            "type": "text",
            "text": """Effectue une analyse detaillee pour identifier
            les principaux facteurs de desabonnement.
            Ton output final doit inclure au moins un graphique
            detaille resumant tes conclusions."""
        },
        {"type": "container_upload", "file_id": file_metadata.id},
    ],
)

chat(
    messages,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}]
)

Comprendre la réponse

Quand Claude utilise l’exécution de code, la réponse contient plusieurs types de blocs :

• Blocs texte : l’analyse et les explications de Claude
• Blocs server_tool_use : le code que Claude à décide d’exécuter
• Blocs code_execution_result : les sorties de l’exécution du code

Claude peut exécuter du code plusieurs fois dans une même réponse, en construisant itérativement son analyse. Chaque cycle d’exécution comprend le code et ses résultats.

Télécharger les fichiers générés

L’une des fonctionnalités les plus utiles : Claude peut générer des fichiers (graphiques, rapports) et les rendre disponibles au téléchargement. Quand Claude crée une visualisation, elle est stockée dans le conteneur et récupérable via l’API Fichiers.

Cherchez les blocs de type code_execution_output dans la réponse — ils contiennent les identifiants des fichiers générés :

download_file("file_id_from_response")

Le résultat : une analyse complète avec des visualisations professionnelles qui aurait demande un effort de codage considérable à faire manuellement.

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

La combinaison API Fichiers + exécution de code ouvre de nombreuses possibilités :

• Traitement et manipulation d’images
• Parsing et transformation de documents
• Calculs mathématiques et modélisation
• Génération de rapports avec mise en forme personnalisée

L’idée centrale : vous pouvez déléguer des tâches computationnelles complexes à Claude tout en gardant le contrôle sur les entrées et sorties via l’API Fichiers. Claude devient un assistant de programmation capable d’exécuter et itérer sur des solutions.

Exercice : analyser vos propres données

1. Préparez un fichier CSV avec des données que vous souhaitez analyser
2. Uploadez-le via l’API Fichiers
3. Demandez à Claude d’effectuer une analyse exploratoire avec au moins un graphique
4. Récupérez le graphique généré via download_file()
5. Expérimentez avec des demandes d’analyses de plus en plus spécifiques