# OpenAI Agents SDK Documentation (Full Context)

> Extended reference map for the OpenAI Agents SDK documentation site. Use these curated links when assembling prompts that need authoritative guidance on building, operating, and extending agentic applications with the SDK.

The Agents SDK delivers a focused set of Python primitives—agents, tools, guardrails, handoffs, sessions, and tracing—plus voice and realtime interfaces. The pages below provide detailed walkthroughs, architectural patterns, and API-level documentation for integrating those capabilities into production systems.

## Getting Started and Orientation
- [Overview](https://openai.github.io/openai-agents-python/): Conceptual tour of the SDK, covering the core agent loop, motivation, installation snippet, and a runnable hello-world.
- [Quickstart](https://openai.github.io/openai-agents-python/quickstart/): Guided setup from environment preparation through running and monitoring your first agent, including troubleshooting tips.
- [Example Gallery](https://openai.github.io/openai-agents-python/examples/): Realistic Python samples that demonstrate tool orchestration, guardrails, streaming, and integrations with external systems.
- [Release notes](https://openai.github.io/openai-agents-python/release/): Version-by-version change log with migration notes for breaking updates.
- [Usage and pricing](https://openai.github.io/openai-agents-python/usage/): Explains how token usage is tracked, how to retrieve usage metadata, and how to forecast cost for different deployment patterns.
- [Configuration](https://openai.github.io/openai-agents-python/config/): Centralized reference for tuning model settings, retries, rate limits, timeouts, logging, and runner behavior.

## Core Agent Workflows
- [Agents](https://openai.github.io/openai-agents-python/agents/): Defines agent objects, instruction design, tool registration, guardrail attachment, streaming options, and lifecycle hooks.
- [Running agents](https://openai.github.io/openai-agents-python/running_agents/): Covers synchronous and asynchronous execution, concurrency controls, background tasks, cancellation, and handling failures.
- [Sessions](https://openai.github.io/openai-agents-python/sessions/): Describes persistent session state, conversation threading, history pruning, and custom session storage backends.
- [Context strategies](https://openai.github.io/openai-agents-python/context/): Techniques for tailoring prompts, managing attachments, trimming history, and injecting auxiliary context into runs.
- [Results](https://openai.github.io/openai-agents-python/results/): Breaks down the result object, including final output, tool call transcripts, intermediate messages, and metadata fields.
- [Streaming](https://openai.github.io/openai-agents-python/streaming/): Shows how to subscribe to incremental events, stream tool progress, and render partial model outputs in real time.
- [REPL](https://openai.github.io/openai-agents-python/repl/): Interactive runner for exploring agent behavior, step-by-step execution, and debugging tool calls.
- [Visualization](https://openai.github.io/openai-agents-python/visualization/): Demonstrates embeddable visualizations for session timelines, message flows, and tool interactions.

## Coordination, Safety, and Tooling
- [Handoffs](https://openai.github.io/openai-agents-python/handoffs/): Implements delegation between agents, argument passing, completion handling, and error recovery across agent boundaries.
- [Multi-agent patterns](https://openai.github.io/openai-agents-python/multi_agent/): Architecture playbook for designing specialist teams, escalation workflows, and role-based collaboration strategies.
- [Guardrails](https://openai.github.io/openai-agents-python/guardrails/): Create synchronous or asynchronous checks, short-circuit runs, and emit structured validation reports.
- [Tools](https://openai.github.io/openai-agents-python/tools/): Turn Python callables into structured tools, manage schemas, compose tool contexts, and test tool execution paths.
- [Model Context Protocol](https://openai.github.io/openai-agents-python/mcp/): Integrate MCP servers so agents can dynamically request data or actions from external providers via a standard protocol.

## Modality-Specific Guides
- [Voice quickstart](https://openai.github.io/openai-agents-python/voice/quickstart/): Build an end-to-end voice assistant with streaming transcription, text-to-speech, and event-driven responses.
- [Voice pipeline](https://openai.github.io/openai-agents-python/voice/pipeline/): Customize audio capture, buffering, model invocation, and playback in voice-first experiences.
- [Voice tracing](https://openai.github.io/openai-agents-python/voice/tracing/): Inspect voice session traces, latency breakdowns, and audio event timelines.
- [Realtime quickstart](https://openai.github.io/openai-agents-python/realtime/quickstart/): Launch realtime agents over websockets (WebRTC is not available in the Python SDK), subscribe to events, and manage low-latency execution.
- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into realtime session lifecycle, event schemas, concurrency, and backpressure handling.

## Models and Provider Integrations
- [Model catalog](https://openai.github.io/openai-agents-python/models/): Lists supported OpenAI and partner models with guidance on selecting capabilities for different workloads.
- [LiteLLM integration](https://openai.github.io/openai-agents-python/models/litellm/): Configure LiteLLM as a provider, map model aliases, and route requests across heterogeneous backends.

## API Reference – Agents SDK Core
- [API index](https://openai.github.io/openai-agents-python/ref/index/): Directory of all documented modules, classes, and functions in the SDK.
- [agents.Agent](https://openai.github.io/openai-agents-python/ref/agent/): Constructor arguments, behaviors, guardrail hooks, and serialization helpers.
- [runs and runners](https://openai.github.io/openai-agents-python/ref/run/): Runner interfaces for launching agents, streaming events, handling cancellations, and background execution.
- [memory interfaces](https://openai.github.io/openai-agents-python/ref/memory/): Session memory primitives, storage adapters, and utilities for retrieving historical context.
- [repl utilities](https://openai.github.io/openai-agents-python/ref/repl/): Programmatic access to the interactive REPL loop and inspection helpers.
- [tool base classes](https://openai.github.io/openai-agents-python/ref/tool/): Tool registration, invocation, and structured argument parsing.
- [tool context helpers](https://openai.github.io/openai-agents-python/ref/tool_context/): Manage shared resources, dependency injection, and cleanup for tool execution.
- [result objects](https://openai.github.io/openai-agents-python/ref/result/): Fields exposed on run results, including final content, tool call summaries, and attachments.
- [stream events](https://openai.github.io/openai-agents-python/ref/stream_events/): Event models emitted during streaming runs and their payload schemas.
- [handoffs module](https://openai.github.io/openai-agents-python/ref/handoffs/): Programmatic API for defining, routing, and resolving handoffs between agents.
- [lifecycle callbacks](https://openai.github.io/openai-agents-python/ref/lifecycle/): Hooks for intercepting agent stages, customizing evaluation, and logging intermediate data.
- [items API](https://openai.github.io/openai-agents-python/ref/items/): Low-level primitives that represent agent messages, tool calls, and attachments.
- [run context utilities](https://openai.github.io/openai-agents-python/ref/run_context/): Context managers and helpers for passing metadata through nested tool executions.
- [usage tracking](https://openai.github.io/openai-agents-python/ref/usage/): Inspect token usage, durations, and cost metrics from completed runs.
- [exceptions](https://openai.github.io/openai-agents-python/ref/exceptions/): Exception hierarchy raised by the SDK and recommendations for resilient error handling.
- [guardrail APIs](https://openai.github.io/openai-agents-python/ref/guardrail/): Build custom guardrails, interpret validation outcomes, and integrate enforcement logic.
- [model settings](https://openai.github.io/openai-agents-python/ref/model_settings/): Shared configuration objects for model parameters, temperature, and tool invocation settings.
- [agent output models](https://openai.github.io/openai-agents-python/ref/agent_output/): Typed models describing message content, tool calls, and aggregated agent responses.
- [function schema utilities](https://openai.github.io/openai-agents-python/ref/function_schema/): Helpers for generating JSON schemas from Python functions and Pydantic models.
- [model interfaces](https://openai.github.io/openai-agents-python/ref/models/interface/): Abstractions for pluggable model providers.
- [OpenAI chat completions provider](https://openai.github.io/openai-agents-python/ref/models/openai_chatcompletions/): Implementation details for the chat-completions-based model adapter.
- [OpenAI responses provider](https://openai.github.io/openai-agents-python/ref/models/openai_responses/): Implementation details for the responses API adapter.
- [MCP server helpers](https://openai.github.io/openai-agents-python/ref/mcp/server/): Utilities for building MCP servers that expose tools to agents.
- [MCP client utilities](https://openai.github.io/openai-agents-python/ref/mcp/util/): Helpers for consuming MCP servers from within agents.

## API Reference – Tracing
- [Tracing overview](https://openai.github.io/openai-agents-python/ref/tracing/index/): End-to-end API documentation for tracing components.
- [Creating traces](https://openai.github.io/openai-agents-python/ref/tracing/create/): Programmatic APIs for instantiating traces and attaching metadata.
- [Trace model](https://openai.github.io/openai-agents-python/ref/tracing/traces/): Data models representing traces and their relationships.
- [Span model](https://openai.github.io/openai-agents-python/ref/tracing/spans/): Span structure, timing data, and message attribution.
- [Processor interface](https://openai.github.io/openai-agents-python/ref/tracing/processor_interface/): Contract for custom processors that consume trace events.
- [Bundled processors](https://openai.github.io/openai-agents-python/ref/tracing/processors/): Built-in processors for exporting traces to external systems.
- [Tracing scope](https://openai.github.io/openai-agents-python/ref/tracing/scope/): Context managers that manage active traces and spans.
- [Tracing setup](https://openai.github.io/openai-agents-python/ref/tracing/setup/): Configuration helpers for initializing tracing in applications and tests.
- [Span data utilities](https://openai.github.io/openai-agents-python/ref/tracing/span_data/): Helper models for span payloads and events.
- [Tracing utility helpers](https://openai.github.io/openai-agents-python/ref/tracing/util/): Miscellaneous tracing utilities, exporters, and logging helpers.

## API Reference – Realtime
- [Realtime agent API](https://openai.github.io/openai-agents-python/ref/realtime/agent/): Programmatic interface for realtime agents.
- [Realtime runner](https://openai.github.io/openai-agents-python/ref/realtime/runner/): Manage realtime execution loops, concurrency, and cleanup.
- [Realtime session](https://openai.github.io/openai-agents-python/ref/realtime/session/): Lifecycle and state management for realtime sessions.
- [Realtime events](https://openai.github.io/openai-agents-python/ref/realtime/events/): Event payload types delivered over realtime channels.
- [Realtime config](https://openai.github.io/openai-agents-python/ref/realtime/config/): Configuration models for realtime transports and behaviors.
- [Realtime model interface](https://openai.github.io/openai-agents-python/ref/realtime/model/): Interfaces for plugging in realtime-capable models.

## API Reference – Voice
- [Voice pipeline API](https://openai.github.io/openai-agents-python/ref/voice/pipeline/): Programmatic control over the voice pipeline and event flow.
- [Voice workflow helpers](https://openai.github.io/openai-agents-python/ref/voice/workflow/): Orchestrate conversational voice workflows.
- [Voice input models](https://openai.github.io/openai-agents-python/ref/voice/input/): Structured representations of microphone and streaming audio input.
- [Voice result models](https://openai.github.io/openai-agents-python/ref/voice/result/): Output schema for voice responses, transcripts, and tool invocations.
- [Voice pipeline config](https://openai.github.io/openai-agents-python/ref/voice/pipeline_config/): Configuration options for buffer sizes, concurrency, and model routing.
- [Voice events](https://openai.github.io/openai-agents-python/ref/voice/events/): Event payloads describing voice session updates.
- [Voice exceptions](https://openai.github.io/openai-agents-python/ref/voice/exceptions/): Exception types for voice pipelines and error handling guidance.
- [Voice model adapters](https://openai.github.io/openai-agents-python/ref/voice/model/): Interfaces for voice-enabled models and synthesis engines.
- [Voice utility helpers](https://openai.github.io/openai-agents-python/ref/voice/utils/): Audio conversion, streaming helpers, and testing utilities.
- [OpenAI voice provider](https://openai.github.io/openai-agents-python/ref/voice/models/openai_provider/): Adapter for OpenAI voice models.
- [OpenAI speech-to-text provider](https://openai.github.io/openai-agents-python/ref/voice/models/openai_stt/): Integration for STT models used in the pipeline.
- [OpenAI text-to-speech provider](https://openai.github.io/openai-agents-python/ref/voice/models/openai_tts/): Adapter for OpenAI TTS output.

## API Reference – Extensions
- [Handoff filters extension](https://openai.github.io/openai-agents-python/ref/extensions/handoff_filters/): Build filters that decide whether to trigger a handoff.
- [Handoff prompt extension](https://openai.github.io/openai-agents-python/ref/extensions/handoff_prompt/): Customize prompt templates used when transferring control.
- [LiteLLM extension](https://openai.github.io/openai-agents-python/ref/extensions/litellm/): Adapter for using LiteLLM-managed providers inside the SDK.
- [SQLAlchemy session memory](https://openai.github.io/openai-agents-python/ref/extensions/memory/sqlalchemy_session/): Persist agent session history to SQL databases.

## Optional
- [Japanese documentation](https://openai.github.io/openai-agents-python/ja/): Localized guides mirroring the core English documentation.
- [GitHub repository](https://github.com/openai/openai-agents-python): Source code, issues, and contribution resources.
- [Agents SDK package on PyPI](https://pypi.org/project/openai-agents/): Distribution page with installation command and release history.
