resolved comments from Jarno

Author: howieleung

sdk/ai/azure-ai-agents/azure/ai/agents/models/_patch.py

@@ -1704,22 +1704,15 @@ def execute_tool_calls(self, tool_calls: List[Any]) -> Any:
         """
         return self._execute_tool_calls(tool_calls)
 
-    def _execute_tool_calls(self, tool_calls: List[Any], run: Optional[ThreadRun] = None, required_action_handler: Optional['CreateAndProcessRequiredActionHandler'] = None) -> Any:
-        """
-        Execute a tool of the specified type with the provided tool calls.
-
-        :param List[Any] tool_calls: A list of tool calls to execute.
-        :return: The output of the tool operations.
-        :rtype: Any
-        """
+    def _execute_tool_calls(self, tool_calls: List[Any], run: Optional[ThreadRun] = None, run_handler: Optional['RunHandler'] = None) -> Any:
         tool_outputs = []
 
         for tool_call in tool_calls:
             if tool_call.type == "function":
                 output: Optional[Any] = None
 
-                if required_action_handler and run:
-                    output = required_action_handler.submit_function_call_output(run, tool_call, tool_call.function)
+                if run_handler and run:
+                    output = run_handler.submit_function_call_output(run, tool_call, tool_call.function)
                 try:
                     if not output:
                         tool = self.get_tool(FunctionTool)
@@ -1782,7 +1775,7 @@ async def execute_tool_calls(self, tool_calls: List[Any]) -> Any:
 EventFunctionReturnT = TypeVar("EventFunctionReturnT")
 T = TypeVar("T")
 BaseAsyncAgentEventHandlerT = TypeVar("BaseAsyncAgentEventHandlerT", bound="BaseAsyncAgentEventHandler")
-BaseAgentEventHandlerT = TypeVar("BaseAgentEventHandlerT", bound="BaseAgentEventHandler")
+# BaseAgentEventHandlerT is defined after BaseAgentEventHandler class to avoid forward reference during parsing.
 
 async def async_chain(*iterators: AsyncIterator[T]) -> AsyncIterator[T]:
     for iterator in iterators:
@@ -1856,10 +1849,26 @@ async def until_done(self) -> None:
             pass
 
 
-class CreateAndProcessRequiredActionHandler:
+class RunHandler:
+    """Helper that drives a run to completion for the "create and process" pattern.
+
+    Extension Points:
+        * ``submit_function_call_output`` -- override to customize how function tool results are produced.
+        * ``submit_mcp_tool_approval`` -- override to implement an approval workflow (UI prompt, policy, etc.).
+    """
+
+    def _start(self, runs_operations: "RunsOperations", run: ThreadRun, polling_interval: int) -> ThreadRun:
+        """Poll and process a run until it reaches a terminal state or is cancelled.
 
-    def _start(self,  runs_operations: "RunsOperations", run: ThreadRun, polling_interval: int) -> ThreadRun:
-        # Monitor and process the run status
+        :param runs_operations: Operations client used to retrieve, cancel, and submit tool outputs/approvals.
+        :type runs_operations: RunsOperations
+        :param run: The initial run returned from create/process call.
+        :type run: ThreadRun
+        :param polling_interval: Delay (in seconds) between polling attempts.
+        :type polling_interval: int
+        :return: The final terminal ``ThreadRun`` object (completed, failed, cancelled, or expired).
+        :rtype: ThreadRun
+        """
         current_retry = 0
         while run.status in [
             RunStatus.QUEUED,
@@ -1882,7 +1891,7 @@ def _start(self,  runs_operations: "RunsOperations", run: ThreadRun, polling_int
                 if any(tool_call.type == "function" for tool_call in tool_calls):
                     toolset = ToolSet()
                     toolset.add(runs_operations._function_tool)
-                    tool_outputs = toolset._execute_tool_calls(tool_calls, run=run, required_action_handler=self)
+                    tool_outputs = toolset._execute_tool_calls(tool_calls, run=run, run_handler=self)
 
                     if _has_errors_in_toolcalls_output(tool_outputs):
                         if current_retry >= runs_operations._function_tool_max_retry:  # pylint:disable=no-else-return
@@ -1896,7 +1905,9 @@ def _start(self,  runs_operations: "RunsOperations", run: ThreadRun, polling_int
 
                     logger.debug("Tool outputs: %s", tool_outputs)
                     if tool_outputs:
-                        run2 = runs_operations.submit_tool_outputs(thread_id=run.thread_id, run_id=run.id, tool_outputs=tool_outputs)
+                        run2 = runs_operations.submit_tool_outputs(
+                            thread_id=run.thread_id, run_id=run.id, tool_outputs=tool_outputs
+                        )
                         logger.debug("Tool outputs submitted to run: %s", run2.id)
             elif isinstance(run.required_action, SubmitToolApprovalAction):
                 tool_calls = run.required_action.submit_tool_approval.tool_calls
@@ -1909,9 +1920,11 @@ def _start(self,  runs_operations: "RunsOperations", run: ThreadRun, polling_int
                 for tool_call in tool_calls:
                     if isinstance(tool_call, RequiredMcpToolCall):
                         logger.info(f"Approving tool call: {tool_call}")
-                        tool_approval = self.submit_tool_approval(run, tool_call)
+                        tool_approval = self.submit_mcp_tool_approval(run, tool_call)
                         if not tool_approval:
-                            logger.debug("submit_tool_approval in event handler returned None.  Please override this function and return a valid ToolApproval.")
+                            logger.debug(
+                                "submit_tool_approval in event handler returned None.  Please override this function and return a valid ToolApproval."
+                            )
                             run = runs_operations.cancel(thread_id=run.thread_id, run_id=run.id)
 
                         tool_approvals.append(tool_approval)
@@ -1923,11 +1936,51 @@ def _start(self,  runs_operations: "RunsOperations", run: ThreadRun, polling_int
 
         return run
 
-    def submit_function_call_output(self, run: ThreadRun, tool_call: RequiredFunctionToolCall, tool_call_details: RequiredFunctionToolCallDetails) -> Optional[str]:
+    def submit_function_call_output(
+        self,
+        run: ThreadRun,
+        tool_call: RequiredFunctionToolCall,
+        tool_call_details: RequiredFunctionToolCallDetails,
+        **kwargs,
+    ) -> Optional[Any]:
+        """Produce (or override) the output for a required function tool call.
+
+        Override this to inject custom execution logic, caching, validation, or transformation.
+        Return ``None`` to fall back to the default execution path handled in ``_start``.
+
+        :param run: Current run requiring the function output.
+        :type run: ThreadRun
+        :param tool_call: The tool call metadata referencing the function tool.
+        :type tool_call: RequiredFunctionToolCall
+        :param tool_call_details: Function arguments/details object.
+        :type tool_call_details: RequiredFunctionToolCallDetails
+        :keyword kwargs: Additional keyword arguments for extensibility.
+        :return: Stringified result to send back to the service, or ``None`` to delegate to auto function calling.
+        :rtype: Optional[Any]
+        """
         return None
 
-    def submit_tool_approval(self, run: ThreadRun, tool_call: RequiredMcpToolCall) -> Optional[ToolApproval]:
-        return None
+    def submit_mcp_tool_approval(
+        self,
+        run: ThreadRun,
+        tool_call: RequiredMcpToolCall,
+        **kwargs,
+    ) -> Optional[ToolApproval]:
+            # NOTE: Implementation intentionally returns None; override in subclasses for real approval logic.
+            """Return a ``ToolApproval`` for an MCP tool call or ``None`` to indicate rejection/cancellation.
+
+            Override this to implement approval policies (interactive prompt, RBAC, heuristic checks, etc.).
+            Returning ``None`` triggers cancellation logic in ``_start``.
+
+            :param run: Current run containing the MCP approval request.
+            :type run: ThreadRun
+            :param tool_call: The MCP tool call requiring approval.
+            :type tool_call: RequiredMcpToolCall
+            :keyword kwargs: Additional keyword arguments for extensibility.
+            :return: A populated ``ToolApproval`` instance on approval, or ``None`` to decline.
+            :rtype: Optional[ToolApproval]
+            """
+            return None
 
 
 
@@ -1991,6 +2044,9 @@ def until_done(self) -> None:
         except StopIteration:
             pass
 
+# Now that BaseAgentEventHandler is defined, we can bind the TypeVar.
+BaseAgentEventHandlerT = TypeVar("BaseAgentEventHandlerT", bound="BaseAgentEventHandler")
+
 
 class AsyncAgentEventHandler(BaseAsyncAgentEventHandler[Tuple[str, StreamEventData, Optional[EventFunctionReturnT]]]):
     def __init__(self) -> None:
@@ -2350,7 +2406,7 @@ def _is_valid_connection_id(connection_id: str) -> bool:
     "MessageTextFileCitationAnnotation",
     "MessageDeltaChunk",
     "MessageAttachment",
-    "CreateAndProcessRequiredActionHandler",
+    "RunHandler",
 ]  # Add all objects you want publicly available to users at this package level
 
 

sdk/ai/azure-ai-agents/azure/ai/agents/operations/_patch.py

@@ -441,7 +441,7 @@ def create_and_process(
         response_format: Optional["_types.AgentsResponseFormatOption"] = None,
         parallel_tool_calls: Optional[bool] = None,
         metadata: Optional[Dict[str, str]] = None,
-        required_action_handler: Optional[_models.CreateAndProcessRequiredActionHandler] = None,
+        run_handler: Optional[_models.RunHandler] = None,
         polling_interval: int = 1,
         **kwargs: Any,
     ) -> _models.ThreadRun:
@@ -553,10 +553,10 @@ def create_and_process(
         )
 
         # Monitor and process the run status
-        if not required_action_handler:
-            required_action_handler = _models.CreateAndProcessRequiredActionHandler(self)
+        if not run_handler:
+            run_handler = _models.RunHandler()
 
-        return required_action_handler._start(self, run, polling_interval)
+        return run_handler._start(self, run, polling_interval)
 
     @overload
     def stream(

sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions_in_create_and_process.py

@@ -22,16 +22,14 @@
        the "Models + endpoints" tab in your Azure AI Foundry project.
 """
 import os, time, sys
-from typing import Optional
+from typing import Any, Optional
 from azure.ai.projects import AIProjectClient
 from azure.identity import DefaultAzureCredential
 from azure.ai.agents.models import (
     FunctionTool,
     ListSortOrder,
     RequiredFunctionToolCall,
-    SubmitToolOutputsAction,
-    ToolOutput,
-    CreateAndProcessRequiredActionHandler,
+    RunHandler,
     ThreadRun,
     RequiredFunctionToolCall,
     RequiredFunctionToolCallDetails,
@@ -51,8 +49,9 @@
 # Initialize function tool with user functions
 functions = FunctionTool(functions=user_functions)
 
-class MyCreateAndProcessRequiredActionHandler(CreateAndProcessRequiredActionHandler):
-    def submit_function_call_output(self, run: ThreadRun, tool_call: RequiredFunctionToolCall, tool_call_details: RequiredFunctionToolCallDetails) -> Optional[str]:
+class MyRunHandler(RunHandler):
+    def submit_function_call_output(self, run: ThreadRun, tool_call: RequiredFunctionToolCall, tool_call_details: RequiredFunctionToolCallDetails) -> Optional[Any]:
+        print(f"Call function: {tool_call_details.name}")
         return functions.execute(tool_call)
 
 with project_client:
@@ -77,8 +76,8 @@ def submit_function_call_output(self, run: ThreadRun, tool_call: RequiredFunctio
     )
     print(f"Created message, ID: {message.id}")
 
-    required_action_handler = MyCreateAndProcessRequiredActionHandler()
-    run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id, required_action_handler=required_action_handler)
+    run_handler = MyRunHandler()
+    run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id, run_handler=run_handler)
 
     print(f"Run completed with status: {run.status}")
 

sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_mcp_in_create_and_process.py

@@ -26,7 +26,7 @@
     4) MCP_SERVER_LABEL - A label for your MCP server.
 """
 
-import os, time
+import os
 from typing import Optional
 from azure.ai.projects import AIProjectClient
 from azure.identity import DefaultAzureCredential
@@ -35,9 +35,8 @@
     McpTool,
     RequiredMcpToolCall,
     RunStepActivityDetails,
-    SubmitToolApprovalAction,
     ToolApproval,
-    CreateAndProcessRequiredActionHandler,
+    RunHandler,
     ThreadRun,
     ToolSet,
 )
@@ -66,15 +65,14 @@
 mcp_tool.allow_tool(search_api_code)
 print(f"Allowed tools: {mcp_tool.allowed_tools}")
 
-class MyCreateAndProcessRequiredActionHandler(CreateAndProcessRequiredActionHandler):
-    def submit_tool_approval(self, run: ThreadRun, tool_call: RequiredMcpToolCall) -> Optional[ToolApproval]:
+class MyRunHandler(RunHandler):
+    def submit_mcp_tool_approval(self, run: ThreadRun, tool_call: RequiredMcpToolCall, **kwargs) -> Optional[ToolApproval]:
         return ToolApproval(
             tool_call_id=tool_call.id,
             approve=True,
             headers=mcp_tool.headers,
         )
 
-
 # Create agent with MCP tool and process agent run
 with project_client:
     agents_client = project_client.agents
@@ -108,9 +106,9 @@ def submit_tool_approval(self, run: ThreadRun, tool_call: RequiredMcpToolCall) -
     # Create and process agent run in thread with MCP tools
     mcp_tool.update_headers("SuperSecret", "123456")
 
-    required_action_handler = MyCreateAndProcessRequiredActionHandler()
+    run_handler = MyRunHandler()
     # mcp_tool.set_approval_mode("never")  # Uncomment to disable approval requirement
-    run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id, required_action_handler=required_action_handler)
+    run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id, run_handler=run_handler)
     print(f"Created run, ID: {run.id}")
 
     print(f"Run completed with status: {run.status}")