OpenAI Agents SDK

1 · What it is

OpenAI’s Agents SDK is an open-source Python toolkit from OpenAI for building AI agents. Here, an agent means a language model with two extras. It has instructions, like a job description. It also has tools, which are actions it can take, such as calling a Python function. SDK stands for software development kit: a set of ready-made code pieces. OpenAI calls it a production-ready upgrade of Swarm, an earlier experiment. It has few parts, so it is quick to learn.

An agent is a model plus its instructions, tools, guardrails and handoffs. A tool can be almost any Python function. The SDK reads the function and writes a short description of it for the model. That description is called a schema. The SDK can also connect agents to MCP (Model Context Protocol) servers, which offer tools to AI apps. A handoff lets one agent pass the conversation to another agent. The model sees a handoff as just another tool, with a name such as transfer_to_refund_agent. An agent can also be offered to another agent as a tool. Guardrails are checks on the user’s input and the agent’s output.

At the centre sits the runner. You give it a starting agent and some input, and it repeats one loop. First it calls the model for the current agent. If the model asks for tools, the runner runs them, adds the results and loops again. If the model asks for a handoff, the runner switches to the new agent and loops again. When the model gives an answer in the expected form and asks for no tools, the loop ends. A turn limit stops a run that goes on too long, and reports an error.

Here is an everyday example. A shop has a front-desk (triage) agent that reads each message and decides who should handle it, and a refund agent that knows the returns rules. A customer writes, “My headphones arrived broken, can I get my money back?” A quick input guardrail also checks the message. The front-desk agent sees a refund question and hands off. The refund agent might call a tool that looks up the order, then writes the reply.

Guardrails come with timing choices. OpenAI says a quick, low-cost model can do the checking. If it spots malicious use, it can raise an error right away and save time and money. In blocking mode the expensive model is guaranteed not to start before the check. In parallel mode, the big model could be running already by the time the check is done. Input checks happen only at the opening agent. Output checks happen only at the agent giving the last answer.

Sessions handle memory between turns. A session stores the conversation history, so the next run can see what was said before. This suits chat apps where the agent should remember earlier messages. The SDK also has built-in ways to involve a human during a run.

Tracing is switched on by default. It records model calls, tool calls, handoffs and guardrails for each run, so you can debug and view the whole workflow. Tracing is not available to groups that have a Zero Data Retention policy with OpenAI.

An API is how one program asks another for something. With OpenAI models, the SDK uses OpenAI’s Responses API by default and wraps model calls in its own higher-level runtime. It also supports the Chat Completions API and more than 100 other language models. The Python package needs Python 3.10 or newer, and a JavaScript and TypeScript version exists too. If you would rather run the loop, tool calls and saved progress yourself, OpenAI suggests using the Responses API directly.