How to Migrate from Chat Completions to Responses API with set_default_openai_api in openai‑agents‑python

Call agents.set_default_openai_api("responses") once at startup to switch the global default from Chat Completions to the Responses API, then remove explicit use_responses flags from your OpenAIProvider instances.

The openai‑agents‑python library supports two high‑level LLM backends: the legacy Chat Completions endpoint and the newer Responses endpoint (which supports both HTTP and WebSocket transports). While the library now defaults to Responses on the main branch, existing code often hard‑codes use_responses=False. The set_default_openai_api helper lets you migrate globally without touching every provider instantiation.

Understanding the API Modes in openai‑agents‑python

Chat Completions vs. Responses API

The library abstracts the underlying OpenAI endpoints through two distinct model classes:

API	Entry point	Transport
Chat Completions	OpenAIChatCompletionsModel	HTTP only
Responses	OpenAIResponsesModel or OpenAIResponsesWSModel	HTTP or WebSocket

OpenAIProvider acts as the factory. When you request a model, it decides which concrete class to instantiate based on an internal _use_responses flag.

How the Global Default Works

The default value for _use_responses is stored in a shared module and controlled by the public API set_default_openai_api. Internally, this flow keeps the provider and the global config in sync:

1. Config layer (src/agents/_config.py): set_default_openai_api validates the input and forwards it to the shared state.
2. Shared state (src/agents/models/_openai_shared.py): Holds the boolean _use_responses_by_default.
3. Provider layer (src/agents/models/openai_provider.py): Reads the shared state when the use_responses constructor argument is None.

Using set_default_openai_api to Switch the Global Default

Place the configuration call at the top of your entry file (e.g., main.py) before any agent or provider is instantiated:

import agents

# Switch the global default from Chat Completions to Responses API

agents.set_default_openai_api("responses")

# Optional: choose WebSocket transport for lower latency streaming

# agents.set_default_openai_responses_transport("websocket")

Under the hood, set_default_openai_api is defined in src/agents/_config.py (lines 27‑31) and delegates to _openai_shared.set_use_responses_by_default:

# src/agents/_config.py

def set_default_openai_api(api: Literal["chat_completions", "responses"]) -> None:
    if api == "chat_completions":
        _openai_shared.set_use_responses_by_default(False)
    else:
        _openai_shared.set_use_responses_by_default(True)

Once set, any new OpenAIProvider instantiated without an explicit use_responses argument will automatically use the Responses API.

Migrating Existing Code Step‑by‑Step

Step 1: Set the Default Early

Add the global switch immediately after your imports and before any business logic:

import agents
from agents import OpenAIProvider

agents.set_default_openai_api("responses")

According to the test suite in tests/test_config.py (lines 60‑73), this call mutates the shared global state and affects all subsequent provider instantiations.

Step 2: Remove Explicit use_responses Flags

Scan your codebase for OpenAIProvider(use_responses=False) and delete the argument. The provider constructor (lines 85‑89 in src/agents/models/openai_provider.py) checks the global default when the parameter is None:

# Old (Chat Completions)

# provider = OpenAIProvider(use_responses=False)

# New (Responses API via global default)

provider = OpenAIProvider()
model = provider.get_model("gpt-4o")  # Returns OpenAIResponsesModel

Step 3: Choose Transport (Optional)

For streaming use cases, you may prefer WebSocket over HTTP. Set the transport globally:

agents.set_default_openai_responses_transport("websocket")

Valid values are "http" and "websocket". This affects only the OpenAIResponsesModel selection logic.

Step 4: Verify the Model Type

Add a quick assertion or log statement to confirm the migration worked:

model = provider.get_model("gpt-4o")
assert isinstance(model, agents.models.openai_responses.OpenAIResponsesModel)
print(f"Using model class: {model.__class__.__name__}")

Reverting or Using Mixed Modes

If you need to temporarily revert a single provider to Chat Completions while keeping the global default as Responses, pass the flag explicitly:

# Force Chat Completions for this specific provider

chat_provider = OpenAIProvider(use_responses=False)

Conversely, you can force Responses even when the global default is still Chat Completions:

resp_provider = OpenAIProvider(use_responses=True)

The explicit argument always overrides the global default defined by set_default_openai_api.

Key Source Files and Implementation Details

File	Purpose
src/agents/_config.py	Exposes set_default_openai_api and set_default_openai_responses_transport (lines 27‑31).
src/agents/models/_openai_shared.py	Stores the global _use_responses_by_default flag accessed by providers (lines 36‑41).
src/agents/models/openai_provider.py	Provider constructor reads the shared flag when use_responses is None (lines 85‑89).
tests/test_config.py	Validates the default switch behavior (lines 60‑73).

Summary

• Call agents.set_default_openai_api("responses") at startup to switch the global default from Chat Completions to the Responses API without editing every provider instantiation.
• Remove use_responses=False arguments from OpenAIProvider calls; the constructor now reads the global default from src/agents/models/_openai_shared.py.
• Optionally set the transport to "websocket" via agents.set_default_openai_responses_transport for lower latency streaming.
• Override per‑instance when needed by passing use_responses=True/False explicitly to OpenAIProvider.

Frequently Asked Questions

What is the difference between Chat Completions and the Responses API in openai‑agents‑python?

The Chat Completions endpoint uses the OpenAIChatCompletionsModel class and supports HTTP transport only. The Responses endpoint uses OpenAIResponsesModel (or OpenAIResponsesWSModel for WebSocket) and offers both HTTP and WebSocket transports, providing lower latency for streaming use cases.

Where is set_default_openai_api defined and how does it work?

The function is defined in src/agents/_config.py (lines 27‑31). It accepts a literal string "chat_completions" or "responses" and updates the global flag _use_responses_by_default stored in src/agents/models/_openai_shared.py. Subsequent OpenAIProvider instances read this flag when the use_responses constructor argument is not explicitly provided.

Can I use both APIs in the same application?

Yes. While you can set a global default with set_default_openai_api, you can override the choice for any individual provider by passing use_responses=True (for Responses) or use_responses=False (for Chat Completions) directly to the OpenAIProvider constructor. This explicit argument always takes precedence over the global configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}