Deep Research Agents Cookbook

This cookbook demonstrates how to build Agentic research workflows using the OpenAI Deep Research API and the OpenAI Agents SDK. It is a continuation of a fundamentals cookbook, if you have not already familiarized yourself with that content, please consider doing so.

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, and architect a robust research application.

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.

Prerequisites

• OpenAI API key (set as OPENAI_API_KEY in your environment)
• Agents SDK and OpenAI Python SDK

Setup

Install dependencies

Import libraries and configure client

Zero Data Retention

We disable Data Retention through the os.environ setting below. This allows Enterprises to operate in a Zero Data Retention environment with Deep Research. If Data Retention is not an active constraint for you, then consider keeping it enabled so you can have automated tracability for your agent workflows and deep integration with other platform tools like evaluations and fine tuning.

Basic Deep Research Agent

The Basic Research Agent performs Deep Research using the o4-mini-deep-research-alpha model. It has native WebSearch access to the public internet and streams its findings directly back into the notebook. In this case we are using the o4-mini-deep-research-alpha model, because it is faster than the full o3 deep research model, with acceptable intelligence.

Learning objective:

After this, you can run a single-agent research task and stream its progress.

Multi-Agent Research with Clarification

Multi-Agent Deep Research

Consider how you might further improve the Research quality "Deep Research" produces. In this case, we are leveraging a multi-agent architecture to enrich the prompt with more information about the users query and what we expect to see in the final research report, before submitting it to a deep research agent.

Sub-Agent Prompt enrichment

The supporting Agent prompts are specifically designed to improve the quality of the final research output by providing structure and rigor to the users intial query.

Four-Agent Deep Research Pipeline

1. Triage Agent

   • Inspects the user’s query
   • If context is missing, routes to the Clarifier Agent; otherwise routes to the Instruction Agent

2. Clarifier Agent

   • Asks follow-up questions
   • Waits for user (or mock) answers

3. Instruction Builder Agent

   • Converts the enriched input into a precise research brief

4. Research Agent (o3-deep-research)

   • Performs web-scale empirical research with WebSearchTool
   • Performs a search against internal knowledge store using MCP, if there are relevant documents, the agent incorporates those relevant snippets in its reference material.
   • Streams intermediate events for transparency
   • Outputs final Research Artifact (which we later parse)

For more insight into how the MCP server is build. See this resource.

Agent Interaction Flow

Although provided natively through Agent SDK traces you may want to print human-readable high-level agent interaction flow with tool calls. Run print_agent_interaction to get a simplified readable sequence of agent steps, including: Agent name, Type of event (handoff, tool call, message output), Brief tool call info (tool name and arguments).

Citations

Below is a Python snippet to extract and print the URL citations related to the final output:

Conclusion

With the patterns in this notebook, you now have a foundation for building scalable, production-ready research workflows using OpenAI Deep Research Agents. The examples demonstrate not only how to orchestrate multi-agent pipelines and stream research progress, but also how to integrate web search and MCP for external knowledge access.

By leveraging agentic workflows, you can move beyond simple Q&A to tackle complex, multi-step research tasks that require planning, synthesis, and tool use. The modular multi-agent design: triage, clarification, instruction, and research agents enables you to adapt these pipelines to a wide range of domains and use cases, from healthcare and finance to technical due diligence and market analysis.

As the Deep Research API and Agents SDK continue to evolve, these patterns will help you stay at the forefront of automated, data-backed research. Whether you’re building internal knowledge tools, automating competitive intelligence, or supporting expert analysts, these workflows provide a strong, extensible starting point.

Happy researching!