Deep Research

Automated research with real-time streaming and citations

The research command enables automated deep research with real-time streaming, web search, and structured citations using OpenAI or Gemini Deep Research APIs.

Quick Start

praisonai research "AI trends"

Usage

Basic Research

# Default: OpenAI (o4-mini-deep-research)
praisonai research "What are the latest AI trends in 2025?"

# Use Gemini
praisonai research --model deep-research-pro "Your research query"

Expected Output:

🔬 Starting deep research...

╭─ Research Progress ──────────────────────────────────────────────────────────╮
│  📊 Searching for relevant sources...                                        │
│  📚 Analyzing 15 documents...                                                │
│  ✍️ Synthesizing findings...                                                 │
╰──────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────── Report ────────────────────────────────────╮
│ # AI Trends in 2025                                                          │
│                                                                              │
│ ## Key Findings                                                              │
│ 1. Multimodal AI systems are becoming mainstream...                         │
│ 2. Agent-based architectures are gaining adoption...                        │
│                                                                              │
│ ## Citations                                                                 │
│ [1] https://example.com/ai-trends                                           │
│ [2] https://example.com/research-paper                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

With Query Rewrite

# Rewrite query before research
praisonai research --query-rewrite "AI trends"

# Rewrite with search tools
praisonai research --query-rewrite --rewrite-tools "internet_search" "AI trends"

With Custom Tools

# Use custom tools from file (gathers context before deep research)
praisonai research --tools tools.py "Your research query"
praisonai research -t my_tools.py "Your research query"

# Built-in SDK tool (worked before and after #2499)
praisonai research --tools "internet_search" "AI trends"

# praisonai-tools / entry-point plugin — works after #2499
praisonai research --tools "duckduckgo_search,wiki_search" "AI trends"

# Custom local tools.py — works after #2499 (requires the env-var gate)
PRAISONAI_ALLOW_LOCAL_TOOLS=1 praisonai research --tools "my_custom_search" "AI trends"

Which Tool Names Work?

--tools accepts any name resolved by the full resolve_tool() chain:

Order	Source	Notes
1	Local tools.py	Requires PRAISONAI_ALLOW_LOCAL_TOOLS=1
2	Wrapper ToolRegistry	Wrapper-registered tools
3	praisonaiagents.tools (TOOL_MAPPINGS)	SDK built-ins (previous behaviour)
4	praisonai-tools package	Curated tool package
5	Entry-point plugins	praisonai.tools group

Any name shown by praisonai tools list is accepted by --tools. The same resolver chain is used by --rewrite-tools and --expand-tools.

Empty-Segment Behaviour

A trailing or doubled comma no longer emits a spurious warning:

# Both produce identical behaviour — no empty-name warning
praisonai research --tools "internet_search," "AI trends"
praisonai research --tools "internet_search" "AI trends"

Class-Based Tools

Tools from praisonai-tools that are BaseTool subclasses are instantiated automatically — no user action required.

Save Output

# Save output to file (output/research/{query}.md)
praisonai research --save "Your research query"
praisonai research -s "Your research query"

Combine Options

# Full featured research
praisonai research --query-rewrite --tools tools.py --save "Your research query"

# Verbose mode (show debug logs)
praisonai research -v "Your research query"

Supported Models

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

How It Works

1. Query Processing: Optionally rewrites query for better results
2. Context Gathering: Uses tools to gather relevant context
3. Deep Research: Executes multi-step research with web search
4. Synthesis: Combines findings into structured report
5. Citations: Includes source URLs and references

Features

Multi-Provider

Support for OpenAI, Gemini, and LiteLLM providers

Real-time Streaming

Live progress updates with reasoning summaries

Structured Citations

Automatic citation extraction with URLs

Built-in Tools

Web search, code interpreter, MCP, file search

Programmatic Usage

from praisonaiagents import DeepResearchAgent

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

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

# Gemini Deep Research
agent = DeepResearchAgent(
    model="deep-research-pro",  # Auto-detected as Gemini
    
)

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

Best Practices

Use --query-rewrite for complex or ambiguous queries to improve research quality.

Deep research uses multiple API calls and can consume significant tokens. Use --metrics to monitor costs.

Do	Don’t
Be specific about the topic	Use vague single-word queries
Include time constraints (“in 2025”)	Assume recency
Use --save for long reports	Rely on terminal output only
Combine with --tools for context	Skip context gathering

Related

• Deep Research Agent
• Query Rewrite CLI
• Web Search CLI