Python: Fix OAuth consent event forwarding in as_tool()

[coding-shalabh]

Summary

Fixes #4499

Adds exception-based OAuth consent event forwarding to enable proper OAuth flows when using agents as tools.

Changes Made

New Exception Class

Added OAuthConsentRequiredException to exceptions.py:114-131:

• Raised when a sub-agent tool requires OAuth consent
• Contains consent_url attribute for the OAuth consent URL
• Parent agents can catch this exception and forward consent requests to users

Modified as_tool() Method

Updated as_tool() in _agents.py:533-561:

• Non-streaming mode (line 536-542): Checks response contents for oauth_consent_request events
• Streaming mode (line 547-552): Checks each update's contents for oauth_consent_request events
• When detected, raises OAuthConsentRequiredException with the consent URL

Implementation Details

This implements the exception-based approach (Option A) discussed in issue #4499.

Detection logic:

for content in response.contents:  # or update.contents
    if content.type == 'oauth_consent_request':
        consent_url = content.get('consent_link') or content.get('url') or ''
        raise OAuthConsentRequiredException(consent_url)

Parent agent handling:

try:
    result = await research_tool(**kwargs)
except OAuthConsentRequiredException as e:
    # Forward consent request to user
    consent_url = e.consent_url

Why This Change?

Currently, when using as_tool() to wrap an agent, OAuth consent request events are silently discarded because the method only returns .text. This makes proper OAuth flows impossible in multi-agent scenarios.

This fix enables:

• Multi-agent OAuth workflows
• Proper consent request propagation
• Parent agents to handle OAuth flows correctly

Testing Recommendations

1. Create a sub-agent that produces oauth_consent_request events
2. Wrap it using as_tool()
3. Use it as a tool in a parent agent
4. Verify OAuthConsentRequiredException is raised with correct consent_url
5. Test both streaming and non-streaming modes

Related Issues

Closes #4499

---

[coding-shalabh]

@microsoft-github-policy-service agree