Python: Add function_choice_behavior support to Azure AI and OpenAI Assistant agents (#14057)

### Description

Adds `function_choice_behavior` parameter to Azure AI and OpenAI
Assistant agents, aligning them with the existing Responses agent and
Chat Completion agent APIs.

### Changes

- Add `function_choice_behavior` parameter to
`invoke`/`invoke_stream`/`get_response` on both `AzureAIAgent` and
`OpenAIAssistantAgent` public APIs
- Add `function_choice_behavior` parameter to internal
`AzureAIAgentThreadActions` and `AssistantThreadActions`
`invoke`/`invoke_stream` methods
- Support `tools` parameter override for SDK-level tools
(CodeInterpreter, FileSearch, etc.)
- Filter kernel functions based on `FunctionChoiceBehavior`
configuration
- Validate that only `Auto` type with auto-invoke enabled is supported
- Fix `_get_tools` in OpenAI path to use passed `kernel` parameter
instead of `agent.kernel`
- Add comprehensive unit tests for both thread actions and public agent
APIs

---------

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

Author: SergeyMenshykh

python/semantic_kernel/agents/azure_ai/agent_thread_actions.py

@@ -68,6 +68,8 @@
 from semantic_kernel.agents.open_ai.function_action_result import FunctionActionResult
 from semantic_kernel.agents.open_ai.run_polling_options import RunPollingOptions
 from semantic_kernel.connectors.ai.function_calling_utils import kernel_function_metadata_to_function_call_format
+from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
+from semantic_kernel.connectors.ai.function_choice_type import FunctionChoiceType
 from semantic_kernel.contents.chat_message_content import ChatMessageContent
 from semantic_kernel.contents.function_call_content import FunctionCallContent
 from semantic_kernel.contents.utils.author_role import AuthorRole
@@ -124,6 +126,7 @@ async def invoke(
         parallel_tool_calls: bool | None = None,
         metadata: dict[str, str] | None = None,
         polling_options: RunPollingOptions | None = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
         **kwargs: Any,
     ) -> AsyncIterable[tuple[bool, "ChatMessageContent"]]:
         """Invoke the message in the thread.
@@ -139,7 +142,9 @@ async def invoke(
             additional_messages: The additional messages to add to the thread. Only supports messages with
                 role = User or Assistant.
                 https://platform.openai.com/docs/api-reference/runs/createRun#runs-createrun-additional_messages
-            tools: The tools.
+            tools: The SDK-level tools (e.g. CodeInterpreter, FileSearch, AzureAISearch). When provided,
+                overrides the tools from the agent definition. Does not affect kernel function availability;
+                use function_choice_behavior for that.
             temperature: The temperature.
             top_p: The top p.
             max_prompt_tokens: The max prompt tokens.
@@ -150,6 +155,9 @@ async def invoke(
             metadata: The metadata.
             polling_options: The polling options defined at the run-level. These will override the agent-level
                 polling options.
+            function_choice_behavior: Controls which kernel functions are allowed to execute during this run.
+                Use FunctionChoiceBehavior.Auto(filters={"included_functions": [...]}) to restrict to specific
+                functions. Only Auto is supported; other types will raise an error.
             kwargs: Additional keyword arguments.
 
         Returns:
@@ -158,7 +166,11 @@ async def invoke(
         arguments = KernelArguments() if arguments is None else KernelArguments(**arguments, **kwargs)
         kernel = kernel or agent.kernel
 
-        tools = cls._get_tools(agent=agent, kernel=kernel)  # type: ignore
+        cls._validate_function_choice_behavior(function_choice_behavior)
+
+        tools = cls._get_tools(
+            agent=agent, kernel=kernel, tools_override=tools, function_choice_behavior=function_choice_behavior
+        )  # type: ignore
 
         base_instructions = await agent.format_instructions(kernel=kernel, arguments=arguments)
 
@@ -232,7 +244,11 @@ async def invoke(
 
                         chat_history = ChatHistory() if kwargs.get("chat_history") is None else kwargs["chat_history"]
                         _ = await cls._invoke_function_calls(
-                            kernel=kernel, fccs=fccs, chat_history=chat_history, arguments=arguments
+                            kernel=kernel,
+                            fccs=fccs,
+                            chat_history=chat_history,
+                            arguments=arguments,
+                            function_choice_behavior=function_choice_behavior,
                         )
 
                         tool_outputs = cls._format_tool_outputs(fccs, chat_history)
@@ -467,6 +483,7 @@ async def invoke_stream(
         temperature: float | None = None,
         top_p: float | None = None,
         truncation_strategy: TruncationObject | None = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
         **kwargs: Any,
     ) -> AsyncIterable["StreamingChatMessageContent"]:
         """Invoke the agent stream and yield ChatMessageContent continuously.
@@ -489,10 +506,15 @@ async def invoke_stream(
                 formed from the streamed chunks.
             parallel_tool_calls: Whether to configure parallel tool calls.
             response_format: The response format.
-            tools: The tools.
+            tools: The SDK-level tools (e.g. CodeInterpreter, FileSearch, AzureAISearch). When provided,
+                overrides the tools from the agent definition. Does not affect kernel function availability;
+                use function_choice_behavior for that.
             temperature: The temperature.
             top_p: The top p.
             truncation_strategy: The truncation strategy.
+            function_choice_behavior: Controls which kernel functions are allowed to execute during this run.
+                Use FunctionChoiceBehavior.Auto(filters={"included_functions": [...]}) to restrict to specific
+                functions. Only Auto is supported; other types will raise an error.
             kwargs: Additional keyword arguments.
 
         Returns:
@@ -502,7 +524,11 @@ async def invoke_stream(
         kernel = kernel or agent.kernel
         arguments = agent._merge_arguments(arguments)
 
-        tools = cls._get_tools(agent=agent, kernel=kernel)  # type: ignore
+        cls._validate_function_choice_behavior(function_choice_behavior)
+
+        tools = cls._get_tools(
+            agent=agent, kernel=kernel, tools_override=tools, function_choice_behavior=function_choice_behavior
+        )  # type: ignore
 
         base_instructions = await agent.format_instructions(kernel=kernel, arguments=arguments)
 
@@ -549,6 +575,7 @@ async def invoke_stream(
             arguments=arguments,
             function_steps=function_steps,
             active_messages=active_messages,
+            function_choice_behavior=function_choice_behavior,
         ):
             if content:
                 yield content
@@ -564,6 +591,7 @@ async def _process_stream_events(
         function_steps: dict[str, FunctionCallContent],
         active_messages: dict[str, RunStep],
         output_messages: "list[ChatMessageContent] | None" = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
     ) -> AsyncIterable["StreamingChatMessageContent"]:
         """Process events from the main stream and delegate tool output handling as needed."""
         thread_msg_id = None
@@ -671,6 +699,7 @@ async def _process_stream_events(
                             run=run,
                             function_steps=function_steps,
                             arguments=arguments,
+                            function_choice_behavior=function_choice_behavior,
                         )
                         if action_result is None:
                             raise RuntimeError(
@@ -959,12 +988,74 @@ def _deduplicate_tools(existing_tools: list[dict], new_tools: list[dict]) -> lis
         }
         return [tool for tool in new_tools if tool.get("function", {}).get("name") not in existing_names]
 
+    @staticmethod
+    def _validate_function_choice_behavior(
+        function_choice_behavior: FunctionChoiceBehavior | None,
+    ) -> None:
+        """Validate the function choice behavior is compatible with agent invocations."""
+        if function_choice_behavior is None:
+            return
+        if function_choice_behavior.type_ != FunctionChoiceType.AUTO:
+            raise AgentInvokeException(
+                f"FunctionChoiceBehavior with type '{function_choice_behavior.type_}' is not supported for agent "
+                "invocations. Use FunctionChoiceBehavior.Auto(filters=...) to control which kernel functions "
+                "are available."
+            )
+        if not function_choice_behavior.auto_invoke_kernel_functions:
+            raise AgentInvokeException(
+                "FunctionChoiceBehavior.Auto(auto_invoke=False) is not supported for agent invocations. "
+                "The agent run loop manages tool invocation; disabling auto_invoke is not compatible."
+            )
+        valid_filter_keys: set[str] = {
+            "excluded_plugins",
+            "included_plugins",
+            "excluded_functions",
+            "included_functions",
+        }
+        if function_choice_behavior.filters is not None:
+            if not function_choice_behavior.filters:
+                raise AgentInvokeException(
+                    "FunctionChoiceBehavior filters must not be empty. Provide at least one filter key "
+                    f"from {sorted(valid_filter_keys)}, or omit filters entirely to include all "
+                    "kernel functions."
+                )
+            unknown_keys = {str(k) for k in function_choice_behavior.filters} - valid_filter_keys
+            if unknown_keys:
+                raise AgentInvokeException(
+                    f"Unknown filter key(s): {sorted(unknown_keys)}. "
+                    f"Valid filter keys are: {sorted(valid_filter_keys)}."
+                )
+
     @classmethod
-    def _get_tools(cls: type[_T], agent: "AzureAIAgent", kernel: "Kernel") -> list[dict[str, Any] | ToolDefinition]:
-        """Get the tools for the agent."""
-        tools: list[Any] = list(agent.definition.tools)
-        funcs = kernel.get_full_list_of_function_metadata()
-        cls._validate_function_tools_registered(tools, funcs)
+    def _get_tools(
+        cls: type[_T],
+        agent: "AzureAIAgent",
+        kernel: "Kernel",
+        tools_override: list[ToolDefinition] | None = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
+    ) -> list[dict[str, Any] | ToolDefinition]:
+        """Get the tools for the agent.
+
+        Args:
+            agent: The agent instance.
+            kernel: The kernel to use for function metadata.
+            tools_override: When provided, overrides agent.definition.tools (SDK-level tools only).
+            function_choice_behavior: When provided, filters which kernel functions are included.
+        """
+        tools: list[Any] = list(tools_override) if tools_override is not None else list(agent.definition.tools)
+
+        # Always validate against the full kernel function list to catch truly
+        # unregistered functions, regardless of FCB filtering.
+        all_funcs = kernel.get_full_list_of_function_metadata()
+        cls._validate_function_tools_registered(tools, all_funcs)
+
+        # Determine which kernel functions to advertise based on function_choice_behavior
+        if function_choice_behavior is not None and not function_choice_behavior.enable_kernel_functions:
+            funcs: list[KernelFunctionMetadata] = []
+        elif function_choice_behavior is not None and function_choice_behavior.filters:
+            funcs = kernel.get_list_of_function_metadata(function_choice_behavior.filters)
+        else:
+            funcs = all_funcs
         dict_defs = [kernel_function_metadata_to_function_call_format(f) for f in funcs]
         deduped_defs = cls._deduplicate_tools(tools, dict_defs)
         tools.extend(deduped_defs)
@@ -1071,6 +1162,7 @@ async def _invoke_function_calls(
         fccs: list["FunctionCallContent"],
         chat_history: "ChatHistory",
         arguments: KernelArguments,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
     ) -> list["AutoFunctionInvocationContext | None"]:
         """Invoke the function calls."""
         return await asyncio.gather(
@@ -1079,6 +1171,7 @@ async def _invoke_function_calls(
                     function_call=function_call,
                     chat_history=chat_history,
                     arguments=arguments,
+                    function_behavior=function_choice_behavior,
                 )
                 for function_call in fccs
             ],
@@ -1111,6 +1204,7 @@ async def _handle_streaming_requires_action(
         run: ThreadRun,
         function_steps: dict[str, "FunctionCallContent"],
         arguments: KernelArguments,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
         **kwargs: Any,
     ) -> FunctionActionResult | None:
         """Handle the requires action event for a streaming run."""
@@ -1121,7 +1215,11 @@ async def _handle_streaming_requires_action(
 
             chat_history = ChatHistory() if kwargs.get("chat_history") is None else kwargs["chat_history"]
             results = await cls._invoke_function_calls(
-                kernel=kernel, fccs=fccs, chat_history=chat_history, arguments=arguments
+                kernel=kernel,
+                fccs=fccs,
+                chat_history=chat_history,
+                arguments=arguments,
+                function_choice_behavior=function_choice_behavior,
             )
 
             function_result_streaming_content = merge_streaming_function_results(

python/semantic_kernel/agents/azure_ai/azure_ai_agent.py

@@ -41,6 +41,7 @@
 from semantic_kernel.agents.channels.agent_channel import AgentChannel
 from semantic_kernel.agents.open_ai.run_polling_options import RunPollingOptions
 from semantic_kernel.connectors.ai.function_calling_utils import kernel_function_metadata_to_function_call_format
+from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
 from semantic_kernel.contents.chat_message_content import ChatMessageContent
 from semantic_kernel.contents.utils.author_role import AuthorRole
 from semantic_kernel.exceptions.agent_exceptions import (
@@ -647,6 +648,7 @@ async def get_response(
         parallel_tool_calls: bool | None = None,
         metadata: dict[str, str] | None = None,
         polling_options: RunPollingOptions | None = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
         **kwargs: Any,
     ) -> AgentResponseItem[ChatMessageContent]:
         """Get a response from the agent on a thread.
@@ -671,6 +673,8 @@ async def get_response(
             parallel_tool_calls: Whether to allow parallel tool calls.
             metadata: Metadata for the agent.
             polling_options: The polling options for the agent.
+            function_choice_behavior: The function choice behavior to control which kernel
+                functions are available. Only Auto is supported; other types will raise an error.
             **kwargs: Additional keyword arguments.
 
         Returns:
@@ -716,6 +720,7 @@ async def get_response(
             thread_id=thread.id,
             kernel=kernel,
             arguments=arguments,
+            function_choice_behavior=function_choice_behavior,
             **run_level_params,  # type: ignore
         ):
             if is_visible and response.metadata.get("code") is not True:
@@ -752,6 +757,7 @@ async def invoke(
         parallel_tool_calls: bool | None = None,
         metadata: dict[str, str] | None = None,
         polling_options: RunPollingOptions | None = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
         **kwargs: Any,
     ) -> AsyncIterable[AgentResponseItem[ChatMessageContent]]:
         """Invoke the agent on the specified thread.
@@ -777,6 +783,8 @@ async def invoke(
             parallel_tool_calls: Whether to allow parallel tool calls.
             polling_options: The polling options for the agent.
             metadata: Metadata for the agent.
+            function_choice_behavior: The function choice behavior to control which kernel
+                functions are available. Only Auto is supported; other types will raise an error.
             **kwargs: Additional keyword arguments.
 
         Yields:
@@ -821,6 +829,7 @@ async def invoke(
             thread_id=thread.id,
             kernel=kernel,
             arguments=arguments,
+            function_choice_behavior=function_choice_behavior,
             **run_level_params,  # type: ignore
         ):
             message.metadata["thread_id"] = thread.id
@@ -856,6 +865,7 @@ async def invoke_stream(
         response_format: AgentsApiResponseFormatOption | None = None,
         parallel_tool_calls: bool | None = None,
         metadata: dict[str, str] | None = None,
+        function_choice_behavior: FunctionChoiceBehavior | None = None,
         **kwargs: Any,
     ) -> AsyncIterable[AgentResponseItem["StreamingChatMessageContent"]]:
         """Invoke the agent on the specified thread with a stream of messages.
@@ -881,6 +891,8 @@ async def invoke_stream(
             response_format: Response format for the agent.
             parallel_tool_calls: Whether to allow parallel tool calls.
             metadata: Metadata for the agent.
+            function_choice_behavior: The function choice behavior to control which kernel
+                functions are available. Only Auto is supported; other types will raise an error.
             **kwargs: Additional keyword arguments.
 
         Yields:
@@ -928,6 +940,7 @@ async def invoke_stream(
             output_messages=collected_messages,
             kernel=kernel,
             arguments=arguments,
+            function_choice_behavior=function_choice_behavior,
             **run_level_params,  # type: ignore
         ):
             # Before yielding the current streamed message, emit any new full messages first