Votre agent IA peut maintenant écrire et exécuter du code : voici comment faire

POURQUOI UN AGENT QUI EXÉCUTE DU CODE CHANGE TOUT

Imaginez un agent IA qui ne se contente pas de répondre à vos questions, mais qui peut aussi ouvrir un fichier Excel, écrire un programme pour analyser les données, et vous envoyer un graphique avec les anomalies détectées. L'exécution de code transforme un simple chatbot en un assistant ultra-puissant capable de réaliser des tâches concrètes.

Avec cette capacité, un agent peut inspecter des jeux de données, écrire de la logique de traitement, ou produire des fichiers utiles pour d'autres outils. Les applications possibles deviennent presque illimitées : analyse financière, détection de fraudes, automatisation de rapports, ou même Génération de code pour d'autres programmes.

Dans ce tutoriel, vous allez apprendre à construire un tel agent en utilisant le OpenAI Agents SDK et Docker. Nous allons d'abord comprendre les bases, puis passer à un cas pratique où l'agent analyse un fichier CSV de consommation énergétique d'un bâtiment. Enfin, nous verrons comment réutiliser cette méthode pour d'autres projets.

LES TROIS PIÈCES QUI FONT FONCTIONNER UN AGENT CODEUR

Un agent capable d'exécuter du code repose sur trois éléments clés : le modèle de langage, l'espace de travail et l'environnement d'exécution.

Le modèle de langage (comme gpt-5.4) est le cerveau de l'agent. Il décide quoi faire, écrit le code nécessaire, et interprète les résultats. Mais il ne peut pas exécuter ce code lui-même : c'est là qu'intervient l'environnement d'exécution.

L'espace de travail est comme un bureau virtuel où l'agent dépose ses fichiers d'entrée (un CSV, un PDF, un dossier de documents) et récupère ses productions (un rapport, un graphique, un tableau). L'utilisateur y place ses données, l'agent y travaille, et les résultats finaux y sont stockés.

L'environnement d'exécution est la machine temporaire où le code s'exécute. Il peut s'agir d'un service hébergé par la plateforme ou d'un conteneur Docker que vous contrôlez. Docker est souvent le choix par défaut pour isoler l'exécution et éviter que le code ne touche à votre ordinateur.

CONTRÔLE TOTAL : DÉFINIR LES RÈGLES DU JEU

Avant de construire l'agent, il faut décider comment le contrôler à chaque niveau :

Au niveau du modèle : quelles instructions donner à l'agent ? Quels artefacts doit-il produire (un rapport, un graphique, un tableau) ?

Au niveau de l'espace de travail : quels fichiers doivent être disponibles ? Quels fichiers finaux doivent être récupérés après l'exécution ?

Au niveau de l'environnement : quelles bibliothèques Python doivent être installées ? L'agent a-t-il accès à internet ou au shell de la machine ?

Dans l'OpenAI Agents SDK, la classe SandboxAgent combine ces trois éléments en un seul outil prêt à l'emploi. Voici comment l'utiliser.

ÉTAPE 1 : PRÉPARER L'ESPACE DE TRAVAIL AVEC UN MANIFESTE

Le premier pas consiste à décrire l'espace de travail de l'agent. Pour cela, on utilise un manifest, qui liste les fichiers locaux à rendre disponibles dans l'espace de travail virtuel.

Voici comment créer un manifest simple avec un fichier CSV :

# Installation du SDK avec le support Docker
# pip install "openai-agents[docker]"

from pathlib import Path
from agents.sandbox import LocalFile, Manifest

manifest = Manifest(
    entries={
        "input/data.csv": LocalFile(src=Path("data/data.csv")),
    },
)

Ce code signifie : « Prends le fichier local data/data.csv et place-le dans l'espace de travail sous le nom input/data.csv ». L'agent pourra ainsi y accéder pour lire ou modifier les données.

ÉTAPE 2 : CRÉER L'AGENT AVEC SES INSTRUCTIONS

Une fois le manifest prêt, on configure l'agent en précisant son rôle, le modèle à utiliser, et le manifest par défaut. Voici comment faire :

from agents.sandbox import SandboxAgent

agent = SandboxAgent(
    name="coding agent",
    instructions="Inspect the input files, write and run code when useful, and save requested artifacts.",
    model="gpt-5.4",
    default_manifest=manifest,
)

L'agent est configuré avec :

• Un nom pour l'identifier (coding agent)
• Des instructions qui lui expliquent ce qu'il doit faire (inspecter les fichiers, écrire et exécuter du code si nécessaire, et sauvegarder les artefacts demandés)
• Un modèle (gpt-5.4)
• Un manifest qui définit les fichiers disponibles

ÉTAPE 3 : CONFIGURER L'ENVIRONNEMENT D'EXÉCUTION AVEC DOCKER

Pour que l'agent puisse exécuter du code, il lui faut un environnement sécurisé. Ici, on utilise un conteneur Docker personnalisé. Voici comment le préparer :

D'abord, installez Docker sur votre machine si ce n'est pas déjà fait. Docker permet de créer des environnements isolés, comme des petites machines virtuelles temporaires. Vous pouvez vérifier que Docker fonctionne en tapant dans un terminal :

docker --version

Ensuite, créez un Dockerfile pour définir l'image de l'environnement. Ce fichier indique quelles bibliothèques Python doivent être installées :

FROM python:3.12-slim

ENV MPLBACKEND=Agg

RUN pip install --no-cache-dir numpy scipy pandas matplotlib

WORKDIR /workspace

Ce Dockerfile installe les bibliothèques essentielles pour l'analyse de données : numpy, scipy, pandas et matplotlib. La ligne ENV MPLBACKEND=Agg permet à matplotlib de sauvegarder des graphiques sans avoir besoin d'un écran, ce qui est crucial dans un conteneur sans interface graphique.

Pour construire l'image Docker, exécutez ce code Python :

import subprocess

IMAGE_NAME = "energy-agent-sandbox:latest"

subprocess.run(["docker", "build", "-t", IMAGE_NAME, "."], check=True)

Cette commande crée une image Docker nommée energy-agent-sandbox:latest à partir du Dockerfile. Plus tard, l'agent utilisera cette image pour exécuter son code.

ÉTAPE 4 : LANCER UNE SESSION D'EXÉCUTION DOCKER

Avec l'image Docker prête, on peut maintenant créer une session d'exécution pour l'agent. Cette session est une instance temporaire du conteneur Docker, configurée avec le manifest et l'image. Voici comment la lancer :

import docker
from agents.sandbox.sandboxes.docker import DockerSandboxClient
from agents.sandbox.sandboxes.docker import DockerSandboxClientOptions

dockerclient = DockerSandboxClient(docker.fromenv())
sandboxoptions = DockerSandboxClientOptions(image=IMAGENAME)

sandboxsession = await dockerclient.create(
    manifest=manifest,
    options=sandbox_options,
)
await sandboxsession.applymanifest()

Ce code fait trois choses :

1. Il crée un client Docker pour interagir avec le démon Docker de votre machine.
2. Il définit les options de la session sandbox, en spécifiant l'image Docker à utiliser.
3. Il lance la session et applique le manifest, ce qui rend les fichiers disponibles dans le conteneur.

ÉTAPE 5 : FAIRE TRAVAILLER L'AGENT AVEC UNE INSTRUCTION PRÉCISE

L'agent est maintenant prêt à recevoir une instruction. Voici un exemple concret où on lui demande d'analyser un fichier de consommation énergétique :

PROMPT = """
I have an hourly energy-consumption export for one building at input/building_energy.csv.
The columns are timestamp, energykwh, and outdoortempc. outdoortemp_c is in degrees Celsius.

Please investigate the file and look for energy-use abnormal events.
Ignore tiny fluctuations that look like normal operating noise.

Use code in the sandbox to do the analysis, then save these files:
- output/anomalies.csv
- output/energy_anomalies.png
- output/anomaly_report.md

In the report, explain your method briefly,
and give plausible explanations based only on the timestamps, energy values, and outdoor temperature.
Use plain ASCII text such as deg C instead of the degree symbol.
""".strip()

Cette instruction demande à l'agent de :

• Analyser le fichier input/building_energy.csv.
• Détecter des anomalies dans la consommation énergétique.
• Produire trois fichiers : un tableau des anomalies (anomalies.csv), un graphique (energy_anomalies.png), et un rapport en markdown (anomaly_report.md).
• Expliquer sa méthode et donner des hypothèses plausibles basées uniquement sur les données disponibles.

ÉTAPE 6 : EXÉCUTER L'AGENT ET RÉCUPÉRER LES RÉSULTATS

Pour lancer l'agent, on utilise le Runner du SDK, qui connecte l'agent à la session sandbox. Voici comment faire :

from agents import Runner, RunConfig
from agents.sandbox import SandboxRunConfig

result = await Runner.run(
    agent,
    PROMPT,
    max_turns=25,
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox_session),
    ),
)

Quelques détails importants :

• max_turns=25 limite le nombre d'itérations pour éviter une boucle infinie.
• Le RunConfig associe l'agent à la session sandbox.

Une fois l'exécution terminée, l'agent a produit les trois fichiers demandés. Pour les récupérer sur votre machine locale, il faut sauvegarder l'espace de travail et extraire les fichiers :

workspacearchive = await sandboxsession.persist_workspace()

OUTPUTS_DIR = Path("outputs")
shutil.rmtree(OUTPUTSDIR, ignoreerrors=True)
OUTPUTSDIR.mkdir(parents=True, existok=True)

with tarfile.open(fileobj=workspace_archive, mode="r:*") as tar:
    for filename in ["anomalies.csv", "energyanomalies.png", "anomalyreport.md"]:
        source = tar.extractfile(f"output/{filename}")
        (OUTPUTSDIR / filename).writebytes(source.read())

await sandbox_session.aclose()

Ce code crée un dossier outputs sur votre machine et y copie les trois fichiers générés par l'agent.

ANALYSE DES FICHIERS PRODUITS PAR L'AGENT

L'agent a généré trois fichiers que vous pouvez maintenant consulter :

• anomalies.csv : un tableau listant les anomalies détectées avec leurs horodatages et valeurs.
• energy_anomalies.png : un graphique montrant les pics de consommation anormaux.
• anomaly_report.md : un rapport en markdown expliquant la méthode utilisée et les hypothèses.

Le graphique energy_anomalies.png révèle clairement un événement anormal, comme un pic de consommation énergétique à un moment précis.

Pour comprendre comment l'agent a abouti à cette conclusion, vous pouvez inspecter les étapes de son raisonnement :

for item in result.new_items:
    print(type(item).__name__, item)

Dans une exécution typique, l'agent a d'abord inspecté l'espace de travail et chargé le CSV avec pandas. Il a vérifié le nombre de lignes, les noms des colonnes, les types de données et les valeurs manquantes. Ensuite, il a écrit et exécuté un script de détection d'anomalies avec numpy et pandas. Le script a construit un modèle de référence horaire, calculé les résidus, et identifié les scores z robustes. Enfin, l'agent a généré le graphique demandé, sauvegardé le tableau, et produit le rapport en markdown. Il a même validé les sorties pour s'assurer que tout était correct.

RECETTE RÉUTILISABLE : LES CLÉS POUR RÉUSSIR

Ce tutoriel a couvert les étapes essentielles pour créer un agent capable d'exécuter du code. Voici les points clés à retenir pour réutiliser cette méthode dans d'autres projets :

1. Le manifest : listez précisément les fichiers nécessaires à l'agent. Si vous avez besoin de plusieurs fichiers, ajoutez-les tous dans le manifest. Par exemple, pour analyser un dossier de documents, vous pouvez inclure plusieurs PDF ou CSV.

2. L'environnement Docker : adaptez le Dockerfile aux bibliothèques dont l'agent a besoin. Si votre projet nécessite scikit-learn ou seaborn, ajoutez-les au Dockerfile. N'oubliez pas de tester l'image localement avant de l'utiliser avec l'agent.

3. Les instructions : soyez précis dans vos prompts. Indiquez exactement quels fichiers l'agent doit produire et sous quel format. Plus l'instruction est claire, plus les résultats seront conformes à vos attentes.

4. Le contrôle des itérations : utilisez max_turns pour limiter le nombre d'itérations de l'agent. Cela évite les boucles infinies et réduit les coûts d'exécution.

5. La récupération des résultats : après l'exécution, sauvegardez l'espace de travail et extrayez uniquement les fichiers dont vous avez besoin. Cela garde votre projet propre et organisé.

AUTRES OPTIONS POUR L'EXÉCUTION DE CODE

Le SandboxAgent n'est pas la seule façon d'activer l'exécution de code dans l'OpenAI Agents SDK. Voici deux alternatives :

CodeInterpreterTool : cet outil permet à un agent standard d'exécuter du code dans un environnement hébergé par OpenAI. C'est pratique si vous ne voulez pas gérer vous-même des images Docker ou des runtimes locaux.

ShellTool : si votre workflow est orienté ligne de commande, le SDK propose aussi l'exécution de shell via ShellTool. Avec SandboxAgent, le shell est déjà inclus par défaut dans les capacités du sandbox.

ET MAINTENANT ? QUEL PROJET ALLEZ-VOUS CRÉER ?

Les agents capables d'exécuter du code ouvrent la porte à une multitude de projets innovants. Voici quelques idées pour vous inspirer :

• Concevoir des API conversationnelles pilotées par des agents IA.
• Créer un cadre de mesure de la qualité de récupération pour les agents utilisant le Model Context Protocol.
• Automatiser la génération systématique d'exemples pour améliorer les prompts de vos modèles.
• Surmonter les limitations des LLM grâce à la vérification formelle.

Le monde des agents IA est en pleine expansion. Avec cette capacité d'exécution de code, vous avez maintenant un outil puissant pour explorer de nouvelles idées et automatiser des tâches complexes. Alors, quel projet allez-vous construire en premier ?