> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai research "AI trends" ``` ![Deep research example](https://mintcdn.com/praisonai/pFBcVNzCyPC2mUmz/cli/deep-research-deep-research.gif?s=a1721405a0de4dfa0aef70c66e283003) ## Usage ### Basic Research ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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: ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR Names["📝 --tools a,b,c"] --> Resolver["🔍 resolve_tool()"] Resolver --> Local["📁 Local tools.py"] Resolver --> Wrapper["📦 Wrapper ToolRegistry"] Resolver --> Builtins["🧰 praisonaiagents.tools"] Resolver --> Praisonai["🛠️ praisonai-tools"] Resolver --> Plugins["🔌 Entry-point plugins"] Local --> Done["✅ Tool used"] Wrapper --> Done Builtins --> Done Praisonai --> Done Plugins --> Done classDef input fill:#6366F1,stroke:#7C90A0,color:#fff classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff classDef source fill:#189AB4,stroke:#7C90A0,color:#fff classDef result fill:#10B981,stroke:#7C90A0,color:#fff class Names input class Resolver process class Local,Wrapper,Builtins,Praisonai,Plugins source class Done result ``` | 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 | > [!NOTE] > > 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Save output to file (output/research/{query}.md) praisonai research --save "Your research query" praisonai research -s "Your research query" ``` ### Combine Options ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} flowchart LR A[Query] --> B{Rewrite?} B -->|Yes| C[QueryRewriterAgent] B -->|No| D[Context Gathering] C --> D D --> E[Deep Research API] E --> F[Web Search] F --> G[Analysis] G --> H[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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 > [!TIP] > > Use `--query-rewrite` for complex or ambiguous queries to improve research quality. > [!WARNING] > > 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](https://praison.ai/docs/agents/deep-research.md) * [Query Rewrite CLI](https://praison.ai/docs/cli/query-rewrite.md) * [Web Search CLI](https://praison.ai/docs/cli/web-search.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.