This document provides a comprehensive overview of the DeepResearchSDK repository, an AI-powered research automation system that orchestrates multiple specialized AI agents to conduct in-depth research and generate comprehensive reports. This overview covers the system's architecture, core components, and key capabilities.
DeepResearchSDK is an OpenAI Agent SDK-based framework designed to automate complex research workflows through coordinated AI agent cooperation. The system transforms user queries into comprehensive, well-researched markdown reports by orchestrating a pipeline of specialized agents, each optimized for specific research tasks.
The framework operates on a multi-agent architecture where each agent has distinct responsibilities: initial topic scanning, research planning, deep web searching, and report synthesis. This modular approach enables parallel execution while maintaining clear separation of concerns.
The DeepResearchSDK follows a hub-and-spoke architecture with ResearchManager as the central orchestrator coordinating specialized agents and external service integrations.
The research process follows a sequential pipeline where each agent's output becomes the input for the next stage, with parallel execution during the deep search phase.
Research Execution Pipeline
The system provides several advanced capabilities that distinguish it from simpler research tools:
| Feature | Implementation | Code Location |
|---|---|---|
| Parallel Execution | Multiple DeepResearcherAgent instances run concurrently | deep_researcher_agent.py |
| Perplexity Integration | Real-time web search via PerplexityResearchTool | perplexity_research_tool.py |
| Agent Orchestration | Centralized coordination through ResearchManager | research_manager.py |
| Automated Report Generation | Structured markdown output via WriterAgent | writer_agent.py |
| Tracing and Debugging | OpenAI trace IDs for execution monitoring | research_manager.py |
| Multi-Interface Support | CLI, web, and notebook interfaces | deep_research.py |
ResearchManager: Central orchestrator that coordinates the entire research pipeline, manages agent lifecycle, and handles asynchronous execution flowdeep_research.py: Primary entry point providing both CLI interface and programmatic API accessInitialResearchAgent: Performs rapid, cost-effective initial topic scanning using OpenAI modelsPlannerAgent: Analyzes initial research to generate focused WebSearchPlan containing structured search tasksDeepResearcherAgent: Executes individual search tasks using Perplexity API for current information retrievalWriterAgent: Synthesizes all research results into coherent, structured markdown reportsPerplexityResearchTool: Handles web search functionality through Perplexity APIWebSearchPlan: Container for organized search tasks generated by PlannerAgentWebSearchItem: Individual search task with reason and query componentsReportData: Final output structure containing summary and formatted markdown reportThe system maintains clear separation between production code and experimental development:
deep_research/ directory with production-ready implementationsresearch.ipynb notebook for experimentation and prototypingrequirements.txt and pyproject.toml for package management