Unable to Trigger start_research_task() function with Deep Research + Bing Grounding using Python SDK for Azure AI

Question

Hi all,

I was exploring capabilities of Deep Research with Azure AI Foundry (Request raised previously for o3 models which was accepted). We also have Bing grounding setup & connected with Azure AI Foundry.

I have used couple of references when implementing Deep Research

https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_async/sample_agents_deep_research_async.py

https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/deep-research-samples?pivots=python

When executing the script (shared below), I am able to run script without any errors & do get result, but the Deep Research Phase with o3-deep-research does not execute & all I see is the following Output,

start_research_task(
    task_violates_safety_guidelines=False,
    user_def_doesnt_want_research=False,
    response="I'll begin full deep research on the current state of studies on orca intelligence and orca language, including an analysis of their cognitive capabilities and communication systems. The structured report will include sections on intelligence, communication methods, research methodologies, recent findings, controversies, and future research directions. I'll provide references for further reading.",
    title="Orca Intelligence and Language Studies",
    prompt="Research the current state of studies on orca intelligence and orca language, including what is currently known about orcas' cognitive capabilities and communication systems. The report should include:\n\n1. An overview of orca intelligence: cognitive capabilities, problem-solving, social learning, memory, and related behaviors.\n2. A detailed review of orca communication systems: vocalizations, social communication, structure of their calls, regional dialects, and comparisons with other cetaceans.\n3. Research methodologies: observational studies, acoustic analysis, controlled experiments, and any technological approaches used.\n4. Discussion on recent findings, controversies, and suggested future research directions.\n\nThe report should be structured with clear headings and subheadings, and where appropriate, use tables to compare studies or findings. Include citations or references to reliable sources for each section. Please format the report as a detailed, organized document and respond in English."
)

I did some exploration over the Internet and found that there's 2 phases, the Intent phase (Intent clarifying which uses gpt-4o & the execution phase which uses o3-deep-research with Bing grounding.

Check out this code that I have used,

import asyncio
import os
import re

from azure.ai.projects.aio import AIProjectClient
from azure.ai.agents.aio import AgentsClient
from azure.ai.agents.models import DeepResearchTool, MessageRole, ThreadMessage
from azure.identity.aio import DefaultAzureCredential


def convert_citations_to_superscript(markdown_content: str) -> str:
    pattern = re.compile(r"\u3010\d+:(\d+)\u2020source\u3011")
    def replacement(match): return f"<sup>{match.group(1)}</sup>"
    return pattern.sub(replacement, markdown_content)


def create_research_summary(message: ThreadMessage, filepath: str = "research_report_2.md") -> None:
    if not message:
        print("No message to summarize.")
        return

    with open(filepath, "w", encoding="utf-8") as fp:
        text_summary = "\n\n".join([t.text.value.strip() for t in message.text_messages])
        text_summary = convert_citations_to_superscript(text_summary)
        fp.write(text_summary)

        if message.url_citation_annotations:
            fp.write("\n\n## Citations\n")
            seen = set()
            for i, ann in enumerate(message.url_citation_annotations, start=1):
                url, title = ann.url_citation.url, ann.url_citation.title or ann.url_citation.url
                if url not in seen:
                    fp.write(f"{i}. [{title}]({url})\n")
                    seen.add(url)

    print(f"Research report written to '{filepath}'.")


async def run_research_task(
    agents_client: AgentsClient,
    thread_id: str,
    agent_id: str,
    title: str,
    refined_prompt: str,
) -> None:
    """Trigger a final research run after kickoff and save report."""

    kickoff_message = (
        f"start_research_task confirmed.\n"
        f"user_def_doesnt_want_research=False,\n"
        f"task_violates_safety_guidelines=False,\n"
        f"Title: {title}\n"
        f"Prompt: {refined_prompt}\n"
        f"Please begin full deep research and return the structured report with references."
    )

    await agents_client.messages.create(
        thread_id=thread_id,
        role="user",
        content=kickoff_message,
    )

    run = await agents_client.runs.create(thread_id=thread_id, agent_id=agent_id)
    while run.status in ("queued", "in_progress"):
        await asyncio.sleep(2)
        run = await agents_client.runs.get(thread_id=thread_id, run_id=run.id)
        print(f"Run status: {run.status}")

    print(f"Run finished with status: {run.status}, ID: {run.id}")
    if run.status == "failed":
        print(f"Run failed: {run.last_error}")
        return

    final_message = await agents_client.messages.get_last_message_by_role(
        thread_id=thread_id, role=MessageRole.AGENT
    )
    if final_message:
        print("Final research report received, saving...", final_message)
        create_research_summary(final_message)

        
async def main() -> None:
    project_client = AIProjectClient(
        endpoint=os.environ["PROJECT_ENDPOINT"],
        credential=DefaultAzureCredential(),
    )

    bing_connection = await project_client.connections.get(name=os.environ["BING_RESOURCE_NAME"])
    deep_research_tool = DeepResearchTool(
        bing_grounding_connection_id=bing_connection.id,
        deep_research_model=os.environ["DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME"],
    )

    async with project_client:
        agents_client = project_client.agents

        agent = await agents_client.create_agent(
            model=os.environ["MODEL_DEPLOYMENT_NAME"],
            name="deep-research-agent",
            instructions="You are a research assistant. Clarify intent if needed, then conduct deep research.",
            tools=deep_research_tool.definitions,
        )
        print(f"Created agent, ID: {agent.id}")

        thread = await agents_client.threads.create()
        print(f"Created thread, ID: {thread.id}")

        # Phase 1: initial user prompt
        user_prompt = (
            "Research the current state of studies on orca intelligence and orca language, "
            "including what is currently known about orcas' cognitive capabilities and communication systems."
        )
        await agents_client.messages.create(
            thread_id=thread.id,
            role="user",
            content=user_prompt,
        )

        # run = await agents_client.runs.create(thread_id=thread.id, agent_id=agent.id)
        run = await agents_client.runs.create_and_process(
            thread_id=thread.id, agent_id=agent.id
        )

        while run.status in ("queued", "in_progress"):
            await asyncio.sleep(2)
            run = await agents_client.runs.get(thread_id=thread.id, run_id=run.id)
            print(f"Initial run status: {run.status}")

        final_message = await agents_client.messages.get_last_message_by_role(
            thread_id=thread.id, role=MessageRole.AGENT
        )

        # Fetch and log all messages
        messages = project_client.agents.messages.list(thread_id=thread.id)
        async for msg in messages:
            print(f"Message [{msg.role}]: {msg.content}")

        run_steps = project_client.agents.run_steps.list(thread_id=thread.id, run_id=run.id)
        async for step in run_steps:
            print(f"Step {step['id']} status: {step['status']}")

            # Check if there are tool calls in the step details
            step_details = step.get("step_details", {})
            tool_calls = step_details.get("tool_calls", [])

            if tool_calls:
                print("  Tool calls:")
                for call in tool_calls:
                    print(f"    Tool Call ID: {call.get('id')}")
                    print(f"    Type: {call.get('type')}")

                    function_details = call.get("function", {})
                    if function_details:
                        print(f"    Function name: {function_details.get('name')}")
            print()  # add an extra newline between steps

        if final_message:
            text_blocks = [t.text.value for t in final_message.text_messages]
            combined_text = "\n".join(text_blocks)

            # Detect kickoff
            match = re.search(r"start_research_task\((.*?)\)", combined_text, re.DOTALL)
            if match:
                print("Kickoff detected. Extracting refined prompt...")
                title_match = re.search(r'title="([^"]+)"', match.group(1))
                prompt_match = re.search(r'prompt="([^"]+)"', match.group(1))
                refined_prompt = prompt_match.group(1) if prompt_match else user_prompt
                title = title_match.group(1) if title_match else "Deep Research Task"
                await run_research_task(agents_client, thread.id, agent.id, title, refined_prompt)

            else:
                print("No kickoff detected, saving report...")
                create_research_summary(final_message)

        await agents_client.delete_agent(agent.id)
        print("Deleted agent")


if __name__ == "__main__":
    asyncio.run(main())

Here's the Output received,

(env) xxxx.xxxxx@INBLRM4061479A deep-research-python % python3 deep_research.py
Created agent, ID: asst_bpEeDi7pVMzZzMk1S00Jv2PK
Created thread, ID: thread_5WEehOUU4z4lwzVTJmysq9zV
Message [MessageRole.AGENT]: [{'type': 'text', 'text': {'value': 'start_research_task(\ntask_violates_safety_guidelines=False,\nuser_def_doesnt_want_research=False,\nresponse="Great! I\'ll research the current state of studies on orca intelligence and language, summarizing what is known about their cognitive capabilities and communication systems, and will organize the information in a detailed report.",\ntitle="Orca Intelligence and Language Studies",\nprompt="Research the current state of studies on orca intelligence and orca language. The report should cover the following:\\n\\n1. Overview of orca intelligence: current scientific insights into cognitive capabilities, problem-solving, social learning, and memory.\\n2. Detailed review of orca communication systems and language characteristics: structure of vocalizations, social communication, regional dialects, and comparisons to other cetaceans.\\n3. Discussion of research methodologies used in studying orcas, including observational studies, acoustic analysis, and controlled experiments.\\n4. Recent findings, controversies, and future research directions.\\n\\nPlease include clear headings, subheadings, tables (if applicable) for comparisons, and cite reliable sources. Format the report as a structured document with clear sections and a summary conclusion. Respond in English."\n)', 'annotations': []}}]
Message [MessageRole.USER]: [{'type': 'text', 'text': {'value': "Research the current state of studies on orca intelligence and orca language, including what is currently known about orcas' cognitive capabilities and communication systems.", 'annotations': []}}]
Step step_OoMiUoGBtwj6FicmtMW0Die4 status: completed

Kickoff detected. Extracting refined prompt...
Run status: RunStatus.IN_PROGRESS
Run status: RunStatus.IN_PROGRESS
Run status: RunStatus.COMPLETED
Run finished with status: RunStatus.COMPLETED, ID: run_69dYihHyIusd4j34rqRMZMR8
Final research report received, saving... {'id': 'msg_FnC5oZioL9iGLdhMtD3e7aBS', 'object': 'thread.message', 'created_at': 1756827131, 'assistant_id': 'asst_bpEeDi7pVMzZzMk1S00Jv2PK', 'thread_id': 'thread_5WEehOUU4z4lwzVTJmysq9zV', 'run_id': 'run_69dYihHyIusd4j34rqRMZMR8', 'role': 'assistant', 'content': [{'type': 'text', 'text': {'value': 'start_research_task(\n    task_violates_safety_guidelines=False,\n    user_def_doesnt_want_research=False,\n    response="I\'ll begin full deep research on the current state of studies on orca intelligence and orca language, including an analysis of their cognitive capabilities and communication systems. The structured report will include sections on intelligence, communication methods, research methodologies, recent findings, controversies, and future research directions. I\'ll provide references for further reading.",\n    title="Orca Intelligence and Language Studies",\n    prompt="Research the current state of studies on orca intelligence and orca language, including what is currently known about orcas\' cognitive capabilities and communication systems. The report should include:\\n\\n1. An overview of orca intelligence: cognitive capabilities, problem-solving, social learning, memory, and related behaviors.\\n2. A detailed review of orca communication systems: vocalizations, social communication, structure of their calls, regional dialects, and comparisons with other cetaceans.\\n3. Research methodologies: observational studies, acoustic analysis, controlled experiments, and any technological approaches used.\\n4. Discussion on recent findings, controversies, and suggested future research directions.\\n\\nThe report should be structured with clear headings and subheadings, and where appropriate, use tables to compare studies or findings. Include citations or references to reliable sources for each section. Please format the report as a detailed, organized document and respond in English."\n)', 'annotations': []}}], 'attachments': [], 'metadata': {}}
Research report written to 'research_report_2.md'.
Deleted agent
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x106ea7e00>

How do I get the execution phase with Deep research (including URLs, Citations) that we usually see with ChatGPT or other LLMs?

Answer 1

Hello Zaid Shaikh

Sorry for delayed response

Thanks for the details provided, You are seeking validation of your Azure AI Foundry setup to ensure that the Deep Research tool executes correctly, particularly the second phase involving the o3-deep-research model with Bing grounding. Here's a detailed and accurate response addressing each component of their configuration:

Your setup appears to be mostly aligned with the requirements for enabling Deep Research in Azure AI Foundry. Starting with the Python packages, you’ve listed azure-ai-agents>=1.0.0b1 and azure-ai-projects>=1.0.0b1, which are functional for basic agent operations. However, for full support of Deep Research—including tool invocation and Bing grounding integration—it is strongly recommended to upgrade both packages to at least version 1.1.0-beta.4 or later. This version includes critical enhancements that ensure the agent can correctly interpret the kickoff message and trigger the execution phase using the DeepResearchTool. Your other packages, azure-identity>=1.17.0 and python-dotenv>=1.0.1, are appropriate and do not require changes.

Regarding your resource deployment, you’ve confirmed that all components—Bing grounding, the o3-deep-research model, and the GPT-4o model—are deployed in the Norway East region. This is one of the two supported regions (alongside West US) where Deep Research is fully operational, so your regional configuration is correct. The environment variables you’ve shared also follow the expected format. The PROJECT_ENDPOINT is structured correctly, pointing to the Azure AI Foundry project API. The BING_RESOURCE_NAME should match the name of the Bing grounding connection configured in your Azure AI Foundry project. Most importantly, the values for DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME and MODEL_DEPLOYMENT_NAME—set to o3-deep-research and o3-mini respectively—must exactly match the deployment names in Azure, including casing and spelling. Any mismatch here can prevent the agent from invoking the correct model during the execution phase.

Additionally, ensure that your agent instructions explicitly guide the agent to use the Deep Research tool after intent clarification. A recommended instruction would be: “You are a research assistant. Clarify intent if needed, then conduct deep research using the Deep Research tool.” This helps the agent understand that it must transition from the intent phase to the execution phase using the registered tool. If all these configurations are correct and the execution phase still does not trigger, it may be helpful to test with a minimal working example from Microsoft’s official GitHub samples or check the Azure AI Foundry issue tracker for any known bugs. Let me know if you’d like help reviewing your deployment setup further or drafting a simplified test script to validate the Deep Research flow.

Hope it helps!

Thank you