Advanced

Python SDK

The openai Python library is the primary way to interact with OpenAI's API from Python applications. It provides synchronous and asynchronous clients, full type safety across all request and response fields, streaming support, and a separate Agents SDK for building agentic workflows.

Installation

pip install openai

Requires Python 3.9 or later. The library is available on PyPI as openaiand on GitHub at openai/openai-python. Set your API key as an environment variable so the client picks it up automatically:

export OPENAI_API_KEY="sk-proj-..."  # Linux/macOS
set OPENAI_API_KEY=sk-proj-...       # Windows CMD

Synchronous Client

The OpenAI() client is synchronous — calls block until the response is returned. Suitable for scripts, command-line tools, and applications that do not require concurrency:

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from environment

response = client.responses.create(
    model="gpt-5",
    input="Explain the difference between RAG and fine-tuning in two paragraphs."
)

print(response.output_text)

Asynchronous Client

The AsyncOpenAI() client uses httpx under the hood and supports Python's async/await syntax. Use this in FastAPI handlers, async scripts, and anywhere you need to make concurrent API calls without blocking the event loop:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main():
    response = await client.responses.create(
        model="gpt-5",
        input="What are the key considerations for deploying LLMs in production?"
    )
    print(response.output_text)

asyncio.run(main())

Streaming

Streaming returns tokens as they are generated rather than waiting for the full response. This gives a more responsive user experience in interactive applications.

Synchronous streaming

with client.responses.stream(
    model="gpt-5",
    input="Write a short story about a robot learning to paint."
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)

Asynchronous streaming

async with client.responses.stream(
    model="gpt-5",
    input="Describe the architecture of a transformer model."
) as stream:
    async for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)

Full Type Safety

All request parameters and response fields are fully typed using Python type annotations. Your IDE will autocomplete field names, warn you about incorrect types, and catch structural errors before runtime. This makes the SDK significantly more ergonomic than making raw HTTP requests with requests or httpx.

The SDK also validates required fields at call time with descriptive errors, so missing a required parameter surfaces immediately rather than as an unexpected API error.

Agents SDK

For building agentic applications, OpenAI provides a separate package in 2025:

pip install openai-agents

The Agents SDK provides higher-level primitives specifically designed for multi-step, tool-using workflows:

Tool use: Define tools as Python functions with type annotations; the SDK handles schema generation and routing automatically
Agent handoffs: One agent can delegate to a specialist sub-agent, enabling modular multi-agent architectures
Guardrails: Programmable safety checks that intercept inputs or outputs before they reach or leave the model
Tracing: Built-in observability showing each tool call, reasoning step, and handoff in a structured trace — viewable in the OpenAI Platform dashboard

The Agents SDK is the recommended foundation for production agentic applications on OpenAI infrastructure, reducing the boilerplate required to build reliable multi-step workflows.

Common Patterns Summary

Pattern	Client	Method
Blocking completion	`OpenAI()`	`client.responses.create(...)`
Async completion	`AsyncOpenAI()`	`await client.responses.create(...)`
Sync streaming	`OpenAI()`	`with client.responses.stream(...)`
Async streaming	`AsyncOpenAI()`	`async with client.responses.stream(...)`
Agentic workflows	`openai-agents`	Agent, Tool, Handoff, Guardrail primitives

Checklist

What is the minimum Python version required by the openai library?
What is the difference between OpenAI() and AsyncOpenAI() and when would you use each?
How does streaming improve user experience in interactive applications?
What four capabilities does the Agents SDK add beyond the base openai library?
How does the SDK pick up your API key without you passing it explicitly in code?