Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Python: [Bug]: AZURE_OPENAI_API_VERSION is ignored by the OpenAI clients on the Azure route

Open
  • Is something wrong?
#9,097 1 comment 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@eavanvalkenburg is already working on this.

Since Oct 6, 2026.

  • #9098 by @Aditya-XR — open

Assessment

This issue has not been assessed yet.

Description

agents python reproduced
Description

OpenAIChatCompletionClient, OpenAIChatClient and OpenAIEmbeddingClient ignore AZURE_OPENAI_API_VERSION, whether it is set in the environment or in a .env file, and always send their built-in default api-version to Azure. Passing api_version= explicitly works.

The constructors document the opposite. For example, OpenAIChatCompletionClient says: "When not provided explicitly, the constructor reads AZURE_OPENAI_API_VERSION and then uses the Chat Completions default." OpenAIChatClient and OpenAIEmbeddingClient say the same, and the package README lists the variable as the Azure OpenAI API version.

Cause: load_openai_service_settings in agent_framework_openai/_shared.py passes the default into load_settings:

azure_settings = load_settings(
    AzureOpenAISettings,
    env_prefix="AZURE_OPENAI_",
    ...
    api_version=api_version or default_azure_api_version,
    ...
)

load_settings gives explicit keyword values priority over .env files and environment variables. Since api_version or default_azure_api_version is never None, the environment value can never win. This looks like a regression from #4925; before it, only the explicit api_version was passed and the default was applied afterwards.

The existing tests miss this because the Azure test fixture sets AZURE_OPENAI_API_VERSION to 2024-12-01-preview, which is also the Chat Completions default.

Expected: an explicit api_version wins, then AZURE_OPENAI_API_VERSION (environment or .env), then the client's default.

Code Sample
import os

for name in ("OPENAI_API_KEY", "AZURE_OPENAI_BASE_URL"):
    os.environ.pop(name, None)  # make sure the clients take the Azure route
os.environ.update({
    "AZURE_OPENAI_ENDPOINT": "https://my-resource.openai.azure.com",
    "AZURE_OPENAI_API_KEY": "test-key",
    "AZURE_OPENAI_MODEL": "my-deployment",
    "AZURE_OPENAI_API_VERSION": "2025-04-01-preview",
})

from agent_framework.openai import OpenAIChatClient, OpenAIChatCompletionClient, OpenAIEmbeddingClient

for client_type in (OpenAIChatCompletionClient, OpenAIChatClient, OpenAIEmbeddingClient):
    client = client_type()
    print(f"{client_type.__name__:<27} api_version={client.api_version}")

Output on main:

OpenAIChatCompletionClient  api_version=2024-12-01-preview
OpenAIChatClient            api_version=preview
OpenAIEmbeddingClient       api_version=2024-10-21

Every client should report 2025-04-01-preview. The same default also goes out as the api-version query parameter on the request, and setting the variable in a .env file passed via env_file_path behaves the same way.

Error Messages / Stack Traces

None. Requests silently use the default version.

Package Versions

agent-framework-openai: 1.15.0, agent-framework-core: 1.20.0 (source checkout of main at b9d24c8fb)

Python Version

Python 3.13

Additional Context
  • Reproduced on Windows and Linux.
  • One question for the fix: OpenAIChatClient (Responses) defaults to preview on the /openai/v1/ path. Once the variable is read again, a dated value set for Chat Completions would also be used by the Responses client. That matches its docstring and the behavior before #4925, but if the Responses client shouldn't pick up the shared variable, its docstring would need to change instead.
  • Fix: pass only the explicit api_version to load_settings, and apply the client default afterwards when nothing set a version. I'll open a PR with that and regression tests.
Dominant language
Python
Stars
13.9k
Forks
2.4k
Avg merge
1d 18h
Merged PRs (30d)
443

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/agent-framework

All issues in microsoft/agent-framework

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.