Implementation:Openai Openai agents python External Model Integration Pattern
| Knowledge Sources | |
|---|---|
| Domains | Agent_Configuration, Model_Integration, Design_Pattern |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Shows how to use an external (non-OpenAI) model with the SDK via OpenAIChatCompletionsModel and a custom AsyncOpenAI client pointing to a local Ollama instance.
Description
The hello_world_gpt_oss.py example demonstrates the SDK's model abstraction layer, which allows any OpenAI-compatible API endpoint to serve as the backing model for an agent. Instead of using the default OpenAI API, this example creates an OpenAIChatCompletionsModel instance configured with a custom AsyncOpenAI client that points to a local Ollama server running at http://localhost:11434/v1.
The pattern involves three key steps: (1) creating an AsyncOpenAI client with a custom base_url and api_key, (2) wrapping it in an OpenAIChatCompletionsModel with the desired model identifier (e.g., "gpt-oss:20b"), and (3) passing this model object to the Agent constructor via the model= parameter. Tracing is disabled via set_tracing_disabled(True) since external models do not support OpenAI's tracing infrastructure.
This pattern is critical for teams that want to use the Agents SDK's orchestration features (handoffs, tools, guardrails) while running open-source or self-hosted models. The example notes that custom output types may not work well with non-OpenAI models, recommending the default "text" output type for maximum compatibility.
Usage
Use this pattern when you need to connect the Agents SDK to any OpenAI-compatible API endpoint, such as Ollama, LM Studio, vLLM, or any other local or remote inference server that implements the OpenAI Chat Completions API. This is especially useful for development, testing, privacy-sensitive workloads, or cost optimization scenarios.
Code Reference
Source Location
- Repository: Openai_Openai_agents_python
- File: examples/basic/hello_world_gpt_oss.py
- Lines: 1-39
Signature
gpt_oss_model = OpenAIChatCompletionsModel(
model="gpt-oss:20b",
openai_client=AsyncOpenAI(
base_url="http://localhost:11434/v1",
api_key="ollama",
),
)
agent = Agent(
name="Assistant",
instructions="You're a helpful assistant. You provide a concise answer to the user's question.",
model=gpt_oss_model,
)
Import
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, Runner, set_tracing_disabled
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| model | str | Yes | The model identifier recognized by the external server (e.g., "gpt-oss:20b") |
| openai_client | AsyncOpenAI | Yes | Custom async OpenAI client configured with the external server's base_url and api_key |
| base_url | str | Yes | The URL of the external OpenAI-compatible API endpoint (e.g., "http://localhost:11434/v1") |
| api_key | str | Yes | API key for the external server (can be a placeholder like "ollama" for local servers) |
Outputs
| Name | Type | Description |
|---|---|---|
| result.final_output | str | The text response from the external model, processed through the Agents SDK pipeline |
Usage Examples
Connect to Ollama
import asyncio
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, Runner, set_tracing_disabled
set_tracing_disabled(True)
gpt_oss_model = OpenAIChatCompletionsModel(
model="gpt-oss:20b",
openai_client=AsyncOpenAI(
base_url="http://localhost:11434/v1",
api_key="ollama",
),
)
agent = Agent(
name="Assistant",
instructions="You're a helpful assistant. You provide a concise answer to the user's question.",
model=gpt_oss_model,
)
async def main():
result = await Runner.run(agent, "Tell me about recursion in programming.")
print(result.final_output)
asyncio.run(main())
Connect to LM Studio
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, set_tracing_disabled
set_tracing_disabled(True)
lm_studio_model = OpenAIChatCompletionsModel(
model="local-model",
openai_client=AsyncOpenAI(
base_url="http://localhost:1234/v1",
api_key="lm-studio",
),
)
agent = Agent(
name="Local Assistant",
instructions="You are a helpful assistant.",
model=lm_studio_model,
)