Evan Mattson
f3db60fa65
* Python: Support GPT-5 verbosity option and restore Foundry agent_reference Adds verbosity as a typed Literal["low","medium","high"] field on OpenAIChatOptions (Responses API) and OpenAIChatCompletionOptions (Chat Completions API), set in the same way as the existing reasoning options. For the Responses API, top-level verbosity is translated to the nested text.verbosity shape the OpenAI service expects. The same field flows through to FoundryChatClient via the existing FoundryChatOptions alias. Also fixes #5582: PR #5447 removed the agent_reference injection from RawFoundryAgentChatClient._prepare_options, so first-turn calls against a Foundry Prompt Agent went out without model and without agent_reference and were rejected by the Responses API with "Missing required parameter: 'model'". Restores the injection on the non-preview path (allow_preview=False) and adds a guard test that asserts the preview path does not inject agent_reference, since the preview SDK injects it via project_client.get_openai_client(agent_name=...). Closes #5516 Closes #5582 * Python: Address Copilot review on PR #5619 - Foundry verbosity sample docstring: replace the misleading "set deployment name on model=" instruction with the actual env-var pattern the sample relies on (FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL). - _build_agent_reference docstring: clarify the helper is used for both Prompt Agents and HostedAgents on the non-preview path. - Add a Responses API test that locks in the documented precedence rule: when both top-level verbosity and text["verbosity"] are supplied, the top-level value wins. * Python: Drop redundant Foundry verbosity sample and list OpenAI sample in README - Remove samples/02-agents/providers/foundry/foundry_chat_client_verbosity.py per review feedback. The verbosity functionality is identical across the OpenAI and Foundry clients (FoundryChatOptions is an alias of OpenAIChatOptions), so a single sample on the OpenAI side is sufficient. - Add the new client_verbosity.py entry to the OpenAI samples README.
agent-framework-openai
OpenAI integration for Microsoft Agent Framework.
This package provides:
OpenAIChatClientfor the OpenAI Responses APIOpenAIChatCompletionClientfor the Chat Completions APIOpenAIEmbeddingClientfor 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.
OpenAIChatClientuses the Responses API and is the preferred general-purpose chat client.OpenAIChatCompletionClientuses 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_MODELOpenAIChatCompletionClient:OPENAI_CHAT_COMPLETION_MODEL->OPENAI_MODELOpenAIEmbeddingClient: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_MODELOpenAIChatCompletionClient:AZURE_OPENAI_CHAT_COMPLETION_MODEL->AZURE_OPENAI_MODELOpenAIEmbeddingClient: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")