# 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.

`agental-openai-agents` is a sandbox client for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/sandbox/clients/) 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](https://console.agental.io/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.

| Option | What it does |
| --- | --- |
| `size` | `tiny`, `small`, `medium` or `large`. Left out, the template's. |
| `template` | The template to make the sandbox from and hold it to, by its id or its name. Left out, the account's default. |
| `name` | The sandbox's name. Made up when left out. |
| `snapshot_id` | Make the sandbox from one of your [snapshots](https://agental.io/docs/snapshots). |
| `allow` | Addresses the sandbox may reach on top of its template's [outbound rule](https://agental.io/docs/outbound-rules). |
| `ttl_seconds` | How long it runs after a start before it is stopped. Up to `86400` (24 hours). Set it longer for a long run. |
| `sandbox_id` | Run 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_exit` | Stop the sandbox when the run ends, in place of deleting it, so a later run can pick it up with its files. |
| `exposed_ports` | Ports 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](https://agental.io/docs/lifecycle).

## Ports

A port in `exposed_ports` gets a [public address](https://agental.io/docs/ports) 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.

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)