Deep Research Agent

This repository contains a deep research agent that uses multiple AI agents to conduct comprehensive research. It includes a web UI for interacting with the agent through a conversational interface.

The current implementation works but has no durability - if the application crashes, all progress is lost. In the companion tutorial, you'll learn how to add Temporal to make this application durable and production-ready.

What This Application Does

The deep research agent:

1. Triages your research query to determine if it needs clarification
2. Asks clarifying questions if your query is too broad
3. Plans a web search strategy based on your query
4. Searches multiple sources concurrently
5. Writes a comprehensive research report

The Problem: No Durability

Without Temporal, this application has critical weaknesses:

• Lost Progress: If the server crashes during research, everything is lost
• Wasted API Calls: Expensive LLM calls must be repeated after failures
• No Recovery: Users must start completely over after any interruption
• In-Memory State: All session data disappears when the server restarts

Quick Start

Prerequisites

• Python 3.10 or later
• An OpenAI API key

Setup

1. Clone the repository:

   git clone https://github.com/temporalio/edu-deep-research-tutorial-template.git
   cd edu-deep-research-tutorial-template

2. Install dependencies:

   uv sync

3. Configure your API key:

   cp .env-sample .env
   # Edit .env and add your OpenAI API key

4. Run the application:

   uv run run_server.py

5. Open your browser: Navigate to http://localhost:8234

Project Structure

edu-deep-research-tutorial-template/
├── deep_research/
│   ├── agents/               # AI agent implementations
│   │   ├── triage_agent.py   # Determines if clarification needed
│   │   ├── clarifying_agent.py  # Generates clarifying questions
│   │   ├── planner_agent.py  # Creates search strategy
│   │   ├── search_agent.py   # Performs web searches
│   │   └── writer_agent.py   # Writes the final report
│   ├── models.py             # Data models
│   └── research_manager.py   # Orchestrates the research pipeline
├── ui/                       # Web interface
│   ├── index.html            # Chat interface
│   ├── success.html          # Results page
│   └── src/
│       ├── css/styles.css
│       └── js/api-client.js
├── run_server.py             # FastAPI server
├── pyproject.toml            # Dependencies
└── README.md

Next Steps

Complete the Building a Durable Deep Research Agent tutorial to:

1. Use the OpenAI Agents SDK Temporal integration for automatic LLM call durability
2. Create a durable Workflow that orchestrates the research pipeline
3. Add human-in-the-loop capabilities with Workflow Updates
4. Handle failures gracefully with automatic retries
5. Make your research sessions survive crashes and restarts

Credit

This code is an adapted version from this repository by steveandroulakis.