Construct an LLM Agent That Can Write and Run Code

As soon as the agent can write and execute code, many duties turn into doable. For instance, the agent can examine recordsdata or datasets, write knowledge processing logic, or produce artifacts for downstream consumption.

That opens the door to a a lot wider vary of agentic purposes.

On this put up, let’s construct a coding agent with the OpenAI Brokers SDK and Docker. We’ll first construct the psychological mannequin, then stroll by way of a small case examine the place we ask the agent to research a CSV file, and return a report with charts.

Ultimately, we’ll additionally summarize the sensible particulars that make this sample reusable.

1. How Code-Executing Brokers Work

There are three necessary parts of a code-executing agent: the mannequin, the workspace, and the execution surroundings. Let’s unpack them one after the other.

1.1 The Mannequin

A code-executing agent is, in spite of everything, an LLM agent. Naturally, it wants an LLM to energy the agent.

On this particular state of affairs, the widespread duties of the LLM can be to examine the out there recordsdata, determine what sort of study is required, write the precise code, learn the outcomes, and proceed with additional iterations.

1.2 Workspace

That is the area the place the agent works, and it’s the place the enter recordsdata go in and the output recordsdata come out. The consumer might add the info recordsdata (reminiscent of CSV, PDF, a folder of paperwork, and so forth) into the workspace, the agent can work on them, and save the artifacts again to it.

1.3 Execution Setting

The LLM agent solely writes the code and doesn’t execute it. So we want an execution surroundings the place the generated code can really run.

There are a number of out there choices. For instance, this code-execution surroundings generally is a hosted one managed by the platform, or it may be a sandbox we management ourselves regionally. If we management it ourselves, Docker is often the default technique to package deal the runtime and isolate the run.

1.4 Cross-Reducing Concern: Management

Then, there may be one sensible design query: management.

On the mannequin layer, we have to determine learn how to construct the agent system instruction and what artifacts the agent ought to produce.

On the workspace layer, we want to consider what recordsdata are staged into it and what remaining output artifacts needs to be introduced again after the run.

On the execution surroundings layer, we have to decide what dependencies needs to be made out there and whether or not community or shell entry is allowed.

1.5 OpenAI Brokers SDK

Within the OpenAI Brokers SDK, a SandboxAgent precisely implements the sample we mentioned above.

To configure the code-executing agent with the Brokers SDK, we first want to explain the workspace with a Manifest, which principally specifies which native recordsdata needs to be staged into the workspace. A easy instance is proven beneath:

# pip set up "openai-agents[docker]"

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

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

This says: take an area file and make it out there contained in the workspace as enter/knowledge.csv.

Then, we specify the agent’s mannequin, directions, and the workspace manifest:

from brokers.sandbox import SandboxAgent

agent = SandboxAgent(
    identify="coding agent",
    directions="Examine the enter recordsdata, write and run code when helpful, and save requested artifacts.",
    mannequin="gpt-5.4",
    default_manifest=manifest,
)

Subsequent, we should always create the execution sandbox. If we use Docker:

# pip set up "openai-agents[docker]"

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

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

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

Right here, the picture argument of DockerSandboxClientOptions specifies the Docker picture utilized by the sandbox. That’s the place we will customise the picture, for instance, by pre-installing the dependencies in order that the agent can immediately use them in the course of the run with out putting in on the fly.

Lastly, we join the agent and the sandbox session at runtime:

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

outcome = await Runner.run(
    agent,
    "Analyze enter/knowledge.csv and save a brief report beneath output/report.md.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(session=sandbox_session),
    ),
)

After the run, the sandbox workspace may also be endured as a tar archive:

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

We will then extract the output recordsdata we care about (e.g., stories, charts, tables, and so forth) and replica them again to the host machine.

After all, there are different methods to allow code execution within the Brokers SDK moreover the above-mentioned SandboxAgent. For instance, you’ll be able to connect CodeInterpreterTool to a daily agent, which permits the agent to run code in an OpenAI-managed surroundings. This is useful if you happen to don’t wish to handle Docker photographs and native runtimes your self.

If the workflow is extra command-line oriented, the SDK additionally gives shell execution by way of ShellTool. With SandboxAgent, shell is included by default as a part of its sandbox capabilities.

2. Case Research: An Agent That Analyzes a CSV

On this case examine, we’ll construct an agent that may write code and carry out knowledge evaluation.

2.1 The Case Research Setup

Right here, we take into account a time sequence anomaly detection job. Particularly, we’ll job the agent to look into an hourly constructing vitality dataset and to determine uncommon vitality use occasions.

I created an artificial dataset in plain CSV:

knowledge/building_energy.csv

with three columns:

timestamp, energy_kwh, outdoor_temp_c

The time sequence knowledge is visualized beneath:

To finish the duty, the agent wants to examine the CSV, construct a standard baseline conduct, and evaluate the observations in opposition to the anticipated patterns.

We ask the agent to save lots of three output recordsdata:

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

2.2 Put together the Docker Runtime

Earlier than configuring the agent, we first want to organize its code execution surroundings. Right here, we use a Docker container.

This container will function the agent’s momentary machine, with a working listing, a Python runtime, and a set of libraries that the agent can use to carry out knowledge evaluation. Be aware that the agent will solely run code inside that container, our host machine stays outdoors the run.

To outline that surroundings, we create a Dockerfile:

FROM python:3.12-slim

ENV MPLBACKEND=Agg

RUN pip set up --no-cache-dir numpy scipy pandas matplotlib

WORKDIR /workspace

Be aware that we give the agent numpy, scipy, pandas, and matplotlib. These libraries needs to be sufficient for the present job. We additionally set MPLBACKEND=Agg, which lets matplotlib save figures with no need a show. That is particularly helpful right here as a result of the code runs inside a non-interactive container.

Subsequent, we will construct the picture:

import subprocess

IMAGE_NAME = "energy-agent-sandbox:newest"

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

Later, once we create the sandbox session, we will cross this picture identify into DockerSandboxClientOptions. That’s how the sandbox is aware of which execution surroundings to make use of.

For this case examine, you’ll want to be sure that Docker is put in and working in your machine. The reason being easy: later, our Python code will ask Docker to create the sandbox session, so the Python course of wants to have the ability to discuss to the Docker daemon.

On Home windows or macOS, you’ll be able to set up Docker Desktop. On Linux, set up Docker Engine immediately from Docker’s official package deal repository.

You may verify if Docker is correctly arrange by working:

docker –model
docker run hello-world

2.3 Outline and Run the Agent

Now we outline the precise agent. We begin with the manifest, which tells the sandbox which native file needs to be out there contained in the workspace:

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

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

Within the code snippet above, we stage the native CSV file into the sandbox workspace as:

enter/building_energy.csv

Subsequent, we outline the agent instruction for outlining its function, anticipated final result, in addition to the libraries at its disposal:

# Be aware: This instruction is iterated with AI
INSTRUCTIONS = """
You're a sensible knowledge analyst. 
Use the sandbox workspace to examine recordsdata, write and run code when helpful, 
and save clear artifacts. 
Maintain conclusions grounded in computed proof. 
The sandbox has Python with numpy, scipy, pandas, and matplotlib out there.
""".strip()

Lastly, we create the SandboxAgent:

from brokers.sandbox import SandboxAgent

agent = SandboxAgent(
    identify="Power anomaly analyst",
    directions=INSTRUCTIONS,
    mannequin="gpt-5.4",
    default_manifest=manifest,
)

To run the agent, we used the next immediate:

PROMPT = """
I've an hourly energy-consumption export for one constructing at enter/building_energy.csv.
The columns are timestamp, energy_kwh, and outdoor_temp_c. outdoor_temp_c is in levels Celsius.

Please examine the file and search for energy-use irregular occasions.
Ignore tiny fluctuations that seem like regular working noise.

Use code within the sandbox to do the evaluation, then save these recordsdata:
- output/anomalies.csv
- output/energy_anomalies.png
- output/anomaly_report.md

Within the report, clarify your technique briefly, 
and provides believable explanations primarily based solely on the timestamps, vitality values, and out of doors temperature. 
Use plain ASCII textual content reminiscent of deg C as an alternative of the diploma image.
""".strip()

Be aware that within the immediate above, we explicitly specified the recordsdata we anticipate again. Subsequent, we create a Docker sandbox session from the picture we constructed earlier:

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

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

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

Then, we will run the agent:

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

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

2.4 Examine the Outcomes

After the run, the agent created the three recordsdata we requested.
To convey them again to our native mission folder, we have to persist the sandbox workspace and extract the anticipated recordsdata:

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(dad and mom=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"]:
        supply = tar.extractfile(f"output/{filename}")
        (OUTPUTS_DIR / filename).write_bytes(supply.learn())

await sandbox_session.aclose()

Now we will see that the next recordsdata exist within the native outputs/ folder:

anomalies.csv
energy_anomalies.png
anomaly_report.md

The agent discovered one clear irregular occasion, as proven within the energy_anomalies.png:

We will additional examine how the agent reached this conclusion:

for merchandise in outcome.new_items:
    print(sort(merchandise).__name__, merchandise)

In my run, I can roughly see that the agent first inspected the workspace and loaded the CSV with pandas. It then checked the row depend, column names, knowledge sorts, and lacking values.

After that, it wrote and ran an anomaly detection script with numpy and pandas. The script first constructed an anticipated hourly baseline, adopted by computing residuals and strong z-scores.

Lastly, the agent generated the requested plot, saved the CSV, and output a markdown report. It even validated the outputs to wrap up the work.

We now have a working code-executing agent.

3. Sensible Issues To Maintain In Thoughts

As we’ve seen within the earlier case examine, there are just a few particulars we have to take into account when constructing the code-executing agent:

1. Begin with the agent’s instruction, be express about its function, its job, and its anticipated final result;
2. Determine what recordsdata ought to enter the workspace. That is the set of recordsdata the agent will work on;
3. Determine what runtime the agent can use, together with the required libraries;
4. State explicitly in regards to the output file names and areas. This makes the later extraction and copy-paste simple.

As soon as these items are clear, you’ll be able to reuse the identical sample for a lot of different agentic workflows.

So, what would you construct subsequent with this functionality?