Python: Fix as_tool() swallowing user_input_request events

[giles17]

Motivation and Context

Fixes #4499.

When a sub-agent wrapped with as_tool() emits user_input_request content (e.g. oauth_consent_request from PR #4197), the event is silently dropped. Both code paths in as_tool() collapse the response to .text, so the caller receives an empty string with no indication that user action is required.

Description

This fix propagates user_input_request Content items from sub-agents through the tool invocation pipeline to the parent agent's response, leveraging the existing user_input_request → AgentExecutor → ctx.request_info() mechanism.

New exception: UserInputRequiredException (exceptions.py)

• Extends ToolException; carries contents: list[Any] from the sub-agent
• Follows the same pattern as MiddlewareTermination — a structured exception that escapes the generic except Exception catch-all to alter control flow

as_tool() changes (_agents.py)

• Both streaming and non-streaming paths now check response.user_input_requests before returning .text
• Raises UserInputRequiredException if non-empty

Tool invocation pipeline changes (_tools.py)

• Two except UserInputRequiredException: raise guards in _auto_invoke_function (direct + middleware paths) prevent the generic except Exception from swallowing the signal
• invoke_with_termination_handling catches the exception and extracts the Content items
• _handle_function_call_results expanded to detect any Content with user_input_request=True, returning "action": "return" to stop the function invocation loop and surface the Content in the parent response

Event flow after fix:

Sub-agent → oauth_consent_request Content (user_input_request=True)
  → as_tool() raises UserInputRequiredException
  → _auto_invoke_function re-raises (not swallowed)
  → invoke_with_termination_handling catches, returns Content
  → _handle_function_call_results → "action": "return"
  → Content in parent response.messages
  → AgentExecutor → ctx.request_info() → pauses workflow

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	358	42	88%	444, 448, 510, 894, 930, 946, 1036–1040, 1106, 1231, 1247, 1249, 1262, 1268, 1304, 1306, 1315–1320, 1325, 1327, 1333–1334, 1341, 1343–1344, 1352–1353, 1356–1358, 1366–1367, 1369, 1374, 1376
_tools.py	800	83	89%	168–169, 328, 330, 348–350, 358, 376, 390, 397, 404, 420, 422, 429, 437, 469, 494, 498, 515–517, 564–566, 588, 644, 666, 733–739, 775, 786–797, 816–818, 822, 826, 840–842, 1181, 1201, 1279–1285, 1409, 1413, 1426, 1461, 1579, 1609, 1629, 1631, 1687, 1750, 1941–1942, 1993, 2062–2063, 2123, 2128, 2135
exceptions.py	67	0	100%
TOTAL	22713	2601	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4952	20 💤	0 ❌	0 🔥	1m 21s ⏱️

[Copilot]

Pull request overview

Fixes a gap in the Python tool-wrapping pipeline where Agent.as_tool() would collapse sub-agent output to .text and silently drop user_input_request content (e.g., oauth_consent_request), preventing parent agents/workflows from pausing for required user action.

Changes:

• Introduces UserInputRequiredException to carry sub-agent user_input_request contents through tool invocation.
• Updates Agent.as_tool() (streaming + non-streaming) to raise UserInputRequiredException when user_input_requests are present.
• Updates tool invocation handling to re-raise/catch UserInputRequiredException, surface the request Content in the parent response, and stop the function loop; adds tests for both as_tool and end-to-end invocation behavior.

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/exceptions.py	Adds UserInputRequiredException to represent “user action required” as a structured control-flow signal.
python/packages/core/agent_framework/_agents.py	Changes as_tool() to detect user_input_requests and raise instead of returning collapsed .text.
python/packages/core/agent_framework/_tools.py	Ensures the exception isn’t swallowed, converts it into surfaced Content, and stops tool-loop processing when user input is required.
python/packages/core/agent_framework/init.py	Exports the new exception from the package surface.
python/packages/core/tests/core/test_agents.py	Adds coverage for as_tool() raising in streaming/non-streaming and normal text behavior.
python/packages/core/tests/core/test_function_invocation_logic.py	Adds an end-to-end test ensuring user_input_request content reaches the parent response via tool invocation.

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

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

---

You can also share your feedback on Copilot code review. Take the survey.