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

> Easily migrate from Chat Completions to the Responses API in openai-agents-python. Update your default API setting once and simplify your provider instances for a smoother workflow.

- Repository: [OpenAI/openai-agents-python](https://github.com/openai/openai-agents-python)
- Tags: migration-guide
- Published: 2026-04-17

---

**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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/_openai_shared.py)): Holds the boolean `_use_responses_by_default`.
3. **Provider layer** ([`src/agents/models/openai_provider.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/main.py)) before any agent or provider is instantiated:

```python
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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/_config.py) (lines 27‑31) and delegates to `_openai_shared.set_use_responses_by_default`:

```python

# 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:

```python
import agents
from agents import OpenAIProvider

agents.set_default_openai_api("responses")

```

According to the test suite in [`tests/test_config.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/openai_provider.py)) checks the global default when the parameter is `None`:

```python

# 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:

```python
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:

```python
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:

```python

# 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:

```python
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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/_config.py) | Exposes `set_default_openai_api` and `set_default_openai_responses_transport` (lines 27‑31). |
| [`src/agents/models/_openai_shared.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/openai_provider.py) | Provider constructor reads the shared flag when `use_responses` is `None` (lines 85‑89). |
| [`tests/test_config.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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.