1# pylint: disable=line-too-long,useless-suppression
2# ------------------------------------
3# Copyright (c) Microsoft Corporation.
4# Licensed under the MIT License.
5# ------------------------------------
6 
7"""
8DESCRIPTION:
9    This sample demonstrates how to use Agent operations with the Deep Research tool from
10    the Azure Agents service through the synchronous Python client. Deep Research issues
11    external Bing Search queries and invokes an LLM, so each run can take several minutes
12    to complete.
13 
14    For more information see the Deep Research Tool document: https://aka.ms/agents-deep-research
15 
16USAGE:
17    python sample_agents_deep_research.py
18 
19    Before running the sample:
20 
21    pip install azure-identity
22    pip install --pre azure-ai-projects
23 
24    Set this environment variables with your own values:
25    1) PROJECT_ENDPOINT - The Azure AI Project endpoint, as found in the Overview
26                          page of your Azure AI Foundry portal.
27    2) MODEL_DEPLOYMENT_NAME - The deployment name of the arbitration AI model, as found under the "Name" column in
28       the "Models + endpoints" tab in your Azure AI Foundry project.
29    3) DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME - The deployment name of the Deep Research AI model, as found under the "Name" column in
30       the "Models + endpoints" tab in your Azure AI Foundry project.
31    4) BING_RESOURCE_NAME - The resource name of the Bing connection, you can find it in the "Connected resources" tab
32       in the Management Center of your AI Foundry project.
33"""
34 
35import os
36import time
37import re
38from typing import Optional, Dict, List
39from azure.ai.projects import AIProjectClient
40from azure.identity import DefaultAzureCredential
41from azure.ai.agents import AgentsClient
42from azure.ai.agents.models import DeepResearchTool, MessageRole, ThreadMessage
43 
44def convert_citations_to_superscript(markdown_content):
45    """
46    Convert citation markers in markdown content to HTML superscript format.
47 
48    This function finds citation patterns like [78:12+source] and converts them to
49    HTML superscript tags <sup>12</sup> for better formatting in markdown documents.
50    It also consolidates consecutive citations by sorting and deduplicating them.
51 
52    Args:
53        markdown_content (str): The markdown content containing citation markers
54 
55    Returns:
56        str: The markdown content with citations converted to HTML superscript format
57    """
58    # Pattern to match [number:number+source]
59    pattern = r"\u3010\d+:(\d+)\u2020source\u3011"
60 
61    # Replace with <sup>captured_number</sup>
62    def replacement(match):
63        citation_number = match.group(1)
64        return f"<sup>{citation_number}</sup>"
65 
66    # First, convert all citation markers to superscript
67    converted_text = re.sub(pattern, replacement, markdown_content)
68 
69    # Then, consolidate consecutive superscript citations
70    # Pattern to match multiple superscript tags with optional commas/spaces
71    # Matches: <sup>5</sup>,<sup>4</sup>,<sup>5</sup> or <sup>5</sup><sup>4</sup><sup>5</sup>
72    consecutive_pattern = r"(<sup>\d+</sup>)(\s*,?\s*<sup>\d+</sup>)+"
73 
74    def consolidate_and_sort_citations(match):
75        # Extract all citation numbers from the matched text
76        citation_text = match.group(0)
77        citation_numbers = re.findall(r"<sup>(\d+)</sup>", citation_text)
78 
79        # Convert to integers, remove duplicates, and sort
80        unique_sorted_citations = sorted(set(int(num) for num in citation_numbers))
81 
82        # If only one citation, return simple format
83        if len(unique_sorted_citations) == 1:
84            return f"<sup>{unique_sorted_citations[0]}</sup>"
85 
86        # If multiple citations, return comma-separated format
87        citation_list = ",".join(str(num) for num in unique_sorted_citations)
88        return f"<sup>{citation_list}</sup>"
89 
90    # Remove consecutive duplicate citations and sort them
91    final_text = re.sub(consecutive_pattern, consolidate_and_sort_citations, converted_text)
92 
93    return final_text
94 
95def fetch_and_print_new_agent_response(
96    thread_id: str,
97    agents_client: AgentsClient,
98    last_message_id: Optional[str] = None,
99    progress_filename: str = "research_progress.txt",
100) -> Optional[str]:
101    """
102    Fetch the interim agent responses and citations from a thread and write them to a file.
103 
104    Args:
105        thread_id (str): The ID of the thread to fetch messages from
106        agents_client (AgentsClient): The Azure AI agents client instance
107        last_message_id (Optional[str], optional): ID of the last processed message
108            to avoid duplicates. Defaults to None.
109        progress_filename (str, optional): Name of the file to write progress to.
110            Defaults to "research_progress.txt".
111 
112    Returns:
113        Optional[str]: The ID of the latest message if new content was found,
114            otherwise returns the last_message_id
115    """
116    response = agents_client.messages.get_last_message_by_role(
117        thread_id=thread_id,
118        role=MessageRole.AGENT,
119    )
120 
121    if not response or response.id == last_message_id:
122        return last_message_id  # No new content
123 
124    # If not a "cot_summary", return.
125    if not any(t.text.value.startswith("cot_summary:") for t in response.text_messages):
126        return last_message_id
127 
128    print("\nAgent response:")
129    agent_text = "\n".join(t.text.value.replace("cot_summary:", "Reasoning:") for t in response.text_messages)
130    print(agent_text)
131 
132    # Print citation annotations (if any)
133    for ann in response.url_citation_annotations:
134        print(f"URL Citation: [{ann.url_citation.title}]({ann.url_citation.url})")
135 
136    # Write progress to file
137    with open(progress_filename, "a", encoding="utf-8") as fp:
138        fp.write("\nAGENT>\n")
139        fp.write(agent_text)
140        fp.write("\n")
141 
142        for ann in response.url_citation_annotations:
143            fp.write(f"Citation: [{ann.url_citation.title}]({ann.url_citation.url})\n")
144 
145    return response.id
146 
147def create_research_summary(message: ThreadMessage, filepath: str = "research_report.md") -> None:
148    """
149    Create a formatted research report from an agent's thread message with numbered citations
150    and a references section.
151 
152    Args:
153        message (ThreadMessage): The thread message containing the agent's research response
154        filepath (str, optional): Path where the research summary will be saved.
155            Defaults to "research_report.md".
156 
157    Returns:
158        None: This function doesn't return a value, it writes to a file
159    """
160    if not message:
161        print("No message content provided, cannot create research report.")
162        return
163 
164    with open(filepath, "w", encoding="utf-8") as fp:
165        # Write text summary
166        text_summary = "\n\n".join([t.text.value.strip() for t in message.text_messages])
167        # Convert citations to superscript format
168        text_summary = convert_citations_to_superscript(text_summary)
169        fp.write(text_summary)
170 
171        # Write unique URL citations with numbered bullets, if present
172        if message.url_citation_annotations:
173            fp.write("\n\n## Citations\n")
174            seen_urls = set()
175            # Dictionary mapping full citation content to ordinal number
176            citations_ordinals: Dict[str, int] = {}
177            # List of citation URLs indexed by ordinal (0-based)
178            text_citation_list: List[str] = []
179 
180            for ann in message.url_citation_annotations:
181                url = ann.url_citation.url
182                title = ann.url_citation.title or url
183 
184                if url not in seen_urls:
185                    # Use the full annotation text as the key to avoid conflicts
186                    citation_key = ann.text if ann.text else f"fallback_{url}"
187 
188                    # Only add if this citation content hasn't been seen before
189                    if citation_key not in citations_ordinals:
190                        # Assign next available ordinal number (1-based for display)
191                        ordinal = len(text_citation_list) + 1
192                        citations_ordinals[citation_key] = ordinal
193                        text_citation_list.append(f"[{title}]({url})")
194 
195                    seen_urls.add(url)
196 
197            # Write citations in order they were added
198            for i, citation_text in enumerate(text_citation_list):
199                fp.write(f"{i + 1}. {citation_text}\n")
200 
201    print(f"Research report written to '{filepath}'.")
202 
203if __name__ == "__main__":
204    project_client = AIProjectClient(
205        endpoint=os.environ["PROJECT_ENDPOINT"],
206        credential=DefaultAzureCredential(),
207    )
208    # [START create_agent_with_deep_research_tool]
209    bing_connection = project_client.connections.get(name=os.environ["BING_RESOURCE_NAME"])
210 
211    # Initialize a Deep Research tool with Bing Connection ID and Deep Research model deployment name
212    deep_research_tool = DeepResearchTool(
213        bing_grounding_connection_id=bing_connection.id,
214        deep_research_model=os.environ["DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME"],
215    )
216 
217    # Create Agent with the Deep Research tool and process Agent run
218    with project_client:
219 
220        with project_client.agents as agents_client:
221 
222            # Create a new agent that has the Deep Research tool attached.
223            # NOTE: To add Deep Research to an existing agent, fetch it with `get_agent(agent_id)` and then,
224            # update the agent with the Deep Research tool.
225            agent = agents_client.create_agent(
226                model=os.environ["MODEL_DEPLOYMENT_NAME"],
227                name="my-agent",
228                instructions="You are a helpful Agent that assists in researching scientific topics.",
229                tools=deep_research_tool.definitions,
230            )
231 
232            # [END create_agent_with_deep_research_tool]
233            print(f"Created agent, ID: {agent.id}")
234 
235            # Create thread for communication
236            thread = agents_client.threads.create()
237            print(f"Created thread, ID: {thread.id}")
238 
239            # Create message to thread
240            message = agents_client.messages.create(
241                thread_id=thread.id,
242                role="user",
243                content=(
244                    "Research the current state of studies on orca intelligence and orca language, including what is currently known about orcas' cognitive capabilities and communication systems."
245                ),
246            )
247            print(f"Created message, ID: {message.id}")
248 
249            print(f"Start processing the message... this may take a few minutes to finish. Be patient!")
250            # Poll the run as long as run status is queued or in progress
251            run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id)
252            last_message_id = None
253            while run.status in ("queued", "in_progress"):
254                time.sleep(1)
255                run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
256 
257                last_message_id = fetch_and_print_new_agent_response(
258                    thread_id=thread.id,
259                    agents_client=agents_client,
260                    last_message_id=last_message_id,
261                    progress_filename="research_progress.txt",
262                )
263                print(f"Run status: {run.status}")
264 
265            # Once the run is finished, print the final status and ID
266            print(f"Run finished with status: {run.status}, ID: {run.id}")
267 
268            if run.status == "failed":
269                print(f"Run failed: {run.last_error}")
270 
271            # Fetch the final message from the agent in the thread and create a research summary
272            final_message = agents_client.messages.get_last_message_by_role(thread_id=thread.id, role=MessageRole.AGENT)
273            if final_message:
274                create_research_summary(final_message)
275 
276            # Clean-up and delete the agent once the run is finished.
277            # NOTE: Comment out this line if you plan to reuse the agent later.
278            agents_client.delete_agent(agent.id)
279            print("Deleted agent")