Créez un agent LLM capable d’écrire et d’exécuter du code

Une fois que l’agent peut écrire et exécuter du code, de nombreuses tâches deviennent possibles. Par exemple, l’agent peut inspecter des fichiers ou des ensembles de données, écrire une logique de traitement des données ou produire des artefacts pour une consommation en aval.

Cela ouvre la porte à une gamme beaucoup plus large d’applications agents.

Dans cet article, créons un agent de codage avec le SDK OpenAI Agents et Docker. Nous allons d’abord construire le modèle mental, puis parcourir une petite étude de cas dans laquelle nous demandons à l’agent d’analyser un fichier CSV et de renvoyer un rapport avec des graphiques.

Au final, nous résumerons également les détails pratiques qui rendent ce patron réutilisable.

1. Comment fonctionnent les agents d’exécution de code

Il existe trois composants importants d’un agent d’exécution de code : le modèle, l’espace de travail et l’environnement d’exécution. Déballons-les un par un.

1.1 Le modèle

Un agent exécutant du code est, après tout, un agent LLM. Naturellement, il a besoin d’un LLM pour alimenter l’agent.

Dans ce scénario spécifique, les tâches courantes du LLM seraient d’inspecter les fichiers disponibles, de décider quel type d’analyse est nécessaire, d’écrire le code réel, de lire les résultats et de continuer avec d’autres itérations.

1.2 Espace de travail

C’est l’espace dans lequel l’agent travaille, et c’est là que les fichiers d’entrée entrent et que les fichiers de sortie sortent. L’utilisateur peut télécharger les fichiers de données (tels que CSV, PDF, un dossier de documents, etc.) dans l’espace de travail, l’agent peut travailler dessus et y enregistrer les artefacts.

1.3 Environnement d’exécution

L’agent LLM écrit uniquement le code et ne l’exécute pas. Nous avons donc besoin d’un environnement d’exécution dans lequel le code généré peut réellement s’exécuter.

Il existe plusieurs options disponibles. Par exemple, cet environnement d’exécution de code peut être un environnement hébergé géré par la plateforme, ou il peut s’agir d’un bac à sable que nous contrôlons nous-mêmes localement. Si nous le contrôlons nous-mêmes, Docker est généralement le moyen par défaut de regrouper le runtime et d’isoler l’exécution.

1.4 Préoccupation transversale : Contrôle

Ensuite, il y a une question pratique de conception : contrôle.

At the model layer, we need to decide how to build the agent system instruction and what artifacts the agent should produce.

Au niveau de la couche d’espace de travail, nous devons réfléchir aux fichiers qui y sont stockés et aux artefacts de sortie finaux qui doivent être ramenés après l’exécution.

Au niveau de l’environnement d’exécution, nous devons déterminer quelles dépendances doivent être mises à disposition et si l’accès au réseau ou au shell est autorisé.

1.5 SDK des agents OpenAI

Dans le SDK OpenAI Agents, un SandboxAgent implémente exactement le modèle dont nous avons discuté ci-dessus.

Pour configurer l’agent d’exécution de code avec le SDK Agents, nous devons d’abord décrire l’espace de travail avec un Manifestqui spécifie essentiellement quels fichiers locaux doivent être transférés dans l’espace de travail. Un exemple simple est présenté ci-dessous :

# 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")),
    },
)

Cela dit : prenez un fichier local et rendez-le disponible dans l’espace de travail en tant que input/data.csv.

Ensuite, nous spécifions le modèle de l’agent, les instructions et le manifeste de l’espace de travail :

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,
)

Ensuite, nous devons créer le bac à sable d’exécution. Si nous utilisons Docker :

# pip install "openai-agents[docker]"

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

docker_client = DockerSandboxClient(docker.from_env())
sandbox_options = DockerSandboxClientOptions(image="my-agent-sandbox:latest")

sandbox_session = await docker_client.create(
    manifest=manifest,
    options=sandbox_options,
)
await sandbox_session.apply_manifest()

Ici, le image argument de DockerSandboxClientOptions spécifie l’image Docker utilisée par le bac à sable. C’est là que l’on peut personnaliser l’image, par exemple en pré-installant les dépendances afin que l’agent puisse les utiliser directement lors de l’exécution sans les installer à la volée.

Enfin, nous connectons l’agent et la session sandbox au moment de l’exécution :

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

result = await Runner.run(
    agent,
    "Analyze input/data.csv and save a short report under output/report.md.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox_session),
    ),
)

Après l’exécution, l’espace de travail sandbox peut également être conservé en tant qu’archive tar :

workspace_archive = await sandbox_session.persist_workspace()
await sandbox_session.aclose()

Nous pouvons ensuite extraire les fichiers de sortie qui nous intéressent (par exemple, rapports, graphiques, tableaux, etc.) et les recopier sur la machine hôte.

Bien entendu, il existe d’autres moyens d’activer l’exécution de code dans le SDK Agents en plus de ceux mentionnés ci-dessus. SandboxAgent. Par exemple, vous pouvez joindre CodeInterpreterTool à un agent standard, ce qui permet à l’agent d’exécuter du code dans un environnement géré par OpenAI. Cela s’avère pratique si vous ne souhaitez pas gérer vous-même les images Docker et les environnements d’exécution locaux.

Si le workflow est davantage orienté ligne de commande, le SDK fournit également l’exécution du shell via ShellTool. Avec SandboxAgentle shell est inclus par défaut dans le cadre de ses fonctionnalités sandbox.

2. Étude de cas : un agent qui analyse un CSV

Dans cette étude de cas, nous allons créer un agent capable d’écrire du code et d’effectuer des analyses de données.

2.1 La configuration de l’étude de cas

Ici, nous considérons une tâche de détection d’anomalies de séries chronologiques. Plus précisément, nous chargerons l’agent d’examiner un ensemble de données horaires sur l’énergie d’un bâtiment et d’identifier les événements inhabituels de consommation d’énergie.

J’ai créé un ensemble de données synthétiques au format CSV :

data/building_energy.csv

avec trois colonnes :

timestamp, energy_kwh, outdoor_temp_c

Les données de la série chronologique sont visualisées ci-dessous :

Pour terminer la tâche, l’agent doit inspecter le CSV, créer un comportement de base normal et comparer les observations aux modèles attendus.

Nous demandons à l’agent de sauvegarder trois fichiers de sortie :

output/anomalies.csv
output/energy_anomalies.png
output/anomaly_report.md

2.2 Préparer le runtime Docker

Avant de configurer l’agent, nous devons d’abord préparer son environnement d’exécution de code. Ici, nous utilisons un conteneur Docker.

Ce conteneur servira de machine temporaire à l’agent, avec un répertoire de travail, un runtime Python et un ensemble de bibliothèques que l’agent pourra utiliser pour effectuer une analyse des données. Notez que l’agent exécutera uniquement le code à l’intérieur de ce conteneur, notre machine hôte reste en dehors de l’exécution.

Pour définir cet environnement, nous créons un Dockerfile:

FROM python:3.12-slim

ENV MPLBACKEND=Agg

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

WORKDIR /workspace

Notez que nous donnons à l’agent numpy, scipy, pandaset matplotlib. Ces bibliothèques devraient suffire pour la tâche actuelle. Nous avons également fixé MPLBACKEND=Aggce qui permet matplotlib enregistrer des chiffres sans avoir besoin d’un affichage. Ceci est particulièrement utile ici car le code s’exécute dans un conteneur non interactif.

Ensuite, nous pouvons construire l’image :

import subprocess

IMAGE_NAME = "energy-agent-sandbox:latest"

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

Plus tard, lorsque nous créerons la session sandbox, nous pourrons transmettre ce nom d’image dans DockerSandboxClientOptions. C’est ainsi que le bac à sable sait quel environnement d’exécution utiliser.

Pour cette étude de cas, vous devez vous assurer que Docker est installé et exécuté sur votre ordinateur. La raison est simple : plus tard, notre code Python demandera à Docker de créer la session sandbox, le processus Python doit donc pouvoir communiquer avec le démon Docker.

Sous Windows ou macOS, vous pouvez installer Docker Desktop. Sous Linux, installez Docker Engine directement à partir du référentiel de packages officiel de Docker.

Vous pouvez vérifier si Docker est correctement configuré en exécutant :

docker-version
Docker exécute Hello-World

2.3 Définir et exécuter l’agent

Nous définissons maintenant l’agent réel. Nous commençons par le manifestqui indique au bac à sable quel fichier local doit être disponible dans l’espace de travail :

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

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

Dans l’extrait de code ci-dessus, nous plaçons le fichier CSV local dans l’espace de travail sandbox comme :

input/building_energy.csv

Ensuite, nous définissons l’instruction de l’agent pour définir son rôle, le résultat attendu, ainsi que les bibliothèques à sa disposition :

# Note: This instruction is iterated with AI
INSTRUCTIONS = """
You are a practical data analyst. 
Use the sandbox workspace to inspect files, write and run code when useful, 
and save clear artifacts. 
Keep conclusions grounded in computed evidence. 
The sandbox has Python with numpy, scipy, pandas, and matplotlib available.
""".strip()

Enfin, nous créons le SandboxAgent:

from agents.sandbox import SandboxAgent

agent = SandboxAgent(
    name="Energy anomaly analyst",
    instructions=INSTRUCTIONS,
    model="gpt-5.4",
    default_manifest=manifest,
)

Pour exécuter l’agent, nous avons utilisé l’invite suivante :

PROMPT = """
I have an hourly energy-consumption export for one building at input/building_energy.csv.
The columns are timestamp, energy_kwh, and outdoor_temp_c. outdoor_temp_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()

Notez que dans l’invite ci-dessus, nous avons explicitement spécifié les fichiers que nous attendons. Ensuite, nous créons une session sandbox Docker à partir de l’image que nous avons créée précédemment :

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

docker_client = DockerSandboxClient(docker.from_env())
sandbox_options = DockerSandboxClientOptions(image=IMAGE_NAME)

sandbox_session = await docker_client.create(
    manifest=manifest,
    options=sandbox_options,
)
await sandbox_session.apply_manifest()

Ensuite, nous pouvons exécuter l’agent :

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),
    ),
)

2.4 Inspecter les résultats

Après l’exécution, l’agent a créé les trois fichiers demandés.
Pour les ramener dans notre dossier de projet local, nous devons conserver l’espace de travail sandbox et extraire les fichiers attendus :

from pathlib import Path

workspace_archive = await sandbox_session.persist_workspace()

OUTPUTS_DIR = Path("outputs")
shutil.rmtree(OUTPUTS_DIR, ignore_errors=True)
OUTPUTS_DIR.mkdir(parents=True, exist_ok=True)

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

await sandbox_session.aclose()

Nous pouvons maintenant voir que les fichiers suivants existent dans le fichier local outputs/ dossier:

anomalies.csv
energy_anomalies.png
anomaly_report.md

L’agent a détecté un événement clairement anormal, comme indiqué dans le energy_anomalies.png:

Nous pouvons examiner plus en détail comment l’agent est parvenu à cette conclusion :

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

Lors de mon exécution, je peux voir à peu près que l’agent a d’abord inspecté l’espace de travail et chargé le CSV avec pandas. Il a ensuite vérifié le nombre de lignes, les noms de colonnes, les types de données et les valeurs manquantes.

Après cela, il a écrit et exécuté un script de détection d’anomalies avec numpy et pandas. Le script a d’abord construit une référence horaire attendue, suivi du calcul des résidus et de scores z robustes.

Enfin, l’agent a généré le tracé demandé, enregistré le CSV et généré un rapport de démarque. Il a même validé les résultats pour conclure le travail.

Nous disposons désormais d’un agent d’exécution de code fonctionnel.

3. Choses pratiques à garder à l’esprit

Comme nous l’avons vu dans l’étude de cas précédente, nous devons prendre en compte quelques détails lors de la création de l’agent d’exécution de code :

1. Commencez par les instructions de l’agent, soyez explicite sur son rôle, sa tâche et le résultat attendu ;
2. Décidez quels fichiers doivent entrer dans l’espace de travail. Il s’agit de l’ensemble de fichiers sur lesquels l’agent va travailler ;
3. Décidez quel environnement d’exécution l’agent peut utiliser, y compris les bibliothèques nécessaires ;
4. Indiquez explicitement les noms et emplacements des fichiers de sortie. Cela facilite l’extraction et le copier-coller ultérieurs.

Une fois ces éléments clairs, vous pouvez réutiliser le même modèle pour de nombreux autres flux de travail agents.

Alors, que construiriez-vous ensuite avec cette capacité ?