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.
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]
- Make a project folder and a virtual environment:
python -m venv .venv. - Install the library:
pip install openai-agents. - Set an OpenAI API key:
export OPENAI_API_KEY=sk-.... - Define an
Agentwith a name and instructions, then run it withRunner.runand readresult.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]
- Hosted MCP server tools (
HostedMCPTool): OpenAI's Responses API calls a publicly reachable MCP server on the model's behalf. - Streamable HTTP servers (
MCPServerStreamableHttp): servers you run locally or remotely. - HTTP with Server-Sent Events (
MCPServerSse). - stdio servers (
MCPServerStdio): a local process, talking over stdin and stdout.
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:
- "The generation_span() stores the inputs/outputs of the LLM generation, and function_span() stores the inputs/outputs of function calls."[5] "By default, trace_include_sensitive_data is True."[5] It can be turned off with
RunConfig.trace_include_sensitive_data, or with the environment variableOPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA.[5] When it is off, model spans omit the request input and the response output.[5] - Audio spans include the audio, base64-encoded, by default; a separate setting turns that off.[5]
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
- What it costs. No price for the SDK or model use is cited; the MIT licence covers the code, not OpenAI's API.
- How it behaves in production. The sources are vendor docs and a read of the package's code, not a test; nothing was run.
- Other languages. Only the Python docs are cited.
- Whether the docs will change. The pages mention features still marked beta or experimental, so check the current page before relying on a setting.
If you build agents for clients and have decided what to do about tracing, I would like to compare notes: mackenzie@mackenziebowes.com.
Sources
- OpenAI, OpenAI Agents SDK documentation home (Python), read 2026-11-06, undated. openai.
github. io/ openai- agents- python/ - OpenAI, openai-agents-python repository, LICENSE file (MIT License), read 2026-11-06. github.
com/ openai/ openai- agents- python/ blob/ main/ LICENSE - OpenAI, OpenAI Agents SDK: Quickstart, read 2026-11-06, undated. openai.
github. io/ openai- agents- python/ quickstart/ - OpenAI, OpenAI Agents SDK: Model context protocol (MCP), read 2026-11-06, undated. openai.
github. io/ openai- agents- python/ mcp/ - OpenAI, OpenAI Agents SDK: Tracing, read 2026-11-06, undated. openai.
github. io/ openai- agents- python/ tracing/ - OpenAI, OpenAI Agents SDK: Models, read 2026-11-06, undated. openai.
github. io/ openai- agents- python/ models/ - 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.