Praison AI

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

bash
praisonai research "AI trends"
Deep research example

Usage

Basic Research

bash
# 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

bash
# 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

bash
# 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:

Diagram

📝 –tools a,b,c

🔍 resolve_tool()

📁 Local tools.py

📦 Wrapper ToolRegistry

🧰 praisonaiagents.tools

🛠️ praisonai-tools

🔌 Entry-point plugins

✅ Tool used

OrderSourceNotes
1Local tools.pyRequires PRAISONAI_ALLOW_LOCAL_TOOLS=1
2Wrapper ToolRegistryWrapper-registered tools
3praisonaiagents.tools (TOOL_MAPPINGS)SDK built-ins (previous behaviour)
4praisonai-tools packageCurated tool package
5Entry-point pluginspraisonai.tools group

Empty-Segment Behaviour

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

bash
# 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

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

Combine Options

bash
# 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

ProviderModels
OpenAIo4-mini-deep-research, o3-deep-research
Geminideep-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
Diagram

Yes

No

Query

Rewrite?

QueryRewriterAgent

Context Gathering

Deep Research API

Web Search

Analysis

Report + Citations

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

python
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

DoDon’t
Be specific about the topicUse vague single-word queries
Include time constraints (“in 2025”)Assume recency
Use --save for long reportsRely on terminal output only
Combine with --tools for contextSkip context gathering

Related