diff --git a/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/README.md b/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/README.md index 46f0f45bbb..8cb282d1cf 100644 --- a/examples/deep_research_api/how_to_build_a_deep_research_mcp_server/README.md +++ b/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
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
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
cost-effectiveness, market revenue…] - C7 --> C1 - end -``` +![../../../images/mcp_dr.png](../../../images/mcp_dr.png) ## Example request diff --git a/examples/deep_research_api/introduction_to_deep_research_api.ipynb b/examples/deep_research_api/introduction_to_deep_research_api.ipynb index 030d644b21..dc202f0c0c 100644 --- a/examples/deep_research_api/introduction_to_deep_research_api.ipynb +++ b/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]()." + "If you would like to see _how_ we built this simple MCP server. Refer to [this related cookbook]([](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
lightweight model]\n", - " Q[Clarifying Questions]\n", - " UQ([User’s Answers])\n", - " R[Rewriter
lightweight model]\n", - " EP[Enriched Prompt]\n", - " DR[Deep Research
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
optional]\n", - " EP2[Enriched Prompt]\n", - " DR2[Deep Research API
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:" ] diff --git a/examples/deep_research_api/introduction_to_deep_research_api_agents.ipynb b/examples/deep_research_api/introduction_to_deep_research_api_agents.ipynb index f45fdbce5f..43ec3e9779 100644 --- a/examples/deep_research_api/introduction_to_deep_research_api_agents.ipynb +++ b/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
• Inspect query
• Route based on context]\n", - " end\n", - " subgraph Clarifier\n", - " CA[Clarifier Agent
• Ask follow‐up questions
• Receive answers]\n", - " end\n", - " subgraph Instruction\n", - " IA[Instruction Builder Agent
• Build precise research brief]\n", - " end\n", - " subgraph Research\n", - " RA[Research Agent
o3‐deep‐research
• WebSearchTool
• Internal MCP search
• Stream events
• 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 )" ] }, { diff --git a/images/agent_dr.png b/images/agent_dr.png new file mode 100644 index 0000000000..3f1180f9a7 Binary files /dev/null and b/images/agent_dr.png differ diff --git a/images/intro_dr.png b/images/intro_dr.png new file mode 100644 index 0000000000..e84803709d Binary files /dev/null and b/images/intro_dr.png differ diff --git a/images/mcp_dr.png b/images/mcp_dr.png new file mode 100644 index 0000000000..671fa67399 Binary files /dev/null and b/images/mcp_dr.png differ