OpenAI Agents API Tutorial: Run Your First Browser-Driving Agent

Introduction

The OpenAI Agents API takes the hardest part of building an agent, the loop that keeps it running, calls tools, trims context, and recovers from failures, and turns it into a managed service. Since DevDay 2026 it also ships computer use, so an agent can drive an OpenAI-hosted browser and operate software through its interface instead of calling an API. This tutorial is for developers who want their first working Agents API session: creating it, giving it a browser, handling the origin approvals every new site triggers, and cleaning up correctly. You will also learn when to pick the Agents API over the Agents SDK or the plain Responses API, because choosing the wrong one is the most common design mistake in this space.

Quick answer

Create a session with the computer_use tool and an openai_hosted environment with the desktop enabled, subscribe to the event stream, send your task, approve or deny each website origin when prompted, verify the results, then delete the session.

The evidence: what the beta actually is, and what it is not

Three dates anchor everything below. The Agents API entered public beta on September 10, 2026, and computer use arrived at DevDay on September 29, 2026, alongside GPT-6.1 Sol, the new lower-cost model whose reported gains include the OSWorld 2.0 computer-use benchmark. The beta label matters because it tells you the pricing shape: there is no separate fee for the API, you pay for the tokens and tools your sessions consume.

The scale of the underlying technology is public. The open-source Codex harness repository on GitHub, which is the same agent loop the managed API runs, carried roughly 117,000 stars when reported in August 2026, under an Apache-2.0 license. You can read the loop’s code instead of treating the managed service as a black box, and you can self-host it if you later outgrow the hosted runtime. OpenAI’s own customer results, reported around DevDay, give a sense of where this is landing in production: SafetyKit measured a 60% lower cost per case, and Hypha measured 86% fewer failed responses.

The vendor’s own description of the product is worth quoting precisely, because it draws the line this tutorial teaches you to respect. OpenAI’s API changelog describes the managed service as handling “session orchestration, context compaction, and recovery” on OpenAI’s side. And the Agents guide warns that its resource types do not mix: “Agents API session, SDK session, Responses conversation, and sandbox are different resources.” That one sentence decides your architecture. If you build on the Agents API, your sessions, state, and recovery live inside it, and you cannot port them to the SDK later without rebuilding.

One more piece of context before we build. Browser-based computer use is not new to the industry: Anthropic has offered computer use for Claude since October 2024. OpenAI’s differentiator is hosting. With the Agents API you do not provision the browser or the desktop; the openai_hosted environment gives the agent a desktop-like browser session that OpenAI operates, and your application approves origins, manages sign-in, verifies results, and deletes the session when the work is done.

Prerequisites

• An OpenAI Platform account with an application API key in a project. The key needs the api.agents.read and api.agents.write scopes for session operations and api.responses.write for model inference. Export it as OPENAI_API_KEY and keep it out of the agent’s sandbox.
• A current OpenAI SDK (Python or JavaScript) that supports the beta Agents API. If you call raw HTTP instead, add the OpenAI-Beta: agents=v1 header, which the documented cURL alternative requires.
• Basic comfort with REST APIs and event streams. You will read JSON events, not click through a dashboard.
• A task that genuinely needs a browser. If the target site exposes an API or an MCP server, use that instead: structured tools are faster, cheaper, and easier to validate than driving a visual interface.

Step 1, Create the API key with the right scopes

In your OpenAI Platform project, create an application API key and grant it api.agents.read, api.agents.write, and api.responses.write. The first two scopes authorize session creation, event reads, and session deletion. The third authorizes the model inference the harness performs on your behalf. Export the key in your shell:

export OPENAI_API_KEY="sk-..."

Keep this key in your application environment only. The agent’s sandbox never needs your credentials, and leaking the key into session input is a real incident class.

Step 2, Create a session with the computer-use tool and a hosted desktop

A browser task is a session plus configuration. The documented shape puts a computer_use tool in the agent’s tool list and sets the environment to openai_hosted with the desktop enabled. The guide’s example also enables network access and screenshot capture. Using the Python SDK pattern documented for the beta Agents API:

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6.1-sol",
        "instructions": (
            "You are a web research assistant. Never sign in to any site "
            "and never change website data. Report page titles and URLs."
        ),
        "tools": [{"type": "computer_use", "include_screenshots": True}],
    },
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
        "network": {"enabled": True},
    },
    input=(
        "Find the OpenAI Agents API quickstart page and return its page "
        "title and URL. Do not sign in and do not change any website data."
    ),
)

print(session.id)

Two details in this block deserve attention. First, creating the session returns an ID but does not start the browser task; the session is a container you will drive with events. Save that ID before proceeding. Second, include_screenshots: true is what lets the agent actually observe the interface, since computer use works by looking at the screen and choosing the next action from what it sees. Confirm exact SDK method names against the Agents guide, since beta signatures evolve.

Step 3, Subscribe to the event stream before you send anything

This step has a real gotcha, documented by developers who hit it: subscribe to the session’s event stream before sending the task, not after. If you send first, you miss the earliest events, including the acknowledgment that the agent received your input at all, and you will not see the origin-approval events until it is too late to respond cleanly.

The events you must handle fall into two families. The browser_origin_access events fire when the hosted browser wants to touch a new website origin, including public sites, and your application must respond with approve, deny, or cancel. The browser_authentication events fire when a site presents a sign-in challenge, and your application must drive the sign-in flow itself. Turning on network access does not skip the approval step.

Step 4, Give the agent a bounded task with explicit guardrails

The guide’s own example is a model of a safe first task: find the Agents API quickstart page and return its title and URL, without signing in and without changing website data. Copy that shape for your own first runs. State the deliverable (a title and a URL, not “research this topic”), name the forbidden actions explicitly (no sign-in, no form submissions, no purchases), and keep the task to one site. An unbounded instruction like “book the cheapest flight” hands the agent your money with none of the guardrails this API assumes you will build yourself.

Step 5, Approve origins deliberately, one at a time

When the browser_origin_access event arrives, decide per origin. Approve origins your task needs, deny everything else. Remember the documented safety boundary: approving an origin grants access to that origin, and it does not enforce a separate confirmation before purchases or destructive changes. If the task touches anything consequential, this is the step where your application should refuse, narrow the task, or require a human decision before approving. The approval handler is your policy layer, and it is the one part of the system OpenAI explicitly leaves to you.

Step 6, Verify the results, review the activity, then delete the session

When the agent reports completion, do not trust the summary alone. Read the recorded browser activity and check the final state of the target: the correct page loaded, the correct data extracted, nothing changed that should not have changed. Access to an origin, completion of a turn, and correctness of the answer are three different observations, and only the last one decides whether the run succeeded. Then delete the session. Deleting is part of the documented flow, not optional hygiene: it closes the hosted environment and ends the billing for that session.

Step 7, Choose the right API before you build further

OpenAI’s guide compares three ways to build an agent, and the choice is architectural, not cosmetic:

Pick the Agents API when you want long-running cloud agents without operating the loop: OpenAI handles sessions, orchestration, context compaction, and recovery, and you supply instructions, tools, and business logic. Pick the Agents SDK when approvals, storage, or deployment must live inside your own infrastructure, or when you want to run the open-source Codex harness yourself and inspect exactly what the loop does. Pick the Responses API when you only need a model call with history and plan to write the agent loop yourself. Because the resource types do not mix, moving later costs a rewrite, so make this call on day one.

The tool story is the same across the options, which makes the choice cleaner. MCP servers plug in as tools on the Agents API, so if you already expose services over MCP, the migration path is short. If you need a refresher on building one, see our MCP server tutorial; to see how existing services get wrapped as agent tools, read how n8n workflows become MCP tools. For the other vendor’s take on the same problem, our Claude SDK computer-use tool tutorial covers Anthropic’s longer-running approach, and the GitHub Copilot computer-use tutorial shows the pattern inside an IDE agent.

Troubleshooting

Raw HTTP calls fail with an unrecognized request. You are missing the beta header. The documented cURL alternative requires the explicit OpenAI-Beta: agents=v1 header on every request. Add it and retry; the SDKs set the equivalent internally.

The agent starts working but you see no events, including the receipt acknowledgment. You subscribed to the event stream after sending the task. Subscribe first, then send the input. The earliest events, including the acknowledgment that the agent received your steering input, are emitted immediately and are not replayed to late subscribers.

Sign-in fails on a site that requires passkeys. The documented browser authentication flow supports email, password, and verification-code sign-ins, but not passkeys. There is no workaround inside the hosted browser: either complete the sign-in with a supported method before the agent session needs it, or run the task in a browser runtime you control.

A session ID from one API is rejected by another. Agents API sessions, SDK sessions, Responses conversations, and sandboxes are different resources, as the guide states. You cannot resume an Agents API session with the SDK or the Responses API. Recreate the session in the API family you intend to keep.

The agent approved itself into a risky page and changed data. Origin approval is not purchase protection. Approving a website origin grants the browser access to that origin without a guaranteed confirmation before consequential actions. Restrict the hosted browser to resources that cannot perform destructive actions, or run sensitive tasks in a runtime you control where your own confirmation gates every action.

FAQ

The FAQ answers are in the front matter at the top of this page.

Conclusion

The OpenAI Agents API is a managed Codex harness with a hosted browser attached: you create a session, configure the computer-use tool and an openai_hosted desktop, approve each website origin, verify what the agent did, and delete the session. The loop, the compaction, and the recovery are OpenAI’s job; origins, sign-in, and verification are yours. For your next step, build a real tool for the agent to call by following our MCP server tutorial, then connect it to a desktop agent with how to connect an MCP server to Claude Desktop. For model choice, our GPT-6.1 Sol Ultrafast tutorial explains the ultrafast tier in the Responses API.

Frequently asked questions