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.

Citations and annotations

OpenAIChatClient exposes Responses API URL, file, file-path, and container-file citations through Content.annotations, using the provider-neutral Annotation(type="citation", ...) representation. URL citations retain their title, URL, and text-span indices, including SharePoint grounding citations.

Inspect content.annotations in response messages or streaming update.contents. Annotations can arrive in an update whose content.text is empty: completed content parts and output messages supply citations without repeating text that was already streamed. Annotation-added and completion events are deduplicated by item, content part, and annotation position, so separate references to the same source remain distinct. Foundry clients that inherit the Responses parser receive the same behavior.

Hosted function results

OpenAIChatClient parses hosted function_call_output items in both streaming and non-streaming responses. Each result retains its call_id for correlation with the corresponding function call. Outputs explicitly marked in_progress are deferred without claiming their deduplication ID, so an empty or partial .added placeholder cannot suppress a later .done result. Completed empty results remain valid.

Rich output parts are available through the function result's items; the backward-compatible result field contains only their text. Image and file parts retain their explicit provider type in OpenAI replay, including hosted file references, extensionless image URLs, and files whose names have image extensions.

The ordinary AG-UI TOOL_CALL_RESULT emitter currently reads only result, not items. It emits the text for mixed text/attachment outputs and empty event content for image/file-only outputs. Preserving rich parts in framework content and OpenAI replay does not provide frontend attachment display; that is a separate transport/frontend capability, outside this parser's scope.

Environment variables

OpenAI

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

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:

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 and the deployment configured on an injected client.

When model= is omitted and an AsyncAzureOpenAI client is injected, that client's configured deployment is used instead of the AZURE_OPENAI_* model variables. A plain AsyncOpenAI client has no Azure deployment, so the OpenAI model variables above still apply. The injected client stays caller-owned.

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")

Concurrent reuse

This contract applies to the Responses API OpenAIChatClient, not the OpenAIChatCompletionClient shown above. An OpenAIChatClient instance can be shared by concurrent asynchronous calls on the same event loop. Streaming, non-streaming, and mixed calls are supported. Keep mutable run state isolated by creating a separate Agent and AgentSession for each concurrent run and by passing separate messages and options.

This guarantee does not extend to user-supplied middleware, tools, or callbacks unless those implementations are also safe for concurrent use. Do not share one client across OS threads or event loops, and do not mutate its configuration while calls are active.