How to start with the OpenAI Agents SDK

What OpenAI's own docs say about the Agents SDK, read on 2026-11-06: the four steps to a first agent, the four ways to connect an MCP server, and that tracing is on by default and includes model inputs and outputs.

By Mackenzie Bowes · mackenzie@mackenziebowes.com · @_mackenziebowes on X

Contents

The OpenAI Agents SDK is an MIT-licensed Python library for building agents on OpenAI's models. A first agent takes four commands. The thing to know before using it on client work is in the tracing guide: tracing is on by default, and by default the record sent to OpenAI includes what went into and out of each model call and tool call. Everything below comes from OpenAI's own documentation and repository, read on 2026-11-06, so it states what the vendor says and not what a test showed. This page covers the Python SDK only.

What it is

OpenAI describes it this way: "The OpenAI Agents SDK enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions."[1] OpenAI calls it "a production-ready upgrade of our previous experimentation for agents, Swarm."[1] The SDK has a small set of parts: agents (models with instructions and tools), handoffs between agents, and guardrails that check inputs and outputs.[1] The repository's LICENSE file is the MIT License.[2]

OpenAI also says when not to use it: use the Responses API directly when "you want to own the loop, tool dispatch, and state handling yourself", and the SDK when "you want the runtime to manage turns, tool execution, guardrails, handoffs, or sessions."[1]

A first agent from the quickstart

The quickstart has these steps.[3]

  1. Make a project folder and a virtual environment: python -m venv .venv.
  2. Install the library: pip install openai-agents.
  3. Set an OpenAI API key: export OPENAI_API_KEY=sk-....
  4. Define an Agent with a name and instructions, then run it with Runner.run and read result.final_output.

Step 3 means the first run calls OpenAI's API with your key. The quickstart and the docs home do not state a price for the SDK or for the models; OpenAI's API price list is not cited, so this page gives no cost.[1][3] The docs home also says the SDK uses the Responses API by default for OpenAI models.[1] How long a full build takes, as agencies quote it and as one set of enterprise rollouts measured it, is on How long does it take to build an AI agent?.

Connecting an MCP server

The MCP page says the Python SDK "understands multiple MCP transports" and lists four ways in, each with the need it serves:[4]

The docs add a warning: "Connect only to servers you trust, use least-privilege credentials, keep access tokens in authorization fields or headers rather than URLs, and require approval for sensitive operations."[4] The first option differs from the other three in where the call runs: for hosted tools, OpenAI's service makes the call to the MCP server, so the server must be reachable from OpenAI.[4] Which MCP connectors exist for QuickBooks, HubSpot and Google Workspace, and what each can read and write, is on AI connectors for QuickBooks, HubSpot, Google. The glossary entry on the Model Context Protocol explains what MCP is.

What tracing records and where it goes

The tracing guide says: "Tracing is enabled by default."[5] It records "LLM generations, tool calls, handoffs, guardrails, and even custom events", and the default setup "exports the spans and traces to the OpenAI backend in batches."[5]

Two defaults matter for client data:

Ways to stop it, from the same guide: "You can globally disable tracing by setting the env var OPENAI_AGENTS_DISABLE_TRACING=1", disable it in code with set_tracing_disabled(True), or for one run with tracing_disabled in the run config.[5] "Tracing is unavailable for organizations that use OpenAI's APIs under a Zero Data Retention (ZDR) policy."[5] What OpenAI's own data terms say about abuse logs and Zero Data Retention approval is on OpenAI data use and chatbot liability.

Adding your own trace processor does not stop the OpenAI export: "Adding a processor with add_trace_processor() also leaves the default OpenAI exporter registered."[5] To send traces only to your own destination, the guide says to replace the processors with set_trace_processors(), so that "traces will not be sent to the OpenAI backend unless you include a TracingProcessor that does so."[5] It also notes that with non-OpenAI models you can give the exporter an OpenAI API key to get "free tracing" in OpenAI's dashboard.[5]

Checked against the code

The latest package, version 0.24.0, was downloaded from PyPI with pip, unzipped and read; it was not installed or run.[7] It agrees with the docs on four points: trace_include_sensitive_data defaults to true unless the environment variable says otherwise, the default exporter's address is https://api.openai.com/v1/traces/ingest, setting OPENAI_AGENTS_DISABLE_TRACING turns tracing off, and the package metadata says MIT licence and Python 3.10 or later.[7] The version number is below 1.0, so the project has not yet declared a stable interface; that is an inference, not an OpenAI statement.

Models other than OpenAI's

The SDK's built-in support is for OpenAI models through the Responses API (recommended) and the Chat Completions API.[6] For other providers the Models guide points to built-in integration points first and to third-party adapters (Any-LLM, LiteLLM) only "when the SDK's built-in provider integration points are not enough."[6] It calls the adapters beta and tells you to "validate the provider path you plan to ship".[6]

Not yet proven

If you build agents for clients and have decided what to do about tracing, I would like to compare notes: mackenzie@mackenziebowes.com.

Sources

  1. OpenAI, OpenAI Agents SDK documentation home (Python), read 2026-11-06, undated. openai.github.io/openai-agents-python/
  2. OpenAI, openai-agents-python repository, LICENSE file (MIT License), read 2026-11-06. github.com/openai/openai-agents-python/blob/main/LICENSE
  3. OpenAI, OpenAI Agents SDK: Quickstart, read 2026-11-06, undated. openai.github.io/openai-agents-python/quickstart/
  4. OpenAI, OpenAI Agents SDK: Model context protocol (MCP), read 2026-11-06, undated. openai.github.io/openai-agents-python/mcp/
  5. OpenAI, OpenAI Agents SDK: Tracing, read 2026-11-06, undated. openai.github.io/openai-agents-python/tracing/
  6. OpenAI, OpenAI Agents SDK: Models, read 2026-11-06, undated. openai.github.io/openai-agents-python/models/
  7. openai-agents 0.24.0, the latest version listed by pip on 2026-11-06; files read from the downloaded wheel (extracts saved in the lab library), not from the PyPI web page. pypi.org/project/openai-agents/

Terms on this page

  • Agentic AI: AI that works toward a goal by planning steps, making decisions and acting with more or less independence.
  • AI agent: A system where a language model decides for itself how to do a task and which tools to use.
  • Model Context Protocol: An open standard for connecting AI applications to outside tools and data.
  • Tool call: A request from an AI model to run one action, such as a search or a file write, which the surrounding program carries out.