🔎Deep Research Agent

👨‍💻 Author: Shailesh Gupta

🔗 GitHub: View Source Code

🧠 What is this project about?

This is an agentic Deep Research Assistant built using Gradio, OpenAI Agents SDK, Web Search, Pydantic, and SendGrid.

Unlike a simple chatbot that gives one quick answer, this system behaves more like a structured research assistant. It first checks whether the user’s query is clear enough, asks 3 to 4 clarifying questions when necessary, creates a targeted research plan, performs multiple web searches, collects structured evidence, and finally generates a detailed long-form research report.

The system also uses an orchestrator-agent architecture, where a top-level manager coordinates specialized agents for clarification, planning, searching, writing, and delivery.

In simple terms, this project was built to simulate how a real AI-powered research workflow should operate — step by step, with reasoning, structure, evidence, and synthesis.

📦 Key Features

✅ Clarification-first workflow for vague or underspecified research queries
✅ Structured research planning with refined query, research goal, assumptions, and prioritized searches
✅ Web research agent that performs targeted searches and extracts useful findings
✅ Structured evidence collection with summaries, key findings, notable sources, and uncertainty tracking
✅ Long-form report generation with executive summary, title, outline, key takeaways, assumptions, gaps, and follow-up questions
✅ Orchestrator-agent architecture using agents-as-tools and handoffs
✅ Concurrent search execution for faster research runs
✅ Interactive Gradio frontend with pause/resume flow for clarification answers
✅ Optional email delivery of the final research report using SendGrid

🏗️ How the system works

The workflow looks like this:

User Query
⬇
Clarification Check
⬇
Clarifying Questions (if needed)
⬇
Research Plan Generation
⬇
Concurrent Web Searches
⬇
Structured Evidence Collection
⬇
Report Writing
⬇
Optional Email Delivery

This is what makes the project feel like a proper research workflow rather than just another one-shot LLM app.

🚀 What I started with

The first version of this project was much simpler.

Initially, I had:

a Gradio interface
a planner that generated search terms
a search agent that summarized results
a writer agent that created the final report
an email agent that sent the final result

It worked, but it still had some major limitations.

It assumed the user query was always clear.
It did not ask clarifying questions.
It passed loose summaries between stages.
It was more of a linear pipeline than a true agentic system.
And most importantly, it felt more like a prototype than a serious product.

That is when I decided to redesign it properly.

🔧 How I improved it

To make the project more useful, more realistic, and more portfolio-worthy, I introduced several important upgrades.

1️⃣ Clarification-first design

The system now first checks whether the user query is too broad, vague, or underspecified.

If needed, it asks 3 to 4 targeted clarifying questions before doing any real research.

This dramatically improves the quality of the search plan and reduces wasted searches.

2️⃣ Better planning layer

Instead of generating search terms directly from the raw prompt, the planner now builds:

a refined query
a research goal
assumptions
constraints
prioritized search items

This makes the entire workflow more intentional and structured.

3️⃣ Structured search outputs

The search agent no longer returns just a loose paragraph.

It now produces structured outputs such as:

concise summary
key findings
notable sources
evidence gaps or uncertainties

This makes the results much more usable downstream.

4️⃣ Richer report generation

The writer agent now produces:

report title
executive summary
report outline
long-form markdown report
key takeaways
assumptions used
research gaps
follow-up questions

That makes the final output feel much more polished and useful.

5️⃣ Orchestrator-agent architecture

The biggest architectural upgrade was introducing a top-level orchestrator agent.

Instead of one script directly calling every component, the manager now routes work across specialized agents using:

agents as tools
handoffs
stage-based orchestration

This made the system far more modular, scalable, and impressive as a serious AI project.

🧩 Main Components Used

1. Gradio UI

Used for the frontend and user interaction flow.

The UI allows users to:

enter the initial research query
see clarification questions
submit clarification answers
view workflow updates
read the final report

2. Clarification Agent

Checks if the query needs clarification before the system proceeds.

3. Planner Agent

Builds a structured research plan based on:

original query
clarification answers
assumed scope

4. Search Agent

Performs web research and extracts:

findings
summaries
notable sources
uncertainty signals

5. Writer Agent

Turns the collected structured evidence into a polished long-form report.

6. Email Agent

Formats the final report into HTML and sends it using SendGrid.

7. Research Manager / Orchestrator

Acts as the central control layer for the complete workflow.

⚠️ Why I have not made the full live product openly available

I have not provided unrestricted public access to the fully enabled final version of this app.

Why?

Because this project depends on:

paid OpenAI API calls
multi-step research runs
SendGrid email delivery

If I publicly expose the full version without restrictions, it can very quickly lead to:

uncontrolled API usage
unnecessary cost
email misuse or abuse
poor reliability for genuine users

So instead of leaving the final product fully open, I have chosen to share:

the complete source code
the architecture
the full setup guide
and a screenshot of the final output

This way, anyone genuinely interested can:

understand the project properly
set it up themselves
learn from it
and experience the full workflow responsibly using their own credentials

📸 App Preview

🚀 Want to explore the full project?

If this project interests you and you want the complete experience, the best place to explore it is the GitHub repository.

🔗 GitHub Repository

Deep Research Agent – View Source Code

The repository contains the full project structure, including:

the Gradio frontend
the orchestrator-based research manager
clarification and planning agents
search, writing, and email agents
dependency file
environment template
complete setup instructions
and usage guidance

So if you want to understand how the full system works, the GitHub repo is the right place to go deeper.

⭐ If you find this project useful, here’s how you can support it

If you liked this project or found it useful, there are several ways you can support it:

⭐ Star the repository

A GitHub star helps the project reach more people and tells me that the work is useful.

🍴 Fork the project

Fork it if you want to:

experiment freely
build your own variation
add features
improve prompts and workflows
deploy it under your own setup

📥 Clone and run it locally

If you really want the full experience, clone the repo, configure your own API keys, and run the complete workflow yourself.

That is the best way to understand the architecture and learn from it properly.

🛠️ Build on top of it

You can use this project as a starting point for:

market research assistants
competitor analysis tools
research copilots
technical investigation assistants
literature review agents
domain-specific research workflows

💡 Why I recommend running it yourself

The fully enabled version of this project becomes far more meaningful when you set it up yourself.

Because when you do that, you do not just “use an app.”

You learn:

how multi-agent orchestration works
how clarification improves research quality
how structured planning affects search quality
how evidence can be passed between agents
how long-form report generation can be built in stages
how to manage API keys and email integrations
how to think about cost, abuse prevention, and product design

That is why I would strongly encourage you to clone it, inspect it, modify it, and rebuild parts of it.

The learning value is much greater than simply testing a live demo for a few minutes.

🔍 What you can try after forking the repo

If you decide to fork the project, here are some interesting directions you can explore:

add source cards directly in the UI
export reports as PDF
create research modes like:
- Market Research
- Competitor Analysis
- Technical Deep Dive
- Startup Research
persist session history in a database
add user authentication
track token usage and cost per run
add evaluation and report scoring
improve prompt quality for each agent

The project is intentionally structured in a way that makes these extensions possible.

📚 Please learn from it, not just copy it

If you are reading this as a student, developer, job seeker, or builder, my honest suggestion is:

do not just fork it and re-upload it as your own work
do not just replace the repo name and call it finished
do not just treat it as a shortcut

Instead:

understand the workflow
run it yourself
inspect how the agents communicate
modify the prompts
change the search strategy
add your own improvements
experiment with UI, deployment, evaluation, and safety

If you do that, this project becomes much more valuable than a copied codebase.

A project like this can teach you:

agent orchestration
tool-based routing
structured outputs with Pydantic
environment and secret management
API-driven application design
Gradio deployment
practical product thinking around costs and abuse risks

That learning is worth much more than a blind copy.

💡 Why this project is valuable

This project is valuable because it goes beyond a basic LLM demo and teaches several practical concepts:

how to build a multi-agent workflow
how to use clarification-first reasoning
how to create a structured planner
how to use web research as a tool
how to pass structured outputs between components
how to produce professional long-form reports
how to integrate email delivery
how to think about real-world issues like API cost, security, and public misuse

It is a strong portfolio project for anyone interested in:

AI Engineering
LLM Engineering
Agentic Systems
Applied NLP
Full-stack AI products

🔮 Future Improvements

Some upgrades I would like to add in future versions:

source cards and URLs directly in the UI
report export as Markdown or PDF
research modes such as market research / competitor analysis / technical deep dive
saved research history
authentication
evaluation dashboard
cost tracking per run
richer evidence visualization

🙌 Let’s Connect

If you liked this project, feel free to:

Star the GitHub Repository ⭐
Fork it and build your own version
Connect with me on LinkedIn
Explore more projects on Prismatic Metrics

More AI, agentic workflows, and LLM engineering projects coming soon.