Skip to content

Deep research api #1923

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Jun 26, 2025
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
43 changes: 2 additions & 41 deletions examples/deep_research_api/introduction_to_deep_research_api.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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))."
]
},
{
Expand Down Expand Up @@ -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:"
]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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."
]
Expand Down Expand Up @@ -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 )"
]
},
{
Expand Down
Binary file added images/agent_dr.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/intro_dr.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/mcp_dr.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.