> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Give OpenAI agents a Notte browser in Python or TypeScript.

<Tip>
  Read [the Notte skill](https://notte.cc/skill.md) and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.
</Tip>

Connect the [OpenAI Agents SDK](https://developers.openai.com/api/docs/guides/agents/sdk) to [Notte Browser MCP](/mcp-server). The example creates a browser, lets an OpenAI agent read a page, and closes the browser when the run finishes or raises an error.

## Install

For Python 3.11+, run `pip install notte-sdk openai-agents==0.24.0`.

For Node.js 24+, run `npm install notte-sdk @openai/agents@0.20.0 openai@7.34.0 zod`.

Set `NOTTE_API_KEY` to your [Notte API key](https://console.notte.cc/apikeys) and `OPENAI_API_KEY` to your [OpenAI API key](https://platform.openai.com/api-keys).

## Run an agent

Save the Python example as `notte_openai_agents.py` and run `python notte_openai_agents.py`. For TypeScript, save it as `notte_openai_agents.ts` in a project with `"type": "module"` and run `node --experimental-strip-types notte_openai_agents.ts`.

<CodeGroup>
  ```python notte_openai_agents.py theme={null}
  import asyncio
  import os

  from agents import Agent, OpenAIResponsesModel, RunConfig, Runner
  from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter
  from notte_sdk import NotteClient
  from openai import AsyncOpenAI
  from pydantic import BaseModel


  class PageTitle(BaseModel):
      title: str


  async def main() -> dict[str, str]:
      with NotteClient().Session(max_duration_minutes=3) as session:
          try:
              async with (
                  AsyncOpenAI(timeout=120) as model_client,
                  MCPServerStreamableHttp(
                      name="Notte",
                      params={
                          "url": os.environ.get("NOTTE_API_URL", "https://api.notte.cc").rstrip("/") + "/mcp",
                          "headers": {"Authorization": f"Bearer {os.environ['NOTTE_API_KEY']}"},
                      },
                      client_session_timeout_seconds=120,
                      tool_filter=create_static_tool_filter(
                          allowed_tool_names=["browser_action", "browser_observe", "browser_scrape"]
                      ),
                  ) as server,
              ):
                  agent = Agent(
                      name="Browser reader",
                      model=OpenAIResponsesModel(model="gpt-4.1-mini", openai_client=model_client),
                      instructions=f"Use only browser_id {session.session_id}. Read the page with Notte tools.",
                      mcp_servers=[server],
                      output_type=PageTitle,
                  )
                  run = await Runner.run(
                      agent,
                      "Visit https://example.com and return its page title.",
                      max_turns=8,
                      run_config=RunConfig(tracing_disabled=True),
                  )
                  title = run.final_output_as(PageTitle).title
                  print(title)
                  return {"title": title, "session_id": session.session_id}
          except Exception:
              raise RuntimeError(f"OpenAI agent failed (session {session.session_id})") from None


  with asyncio.Runner() as runner:
      result = runner.run(main())
  ```

  ```typescript notte_openai_agents.ts theme={null}
  import { Agent, MCPServerStreamableHttp, createMCPToolStaticFilter, OpenAIResponsesModel, Runner } from '@openai/agents';
  import { NotteClient } from 'notte-sdk';
  import OpenAI from 'openai';
  import { z } from 'zod';

  export const result = await new NotteClient().Session({ max_duration_minutes: 3 }).use(async (session) => {
    const server = new MCPServerStreamableHttp({
      name: 'Notte',
      url: `${(process.env.NOTTE_API_URL || 'https://api.notte.cc').replace(/\/+$/, '')}/mcp`,
      requestInit: { headers: { Authorization: `Bearer ${process.env.NOTTE_API_KEY!}` } },
      clientSessionTimeoutSeconds: 120,
      toolFilter: createMCPToolStaticFilter({
        allowed: ['browser_action', 'browser_observe', 'browser_scrape'],
      }),
    });
    let operationFailed = false;
    try {
      await server.connect();
      const agent = new Agent({
        name: 'Browser reader',
        model: new OpenAIResponsesModel(new OpenAI({ timeout: 120_000 }), 'gpt-4.1-mini'),
        instructions: `Use only browser_id ${session.getId()!}. Read the page with Notte tools.`,
        mcpServers: [server],
        outputType: z.object({ title: z.string() }),
      });
      const answer = await new Runner({ tracingDisabled: true }).run(agent, 'Visit https://example.com and return its page title.', {
        maxTurns: 8,
      });
      if (!answer.finalOutput) throw new Error('The agent returned no title');
      console.log(answer.finalOutput.title);
      return { title: answer.finalOutput.title, session_id: session.getId()! };
    } catch {
      operationFailed = true;
      throw new Error(`OpenAI agent failed (session ${session.getId()!})`);
    } finally {
      try {
        await server.close();
      } catch {
        if (!operationFailed) throw new Error(`OpenAI MCP cleanup failed (session ${session.getId()!})`);
      }
    }
  });
  ```
</CodeGroup>

Both examples print `Example Domain`. The application owns the session and exposes `browser_action`, `browser_observe`, and `browser_scrape`. `browser_action` can also click elements and fill forms. Closing the MCP connection alone does not stop a browser; the outer Notte session scope handles cleanup. OpenAI tracing is disabled for this example.

See [Notte Browser MCP](/mcp-server) for the available tools and [session lifecycle](/features/sessions/lifecycle) for longer-lived browsers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.