Skip to content

openai

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

openai

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
agent_framework_openai
agent_framework_openai
 
 
tests
tests
 
 
AGENTS.md
AGENTS.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 

README.md

agent-framework-openai

OpenAI integration for Microsoft Agent Framework.

This package provides:

  • OpenAIChatClient for the OpenAI Responses API
  • OpenAIChatCompletionClient for the Chat Completions API
  • OpenAIEmbeddingClient for embeddings

Installation

pip install agent-framework-openai

Which chat client should I use?

Use OpenAIChatClient for new work unless you specifically need the Chat Completions API.

  • OpenAIChatClient uses the Responses API and is the preferred general-purpose chat client.
  • OpenAIChatCompletionClient uses the Chat Completions API and is mainly for compatibility with existing Chat Completions-based integrations.

The previous deprecated Responses alias has been removed. Use OpenAIChatClient directly.

Environment variables

OpenAI

These variables are used when the client is configured for OpenAI:

Variable Purpose
OPENAI_API_KEY OpenAI API key
OPENAI_ORG_ID OpenAI organization ID
OPENAI_BASE_URL Custom OpenAI-compatible base URL
OPENAI_MODEL Generic fallback model
OPENAI_CHAT_MODEL Preferred model for OpenAIChatClient
OPENAI_CHAT_COMPLETION_MODEL Preferred model for OpenAIChatCompletionClient
OPENAI_EMBEDDING_MODEL Preferred model for OpenAIEmbeddingClient

Model lookup order:

  • OpenAIChatClient: OPENAI_CHAT_MODEL -> OPENAI_MODEL
  • OpenAIChatCompletionClient: OPENAI_CHAT_COMPLETION_MODEL -> OPENAI_MODEL
  • OpenAIEmbeddingClient: OPENAI_EMBEDDING_MODEL -> OPENAI_MODEL

These model variables are only consulted when you do not pass model= directly. In other words, OpenAIChatClient(model="...") ignores OPENAI_CHAT_MODEL, and OpenAIChatCompletionClient(model="...") ignores OPENAI_CHAT_COMPLETION_MODEL.

Azure OpenAI

These variables are used when the client is configured for Azure OpenAI:

Variable Purpose
AZURE_OPENAI_ENDPOINT Azure OpenAI resource endpoint
AZURE_OPENAI_BASE_URL Full Azure OpenAI base URL (.../openai/v1)
AZURE_OPENAI_API_KEY Azure OpenAI API key
AZURE_OPENAI_API_VERSION Azure OpenAI API version
AZURE_OPENAI_MODEL Generic fallback deployment
AZURE_OPENAI_CHAT_MODEL Preferred deployment for OpenAIChatClient
AZURE_OPENAI_CHAT_COMPLETION_MODEL Preferred deployment for OpenAIChatCompletionClient
AZURE_OPENAI_EMBEDDING_MODEL Preferred deployment for OpenAIEmbeddingClient

Deployment lookup order:

  • OpenAIChatClient: AZURE_OPENAI_CHAT_MODEL -> AZURE_OPENAI_MODEL
  • OpenAIChatCompletionClient: AZURE_OPENAI_CHAT_COMPLETION_MODEL -> AZURE_OPENAI_MODEL
  • OpenAIEmbeddingClient: AZURE_OPENAI_EMBEDDING_MODEL -> AZURE_OPENAI_MODEL

For Azure routing, the same rule applies: the client-specific deployment variable is checked first, then the generic AZURE_OPENAI_MODEL fallback. Passing model= overrides both environment variables.

When both OpenAI and Azure environment variables are present, the generic clients prefer OpenAI when OPENAI_API_KEY is configured. To use Azure explicitly, pass azure_endpoint or credential.

OpenAI example

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(model="gpt-4.1")

Azure OpenAI example

from azure.identity.aio import AzureCliCredential

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(
    model="my-responses-deployment",
    azure_endpoint="https://my-resource.openai.azure.com",
    credential=AzureCliCredential(),
)

ChatClient vs ChatCompletionClient

Use OpenAIChatClient when you want the Responses API as your default chat surface.

Use OpenAIChatCompletionClient when you specifically need the Chat Completions API:

from agent_framework.openai import OpenAIChatCompletionClient

client = OpenAIChatCompletionClient(model="gpt-4o-mini")