OpenAI Agents SDK

By OpenAI

OpenAI's lightweight SDK for agents with tools, handoffs, and guardrails

Website ↗ Repository ↗ Docs ↗

v0.18.32026-07-17PythonMIT

#agents #tools #handoffs #python

28.1k Completely free Open source

Doc version 1.0 · Updated June 28, 2026

Related concepts

Harness Engineering Doc version 1.0 · Updated June 28, 2026 Wrapping an LLM in scaffolding — a control loop, tools, a sandbox, guardrails, and evaluation — so it behaves reliably in production.

Related tools

OpenAI

Foundation Model APIs

Pydantic AI

Structured Output & Typing

Overview

The OpenAI Agents SDK is a lightweight, provider-first framework for building agents from a few primitives: agents, tools, handoffs between agents, and guardrails.
It is the production-oriented successor to OpenAI’s Swarm experiment, with built-in tracing and a small surface area.

flowchart LR
  input[input] --> r[Runner]
  r --> agent[Agent]
  agent --> tools[tools / handoffs]
  agent --> out[final output]

The Code samples tab shows a minimal single-agent run.

When to use it

Choose it when you want a thin, composable agent loop close to the OpenAI API — especially for tool use, multi-agent handoffs, and guardrails — without adopting a larger orchestration framework.

Example

Python · run an agent

When to use

A small, unopinionated core when you want primitives — agents, tools, handoffs, guardrails — without a heavy framework.

How it flows

Define an Agent with instructions (and optional tools); the Runner executes the loop and returns the final output.

Structure

flowchart LR
  input[input] --> r[Runner]
  r --> agent[Agent]
  agent --> tools[tools / handoffs]
  agent --> out[final output]

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are concise and helpful.")
result = Runner.run_sync(agent, "Summarize what an AI agent is in one sentence.")
print(result.final_output)

Example

OpenAI Agents SDK — implementation sample

A real, runnable mini-project. Download it and run with Docker.

View samples/openai-agents-sdk_1 on GitHub ↗

June 28, 2026

OpenAI Agents SDK — implementation sample

A tiny OpenAI Agents SDK sample: it defines an agent and runs your prompt.

Configure

cd samples/openai-agents-sdk_1
cp .env.sample .env
# edit .env: set OPENAI_API_KEY (and optionally MODEL)

Run with Docker

cd samples/openai-agents-sdk_1
docker build -t aas-openai-agents .
docker run --rm --env-file .env aas-openai-agents "Summarize AI agents in one sentence."

Run with Docker (in a devcontainer with DooD)

The foreground docker run may print nothing under Docker-outside-of-Docker — run detached and follow the logs:

docker logs -f "$(docker run -d --env-file .env aas-openai-agents "Summarize AI agents in one sentence.")"

Run locally

cd samples/openai-agents-sdk_1
pip install -r requirements.txt
python app.py "Summarize AI agents in one sentence."

Example run

Output varies by model and run — LLMs are non-deterministic. One run with gpt-4o-mini:

An AI agent is an autonomous system that perceives its environment, makes decisions based on that information, and acts to achieve specific goals.

Files

.env.sample

# Copy to `.env` and add your OpenAI API key.
#   cp .env.sample .env
OPENAI_API_KEY=

MODEL=gpt-4o-mini

app.py

"""OpenAI Agents SDK: define an agent and run it.

Run:
    docker build -t aas-openai-agents .
    docker run --rm --env-file .env aas-openai-agents "Summarize AI agents in one sentence."
"""

import os
import sys

from dotenv import load_dotenv
from agents import Agent, Runner

load_dotenv()

MODEL = os.environ.get("MODEL", "gpt-4o-mini")


def main() -> None:
    prompt = " ".join(sys.argv[1:]) or "Summarize what an AI agent is in one sentence."
    agent = Agent(name="Assistant", instructions="You are concise and helpful.", model=MODEL)
    print(Runner.run_sync(agent, prompt).final_output)


if __name__ == "__main__":
    main()

Dockerfile

FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

ENTRYPOINT ["python", "app.py"]