Python: Fix web_search_options sent to Azure OpenAI Chat Completions API (issue #3629)

[Oxygen56]

Summary

Azure OpenAI Chat Completions API does not support the web_search_options parameter. Sending it results in a 400 error:

{'error': {'message': "Unknown parameter: 'web_search_options'."}}

This PR fixes the issue by storing the Azure client flag and skipping web search tools when configured with Azure OpenAI.

Changes

1. Store _use_azure_client flag in RawOpenAIChatCompletionClient.__init__ so downstream methods can check whether the client is Azure-based
2. Skip web search for Azure in _prepare_tools_for_openai: when the client is Azure-based, web search tools are silently excluded with a warning guiding users to use OpenAIChatClient (Responses API) instead

Before

client = OpenAIChatCompletionClient(azure_endpoint="...", api_key="...", model="gpt-4o-mini")
tool = OpenAIChatCompletionClient.get_web_search_tool()
agent = Agent(client=client, tools=[tool])
await agent.run("Weather?")
# -> ServiceResponseException: Unknown parameter: 'web_search_options'

After

client = OpenAIChatCompletionClient(azure_endpoint="...", api_key="...", model="gpt-4o-mini")
tool = OpenAIChatCompletionClient.get_web_search_tool()
agent = Agent(client=client, tools=[tool])
await agent.run("Weather?")
# -> Warning logged: Web search not supported by Azure OpenAI Chat Completions
# -> Agent runs without web search, no error

Alternatives

For web search on Azure, use the Responses API via OpenAIChatClient:

from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(azure_endpoint="...", credential=AzureCliCredential())

Fixes #3629

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds Azure-specific handling for web search tools in the Chat Completions client, preventing unsupported parameters from being sent when using an Azure endpoint.

Changes:

• Persist use_azure_client configuration on the instance for later branching.
• Update tool preparation to ignore web_search tools when configured for Azure, and log a warning.
• Add a docstring note describing Azure Chat Completions limitations around web search.

[Oxygen56]

@microsoft-github-policy-service agree

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/openai/agent_framework_openai
_chat_completion_client.py	366	25	93%	432, 528–529, 533, 778–785, 787–790, 878, 880, 897, 918, 946, 959, 983, 1003, 1318
TOTAL	37396	4350	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7453	34 💤	0 ❌	0 🔥	1m 54s ⏱️

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Oxygen56]

Addressed Copilot review feedback:

1. ✅ Centralized error message — extracted _AZURE_WEB_SEARCH_UNSUPPORTED_MSG as a module-level constant in _chat_completion_client.py
2. ✅ Test uses shared constant — test_openai_chat_completion_client.py now imports and matches against the same constant
3. ✅ Docstring — already correct (says "raises ValueError" which matches the current implementation)
4. ✅ Commit author fixed to Oxygen56 <1391083091@qq.com>

Ready for re-review.

[Oxygen56]

Thanks for the review approval @eavanvalkenburg!

It looks like the CI workflows need manual approval to run on this fork PR — all 6 critical checks (Python tests, code quality, merge gatekeeper, etc.) are stuck in action_required. Could you approve the workflow runs when you get a chance?

The CI run page should be here: https://github.com/microsoft/agent-framework/actions?query=branch%3Afix%2Fazure-web-search-options