Deep research api (#1922)

Author: alwell-kevin

examples/deep_research_api/how_to_build_a_deep_research_mcp_server/README.md

@@ -36,34 +36,11 @@ You should now be able to reach your local server from your client.
 
 ## Files
 
-- `main.py`: Main server code
+- `main.py`: [Main server code](https://github.com/openai/openai-cookbook/blob/main/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/main.py)
 
 ## Example Flow diagram for MCP Server
 
-```mermaid
-flowchart TD
-  subgraph Connection_Setup
-    A1[MCP Server starts up<br/>listening on /sse/] --> A2[Client opens SSE connection]
-    A2 --> A3[Server confirms SSE connection]
-  end
-
-  subgraph Tool_Discovery
-    A3 --> B1[Client asks 'What tools do you support?']
-    B1 --> B2[Server replies with Search & Fetch schemas]
-    B2 --> B3[Client stores schemas in context]
-  end
-
-  subgraph Search_Fetch_Loop
-    B3 --> C1[Client issues search call]
-    C1 --> C2[MCP Server routes to Search Tool]
-    C2 --> C3[Search Tool queries Data Store<br/>returns one hit]
-    C3 --> C4[Client issues fetch call]
-    C4 --> C5[MCP Server routes to Fetch Tool]
-    C5 --> C6[Fetch Tool retrieves document text]
-    C6 --> C7[Client refines/repeats search<br/> cost-effectiveness, market revenue…]
-    C7 --> C1
-  end
-```
+![../../../images/mcp_dr.png](../../../images/mcp_dr.png)
 
 ## Example request
 

examples/deep_research_api/introduction_to_deep_research_api.ipynb

@@ -295,7 +295,7 @@
         "\n",
         "In the example below, we configure an MCP tool that lets Deep Research fetch your organizations internal semaglutide studies on demand. The MCP server is a proxy for the OpenAI File Storage service that automagically vectorizes your uploaded files for performant retrieval.\n",
         "\n",
-        "If you would like to see _how_ we built this simple MCP server. Refer to [this related cookbook](<placeholder>)."
+        "If you would like to see _how_ we built this simple MCP server. Refer to [this related cookbook]([<placeholder>](https://cookbook.openai.com/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/readme))."
       ]
     },
     {
@@ -454,46 +454,7 @@
         "\n",
         "This setup gives developers full control over how research tasks are framed, but also places greater responsibility on the quality of the input prompt. Here's an example of a generic rewriting_prompt to better direct the subsequent deep research query.\n",
         "\n",
-        "```mermaid\n",
-        "flowchart TD\n",
-        "  %% Interactive ChatGPT Flow with Clarifier\n",
-        "  subgraph ChatGPT Session\n",
-        "    direction TB\n",
-        "    U1([User Query])\n",
-        "    C[Clarifier<br/>lightweight model]\n",
-        "    Q[Clarifying Questions]\n",
-        "    UQ([User’s Answers])\n",
-        "    R[Rewriter<br/>lightweight model]\n",
-        "    EP[Enriched Prompt]\n",
-        "    DR[Deep Research<br/>o3-deep-research]\n",
-        "    O[Research Results]\n",
-        "\n",
-        "    U1 --> C\n",
-        "    C  --> Q\n",
-        "    Q  --> UQ\n",
-        "    UQ --> R\n",
-        "    R  --> EP\n",
-        "    EP --> DR\n",
-        "    DR --> O\n",
-        "  end\n",
-        "\n",
-        "  %% Deep Research API Flow (no built-in clarifier)\n",
-        "  subgraph Deep Research API\n",
-        "    direction TB\n",
-        "    U2([User Query])\n",
-        "    R2[Rewriter<br/>optional]\n",
-        "    EP2[Enriched Prompt]\n",
-        "    DR2[Deep Research API<br/>o3-deep-research]\n",
-        "    O2[Research Results]\n",
-        "\n",
-        "    U2 -->|include all details up-front| EP2\n",
-        "    EP2 --> DR2\n",
-        "    DR2 --> O2\n",
-        "\n",
-        "    U2 -->|use prompt rewriter| R2\n",
-        "    R2 --> EP2\n",
-        "  end\n",
-        "```\n",
+        "![../../../images/intro_dr.png](../../../images/intro_dr.png)\n",
         "\n",
         "Here's an example of a rewriting prompt:"
       ]

examples/deep_research_api/introduction_to_deep_research_api_agents.ipynb

@@ -10,7 +10,7 @@
         "\n",
         "This cookbook demonstrates how to build Agentic research workflows using the OpenAI Deep Research API and the OpenAI [Agents SDK](https://openai.github.io/openai-agents-python/). It is a continuation of [a fundamentals cookbook](https://cookbook.openai.com/examples/deep_research_api/introduction_to_deep_research_api), if you have not already familiarized yourself with that content, please consider doing so.\n",
         "\n",
-        "You’ll learn how to orchestrate single and multi-agent pipelines, enrich user queries to maximize output quality, stream research progress, integrate web search and [MCP for internal file search](https://cookbook.openai.com/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/README), and architect a robust research application.\n",
+        "You’ll learn how to orchestrate single and multi-agent pipelines, enrich user queries to maximize output quality, stream research progress, integrate web search and [MCP for internal file search](https://cookbook.openai.com/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/readme), and architect a robust research application.\n",
         "\n",
         "Consider using Deep Research Agents for tasks that require planning, synthesis, tool use, or multi-step reasoning. Do not use Deep Research for trivial fact lookups, simple Q&A, or short-form chat, a vanilla openai.responsesAPI would be faster and cheaper."
       ]
@@ -260,28 +260,9 @@
         "   - Streams intermediate events for transparency\n",
         "   - Outputs final Research Artifact (which we later parse)\n",
         "\n",
-        "```mermaid\n",
-        "flowchart LR\n",
-        "    subgraph Triage\n",
-        "        TA[Triage Agent<br/>• Inspect query<br/>• Route based on context]\n",
-        "    end\n",
-        "    subgraph Clarifier\n",
-        "        CA[Clarifier Agent<br/>• Ask follow‐up questions<br/>• Receive answers]\n",
-        "    end\n",
-        "    subgraph Instruction\n",
-        "        IA[Instruction Builder Agent<br/>• Build precise research brief]\n",
-        "    end\n",
-        "    subgraph Research\n",
-        "        RA[Research Agent<br/> o3‐deep‐research <br/>• WebSearchTool<br/>• Internal MCP search<br/>• Stream events<br/>• Output Artifact]\n",
-        "    end\n",
-        "\n",
-        "    TA -->|Missing context| CA\n",
-        "    TA -->|Context OK| IA\n",
-        "    CA --> IA\n",
-        "    IA --> RA\n",
-        "```\n",
-        "\n",
-        "For more insight into _how_ the MCP server is build. [See this resource.](https://cookbook.openai.com/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/README )"
+        "![../../../images/agents_dr.png](../../../images/agents_dr.png)\n",
+        "\n",
+        "For more insight into _how_ the MCP server is build. [See this resource.](https://cookbook.openai.com/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/readme )"
       ]
     },
     {