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
- Simple Usage
Pick a deep-research model and run a query.
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) - With Custom Instructions
Steer the researcher and inspect citations.
python 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
- Receive research query
- Execute web searches via provider API
- Perform multi-step reasoning
- Generate comprehensive report with citations
Setup
pip install praisonaiagents praisonai
export OPENAI_API_KEY="your-key" # or GEMINI_API_KEYRun — 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 citationspraisonai agents.yamlServe API
from praisonaiagents import DeepResearchAgent
agent = DeepResearchAgent(
model="o4-mini-deep-research",
)
# Note: DeepResearchAgent uses .research() method
# For API serving, wrap in standard agentOpenAI 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
Supports OpenAI, Gemini, and LiteLLM providers.
Real-time StreamingSee reasoning summaries and web searches as they happen.
Structured CitationsGet citations with titles and URLs.
Auto DetectionProvider 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" --verboseCleanup
# No cleanup needed - uses provider APIsFeatures 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.