Deep Research Agent

Automated research using OpenAI or Gemini Deep Research APIs with real-time streaming and citations.

Run provider-native deep research — multi-step web search, reasoning, and cited reports — with the DeepResearchAgent.

from praisonaiagents import DeepResearchAgent

agent = DeepResearchAgent(model="o4-mini-deep-research")

result = agent.research("What are the latest AI trends in 2025?")
print(result.report)
print(f"Citations: {len(result.citations)}")

The Deep Research Agent automates comprehensive research using OpenAI or Gemini Deep Research APIs with real-time streaming, web search, and structured citations.

Agents: 1 — Specialized agent using provider deep research APIs.

Quick Start

1. Simple Usage

   Pick a deep-research model and run a query.

   from praisonaiagents import DeepResearchAgent
   
   agent = DeepResearchAgent(model="o4-mini-deep-research")
   
   result = agent.research("What are the latest AI trends in 2025?")
   print(result.report)
   
2. With Custom Instructions

   Steer the researcher and inspect citations.

   from praisonaiagents import DeepResearchAgent
   
   agent = DeepResearchAgent(
       model="o4-mini-deep-research",
       instructions="Focus on data-rich insights with reliable sources.",
   )
   
   result = agent.research("Economic impact of AI on healthcare")
   for citation in result.citations:
       print(citation.title, citation.url)
   

How It Works

Workflow

1. Receive research query
2. Execute web searches via provider API
3. Perform multi-step reasoning
4. Generate comprehensive report with citations

Setup

pip install praisonaiagents praisonai
export OPENAI_API_KEY="your-key"  # or GEMINI_API_KEY

Run — Python

from praisonaiagents import DeepResearchAgent

agent = DeepResearchAgent(
    model="o4-mini-deep-research",
    
)

result = agent.research("What are the latest AI trends in 2025?")
print(result.report)
print(f"Citations: {len(result.citations)}")

Run — CLI

# Deep research mode
praisonai research "What are the latest AI trends?"

# With save option
praisonai research --save "Research quantum computing advances"

Run — agents.yaml

framework: praisonai
topic: Deep Research
roles:
  researcher:
    role: Deep Research Specialist
    goal: Conduct comprehensive research with citations
    backstory: You are an expert researcher
    llm: o4-mini-deep-research
    tasks:
      research:
        description: Research the latest AI trends in 2025
        expected_output: Comprehensive report with citations

praisonai agents.yaml

Serve API

from praisonaiagents import DeepResearchAgent

agent = DeepResearchAgent(
    model="o4-mini-deep-research",
    
)

# Note: DeepResearchAgent uses .research() method
# For API serving, wrap in standard agent

OpenAI Deep Research

from praisonaiagents import DeepResearchAgent

agent = DeepResearchAgent(
    model="o4-mini-deep-research",  # or "o3-deep-research"
    
)

result = agent.research("What are the latest AI trends?")
print(result.report)
print(f"Citations: {len(result.citations)}")

Gemini Deep Research

from praisonaiagents import DeepResearchAgent

agent = DeepResearchAgent(
    model="deep-research-pro",
    
)

result = agent.research("Research quantum computing advances")
print(result.report)

Features

Multi-Provider

Supports OpenAI, Gemini, and LiteLLM providers.

Real-time Streaming

See reasoning summaries and web searches as they happen.

Structured Citations

Get citations with titles and URLs.

Auto Detection

Provider automatically detected from model name.

Streaming Output

Streaming is enabled by default. You will see:

• 💭 Reasoning summaries
• 🔎 Web search queries
• Final report text

# Streaming is ON by default
result = agent.research("Research topic")

# Disable streaming
result = agent.research("Research topic", stream=False)

Response Structure

result.report           # Full research report
result.citations        # List of citations with URLs
result.web_searches     # Web searches performed
result.reasoning_steps  # Reasoning steps captured
result.interaction_id   # Session ID (for Gemini follow-ups)

Available Models

Provider	Models
OpenAI	o3-deep-research, o4-mini-deep-research
Gemini	deep-research-pro

Configuration Options

agent = DeepResearchAgent(
    name="Researcher",
    model="o4-mini-deep-research",
    instructions="Focus on data-rich insights",
    
    poll_interval=5,      # Gemini polling interval (seconds)
    max_wait_time=3600    # Max research time (seconds)
)

With Custom Instructions

from praisonaiagents import DeepResearchAgent

agent = DeepResearchAgent(
    model="o4-mini-deep-research",
    instructions="""
    You are a professional researcher. Focus on:
    - Data-rich insights with specific figures
    - Reliable sources and citations
    - Clear, structured responses
    """,
    
)

result = agent.research("Economic impact of AI on healthcare")

Accessing Citations

result = agent.research("Research topic")

for citation in result.citations:
    print(f"Title: {citation.title}")
    print(f"URL: {citation.url}")
    print(f"Snippet: {citation.snippet}")
    print("---")

---

Monitor / Verify

praisonai research "test query" --verbose

Cleanup

# No cleanup needed - uses provider APIs

Features Demonstrated

Feature	Implementation
Workflow	Multi-step reasoning with web search
Observability	--verbose flag, streaming output
Tools	Built-in web search via provider API
Resumability	interaction_id for Gemini follow-ups
Structured Output	Citations with titles and URLs

Best Practices

Match the model to the provider

o3-deep-research and o4-mini-deep-research route to OpenAI; deep-research-pro routes to Gemini. The provider is auto-detected from the model name, so pick the one whose API key you have set.

Set a generous max_wait_time for hard questions

Deep research runs multiple search-and-reason cycles. Raise max_wait_time for broad topics so the agent isn’t cut off mid-report.

Always surface the citations

Every result carries citations with titles and URLs. Render them so users can verify claims — that traceability is the whole point of deep research.

Use the plain Research Agent for lightweight queries

For quick, cheap look-ups, a plain Agent with a search tool is faster and cheaper. Reserve DeepResearchAgent for questions that genuinely need multi-step reasoning.

Related

A lighter search-tool research recipe using a plain Agent.

Single-pass web search for quick answers.