Docs
⌘K

OpenAI Agents SDK

Run an agent built with the OpenAI Agents SDK in an agental sandbox. Its commands and file edits happen in the sandbox, and your code and the model's calls stay where they are.

For your agent

agental.io/docs/openai-agents.md

agental-openai-agents is a sandbox client for the OpenAI Agents SDK in Python. Give it to a SandboxAgent's run, and the sandbox the run works in is an agental sandbox. It is made by agental, not by OpenAI.

Install it

shell
pip install agental-openai-agents

Python 3.10 or later, with openai-agents 0.24. Make a key on the console's API keys page and put it in AGENTAL_API_KEY, next to OPENAI_API_KEY.

Run an agent

python
import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agental_openai_agents import AgentalSandboxClient, AgentalSandboxClientOptions

agent = SandboxAgent(name="Fixer", instructions="Run the tests in the workspace and fix what fails.")


async def main() -> None:
    run_config = RunConfig(
        sandbox=SandboxRunConfig(
            client=AgentalSandboxClient(),  # reads AGENTAL_API_KEY
            options=AgentalSandboxClientOptions(size="small"),
        ),
    )
    result = await Runner.run(agent, "Make the tests pass.", run_config=run_config)
    print(result.final_output)


asyncio.run(main())

Moving from another sandbox client, such as E2B or Modal, changes only client= and options=. The agent stays as it is.

What happens in a run

  • The client makes a sandbox from your account's default template, or the template you name.
  • The Agents SDK writes the manifest's files into the workspace, /opt/agental/workspace unless the manifest names another root.
  • Each command the model runs goes to the sandbox, in the workspace and with the manifest's variables, and its output goes back to the model. A command that takes a while is left running and read as it goes, so the model can start a build and come back to it.
  • When the run ends, the sandbox is deleted. It is billed for the time it ran.

Choose the sandbox

Pass these to AgentalSandboxClientOptions. Each one can be left out.

OptionWhat it does
sizetiny, small, medium or large. Left out, the template's.
templateThe template to make the sandbox from and hold it to, by its id or its name. Left out, the account's default.
nameThe sandbox's name. Made up when left out.
snapshot_idMake the sandbox from one of your snapshots.
allowAddresses the sandbox may reach on top of its template's outbound rule.
ttl_secondsHow long it runs after a start before it is stopped. Up to 86400 (24 hours). Set it longer for a long run.
sandbox_idRun in a sandbox you already have. It is not deleted when the run ends, and the options above, which are for a new sandbox, cannot be given with it.
stop_on_exitStop the sandbox when the run ends, in place of deleting it, so a later run can pick it up with its files.
exposed_portsPorts that get a public address when the agent asks for one.

Pick a run up later

With stop_on_exit=True, the sandbox is stopped when the run ends, and its disk is kept at 5% of the running price. A run resumed from its state, after an approval for example, starts that sandbox again with the workspace as it was. Without it, the sandbox is deleted, and a resumed run gets a new one, with the workspace put back from the run's snapshot if you gave SandboxRunConfig one.

A stopped sandbox stays until you delete it, in the console or with the SDK.

Ports

A port in exposed_ports gets a public address the first time the agent asks for it. Anyone with the address can open it while the sandbox runs. What listens must listen on 0.0.0.0.

Limits

  • A command runs for at most ten minutes. For longer work, have the agent start it in the background inside the sandbox, with nohup.
  • Nothing can be typed into a command once it runs, and there is no terminal. The agent gives a command its input with a pipe or a here-document.
  • Files outside /opt/agental are read and written through a copy there, which is made and taken away by the same call.
  • Mounting cloud storage buckets is not supported yet.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]