Deep Researcher (User-Guided)
A four-agent deterministic research pipeline where Python code controls all execution flow — delivering predictable, traceable research automation from query to emailed report in a fixed sequence of steps.
4
Specialized Agents
5
Parallel Searches / Run
1000+
Word Structured Report
The Problem
Autonomous agents are powerful but hard to predict
Fully agentic systems hand control to the LLM — which makes them adaptive but also unpredictable. For many research tasks, that flexibility isn't needed. What's needed is a system that reliably executes the same well-tested sequence every time: plan the searches, run them in parallel, synthesise the results, deliver the report. A workflow architecture delivers exactly that — deterministic, debuggable, and straightforward to extend — without the complexity overhead of autonomous decision-making.
The Solution
A fixed pipeline where Python owns the control flow
Deep Researcher — User-Guided is a linear four-agent pipeline orchestrated entirely by Python code via the ResearchManager class. The user enters a query, clicks Run, and the system executes a fixed sequence: PlannerAgent generates 5 targeted search queries, SearchAgent fans all five out in parallel, WriterAgent synthesises the results into a 1,000+ word structured report, and EmailAgent delivers it via SendGrid. Every stage always runs, in order, exactly once. There is no dynamic branching, no quality evaluation loop, and no LLM making decisions about what happens next.
Key Outcome
A fully automated research-to-email pipeline that executes the same reliable sequence on every run — producing a 1,000+ word structured report with zero manual intervention, built alongside the Fully Agentic version to directly compare workflow vs. autonomous architectures for the same task.
Technical Deep Dive
Architecture & Design
Step 1
Plan
ResearchManager.plan_searches() calls PlannerAgent with the user query. PlannerAgent returns a WebSearchPlan containing 5 targeted search queries, each with a reason explaining its relevance. Output is validated against a Pydantic schema before being passed to the next step.
Step 2
Search
ResearchManager.perform_searches() fans out all 5 queries in parallel using asyncio.create_task(). Each query spawns an independent SearchAgent instance with WebSearchTool set to tool_choice='required' — ensuring the web search is always executed. Each agent returns a 300-word summary of its findings.
Step 3
Write
ResearchManager.write_report() passes the original query and all accumulated search summaries to WriterAgent. The agent produces an outline then writes a full structured markdown report targeting 1,000+ words across 5–10 sections. Output is a validated ReportData Pydantic model containing short_summary, markdown_report, and follow_up_questions.
Step 4
ResearchManager.send_email() passes the markdown report to EmailAgent. The agent converts it to styled HTML — max 700px wide, Georgia serif font, proper heading hierarchy — and delivers it via the send_email function_tool backed by the SendGrid API. Email delivery runs automatically on every pipeline execution.
Key Design Decisions
Python owns the control flow — not the LLM
The ResearchManager class orchestrates all agents via explicit Runner.run() calls. Results are passed between stages as Python variables — there is no agent-to-agent communication, no handoffs, and no LLM making decisions about what happens next. This makes the pipeline deterministic, easy to debug, and straightforward to extend with new steps.
Parallel search execution via asyncio
All 5 search queries run concurrently using asyncio.create_task(), reducing total search time to the duration of the slowest single search rather than the sum of all five. Each SearchAgent instance is independent — a failed search does not block the others.
Predictability as a feature — not a limitation
The workflow system was deliberately built without adaptive stopping, quality evaluation, or query scoping — not because these are impossible, but to establish a clean baseline. Every design tradeoff in this system is addressed explicitly in the Fully Agentic version, making the two systems a direct architectural comparison.
Tech Stack
| Technology | Purpose |
|---|---|
| OpenAI Agents SDK | Agent definitions and Runner.run() calls |
| GPT-4o-mini | LLM backbone for all 4 agents |
| WebSearchTool | Real-time web search within SearchAgent |
| Gradio | Single-page UI with query input and streaming report output |
| SendGrid | HTML email delivery of completed reports |
| Pydantic | Structured output validation for WebSearchPlan and ReportData |
| asyncio | Parallel search execution via asyncio.create_task() |
| Python | Core language and pipeline orchestration |
Results & Metrics
What the system delivers
4
Specialized Agents
Planner, Search, Writer, and Email — each with a single well-defined responsibility in the pipeline
5
Parallel Searches / Run
All 5 queries execute concurrently via asyncio — total search time equals the slowest single search
1000+
Word Structured Report
Executive summary, full markdown report, and follow-up questions delivered directly to email
Deterministic execution
Every run follows the exact same sequence — plan, search, write, email. No branching, no skipped steps, no LLM-driven surprises. The same query always produces a structurally identical pipeline execution.
Easy to debug and extend
Because control flow lives in Python rather than LLM reasoning, every stage can be inspected, logged, and modified independently. Adding a new pipeline step is as simple as writing a new ResearchManager method.
Zero-touch delivery
From query submission to emailed report, the pipeline requires no manual intervention. The user enters a topic, the system handles everything else — research, synthesis, formatting, and delivery.
Clean architectural baseline
Built alongside the Fully Agentic version as a direct architectural comparison — isolating the impact of adaptive stopping, quality evaluation, and human-in-the-loop scoping by removing all three from this system.
Agent Roster
| Agent | Responsibility |
|---|---|
| PlannerAgent | Generates 5 targeted web search queries from the user query |
| SearchAgent | Performs a single web search; returns a 300-word summary |
| WriterAgent | Synthesises all search results into a structured 1,000+ word markdown report |
| EmailAgent | Converts markdown to styled HTML; delivers via SendGrid |