mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Giles Odigwe 570a4d54c2 Python: Support OpenAI and Gemini allowed_tools tool choice (#5322 )

* Support OpenAI allowed_tools in ToolMode (#5309)

Add allowed_tools field to ToolMode TypedDict, enabling users to restrict
which tools the model may call via the OpenAI allowed_tools tool_choice
type. This preserves prompt caching by keeping all tools in the tools list
while limiting which ones the model can invoke.

- Add allowed_tools: list[str] to ToolMode TypedDict
- Add validation in validate_tool_mode() (only valid when mode == "auto")
- Convert to OpenAI API format in _prepare_options()
- Add tests for validation and API payload generation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Python: Support OpenAI `allowed_tools` tool choice in Python SDK

Fixes #5309

* Fix #5309: Validate allowed_tools shape and add Chat Completions client support

- validate_tool_mode now checks allowed_tools is a non-string sequence of
  strings and normalizes to list[str], raising ContentError for invalid types
- Add missing allowed_tools branch in _chat_completion_client._prepare_options
  so allowed_tools is emitted as the OpenAI allowed_tools wire format instead
  of being silently dropped
- Add tests for invalid allowed_tools types (string, int, mixed), empty list,
  tuple normalization, and Chat Completions client payload generation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: support allowed_tools with mode 'required' in addition to 'auto'

OpenAI's allowed_tools tool_choice type supports both mode 'auto' and
'required'. Update validation, client conversion, and tests to allow
both modes instead of restricting to 'auto' only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: use Gemini VALIDATED mode for allowed_tools, warn in unsupported providers

- Use FunctionCallingConfigMode.VALIDATED instead of ANY when allowed_tools
  is set with auto mode in Gemini, preserving optional tool-call semantics.
- Handle allowed_tools in required mode with required_function_name precedence.
- Fix allowed_names guard to use identity check (is not None) so empty lists
  are preserved.
- Bump google-genai minimum to >=1.32.0 (VALIDATED added in that version).
- Add warnings in Anthropic and Bedrock when allowed_tools is set but not
  supported.
- Add Gemini unit tests for allowed_tools with auto, required, empty list,
  and required_function_name precedence scenarios.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: Chat Completions API does not support allowed_tools, add integration tests

- Chat Completions API (_chat_completion_client.py) now warns and falls
  back to plain mode when allowed_tools is set, since the /chat/completions
  endpoint does not support the allowed_tools type.
- Add allowed_tools integration test param to both OpenAIChatClient
  (Responses API) and OpenAIChatCompletionClient parametrized option tests.
- Update Chat Completions unit tests to reflect the warn-and-fallback
  behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: remove unused walrus operator variable in chat completion client

Remove assigned-but-never-used variable 'allowed' flagged by ruff F841.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

570a4d54c2 · 2026-04-29 17:43:47 +00:00

History

agent_framework_openai

Python: Support OpenAI and Gemini allowed_tools tool choice (#5322 )

2026-04-29 17:43:47 +00:00

tests

Python: Support OpenAI and Gemini allowed_tools tool choice (#5322 )

2026-04-29 17:43:47 +00:00

AGENTS.md

Python: [BREAKING] Remove deprecated Python OpenAI/Azure AI surfaces (#4990 )

2026-03-31 20:36:21 +00:00

LICENSE

Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818 )

2026-03-25 09:56:29 +00:00

pyproject.toml

Python: bump package versions for 1.2.2 release (#5561 )

2026-04-29 17:51:48 +09:00

README.md

Python: [BREAKING] update to v1.0.0 (#5062 )

2026-04-02 15:26:30 +00:00

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