How to run a first task on the OpenAI Agents API

The Agents API quickstart is the managed path: OpenAI manages the agent, its conversation, and the sandbox where it works. The same docs list a separate Agents SDK, with its own quickstart. This article stays on the Agents API page: the key scopes, the beta header, a hosted session that writes and runs tree.py, the events that mark a finished or failed turn, and how to delete the session.

Grant the three scopes and export the key

Create an application API key in your OpenAI Platform project. Grant api.agents.read and api.agents.write for session operations, plus api.responses.write for model inference. Then export it:

export OPENAI_API_KEY="your-api-key"

Keep this key outside the agent's sandbox. The quickstart points to the OpenAI-hosted sandboxes guide for configuration and limits. Those limits are not listed on the quickstart page, so they are unknown from this page alone.

Requests require the OpenAI-Beta: agents=v1 header. The OpenAI SDKs add it automatically. Include it explicitly when using cURL.

Create the hosted session

The SDK examples use the beta.agents namespace. The request creates a session, submits a task, and streams progress. Install or update the Python SDK:

pip install --upgrade openai

Save the example as quickstart.py. The published model string is gpt-6-astra. Use that string as written on the page. environment.type is openai_hosted, and stream is true.

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

Run it from your terminal:

python quickstart.py

The same page publishes JavaScript, Go, Java, and Ruby samples for this task, each with its own install command and filename. Copy the sample for the language you run. Do not mix flags across SDKs.

Without an SDK, send the beta header yourself:

curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted" },
    "input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
    "stream": true
  }'

Don't need a sandbox? Set environment.type to none for agents that answer questions or call external tools without running commands or working with local files.

Read completion events, not just idle

The terminal shows streamed events. The SDK examples print JSON; cURL shows the raw event stream. On a successful run, the agent creates tree.py, executes it, and reports a directory tree containing that file. Other files and output depend on the sandbox. The page does not include a sample event payload, so judge the run by the names it gives you.

Look for agent.session.turn.completed, then check the agent's reported execution result. A completed turn does not guarantee every tool succeeded. Events ending in turn.failed, turn.cancelled, or session.failed indicate failure or cancellation. agent.session.idle alone does not mean success.

If the stream disconnects early, retrieve the session and its saved items before retrying. The retrieve call is on the sessions guide, not in this quickstart, so it is not reproduced here.

Continue with the saved session id, then delete

Save the session_id from the events. Use it to send a follow-up such as "Add a maximum-depth option to tree.py, run it, and show me the output." Open the event stream before sending follow-up input so you don't miss early events. This page does not include the follow-up request; it points to the sessions guide for sending input. What it does specify is that the follow-up reuses the saved id.

Keep the session for more tasks, or delete it when you're done. Save any files you need first. How to download those files is linked from the quickstart, not spelled out on it.

Replace the illustrative sess_123 value with the session ID you saved:

# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)

if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

The cURL delete uses the same placeholder id in the path:

curl -X DELETE "https://api.openai.com/v1/agents/sessions/sess_123" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

JavaScript, Go, Java, and Ruby delete examples are on the same page. Each passes the session id to the sessions delete call and prints the result. sess_123 is illustrative, not a live id.

What to run next

Run python quickstart.py, or the cURL request if you are not using an SDK. Treat the task as finished only after you see agent.session.turn.completed and you have checked the reported execution result. Then stay on the quickstart's next-steps list: configure an OpenAI-hosted sandbox, including packages, input files, network access, and artifact download; work with files and artifacts before you delete; and choose an environment or connect your own sandbox if openai_hosted is not the right fit.

Sources

Agents API quickstart