Python: Enhance Azure AI Search Citations with Complete URL Information

[giles17]

Motivation and Context

Enhances Azure AI Search tool integration to provide complete URL information in citation annotations, allowing customers to access actual document URLs instead of placeholder references like "doc_0".

Key Changes

• Direct URL in Citations: Modified _extract_url_citations to populate citation.url with real document URLs from Azure AI Search tool calls
• Tool Call Capture: Added _capture_azure_search_tool_calls to store Azure AI Search execution metadata
• URL Pattern Matching: Uses regex to extract document indices (doc_0, doc_1, etc.) from citation references

Addresses #1889

Description

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/azure-ai/agent_framework_azure_ai
_chat_client.py	411	79	80%	293, 521–522, 524, 527, 530–535, 537, 545, 557–559, 563, 566–567, 575–578, 588, 596–599, 601–602, 604–605, 612, 620–621, 629–630, 635–636, 640–647, 652–653, 661, 667, 675–677, 680, 702–703, 765, 780, 792–796, 823–825, 828–829, 887–892, 913, 954, 963, 989
TOTAL	14698	2121	85%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2035	129 💤	0 ❌	0 🔥	38.679s ⏱️

[Copilot]

Pull Request Overview

This PR enhances Azure AI Search tool integration to provide complete URL information in citation annotations, replacing placeholder references like "doc_0" with actual document URLs from Azure AI Search responses.

Key Changes:

• Enhanced citation mechanism to capture and include Azure AI Search tool call metadata in raw_representation
• Added infrastructure to capture tool execution data when Azure AI Search steps complete
• Updated sample to demonstrate extracting actual URLs from enhanced citation data

Reviewed Changes

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

File	Description
python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py	Implements core functionality: _capture_azure_search_tool_calls() captures tool execution data, _enhance_raw_representation_with_azure_search() enriches citations with tool call metadata, and _process_stream() coordinates the capture process
python/packages/azure-ai/tests/test_azure_ai_agent_client.py	Adds unit tests for the new citation enhancement methods and initializes _azure_search_tool_calls in test helper
python/samples/getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py	Demonstrates extracting actual URLs from enhanced citation data using the new azure_ai_search_tool_calls field in raw_representation
python/samples/getting_started/agents/azure_ai/azure_ai_with_file_search.py	Refactors API calls from client.project_client.agents to client.agents_client (unrelated to PR's main purpose)