Agentic RAG & Deep Research
Relevant source files
The following files were used as context for generating this wiki page:
Agentic Retrieval-Augmented Generation (RAG) and Deep Research represent the advanced reasoning capabilities of the Onyx platform. Unlike standard RAG, which performs a single retrieval step to answer a query, the Agentic RAG system uses an iterative loop of reasoning, tool usage (internal and web search), and information synthesis to handle complex, multi-step research tasks. Deep Research specifically utilizes a multi-layered agent architecture to plan, execute, and consolidate thorough investigations into comprehensive reports.
Sources: backend/onyx/chat/README.md, backend/onyx/prompts/deep_research/orchestration_layer.py:46-60
Multi-Agent Architecture
The Deep Research system is structured as a hierarchical multi-agent orchestration. This design separates high-level planning from low-level execution, allowing the system to pursue multiple research directions simultaneously.
Hierarchical Roles
The system utilizes three primary agent roles defined by specific prompt sets:
| Agent Role | Responsibility | Key Tools |
|---|---|---|
| Clarification Agent | Assesses if the user query is detailed enough or requires follow-up questions. | generate_plan |
| Orchestrator Agent | Generates a high-level research plan and delegates sub-tasks to research agents. | research_agent, generate_report, think |
| Research Agent | Conducts specific, low-level investigation on a single topic delegated by the orchestrator. | internal_search, web_search, open_url, think |
Sources: backend/onyx/prompts/deep_research/orchestration_layer.py:8-23, backend/onyx/prompts/deep_research/orchestration_layer.py:73-100, backend/onyx/prompts/deep_research/research_agent.py:9-30
Orchestration Flow
The orchestration layer manages the overall lifecycle of a research task. It starts by breaking down a query into a research plan consisting of 6 or fewer individual steps.
The Orchestrator Agent is encouraged to call the Research Agent in parallel for independent tasks, with a strict limit of 3 parallel calls to maintain system stability.
Sources: backend/onyx/prompts/deep_research/orchestration_layer.py:38-44, backend/onyx/prompts/deep_research/orchestration_layer.py:93-95
The Research Loop
The Research Agent operates in iterative cycles (limited to a maximum of 8 cycles). In each cycle, it performs searches, reads content, and then uses a mandatory "think" step to analyze results and plan the next search.
Agentic Decision Making
The research_agent prompt enforces a strict "tool-only" output mode, preventing the agent from generating conversational tokens during the research phase. It must use the think tool after every set of searches and before generating the final research report.
Search and Retrieval Logic
Onyx utilizes multiple search prompts to refine the RAG process:
- Semantic Rephrasing: Reformulates user messages into self-contained natural language queries.
- Keyword Rephrasing: Generates optimized keyword-only queries (max 3) for traditional search engines.
- Document Selection: A prompt-based filter where the LLM selects the most relevant sections from a provided list (max sections limit applies).
Context Management and Representation
To ensure high accuracy, Onyx handles retrieved documents and agent history with specific formatting rules designed to minimize hallucinations.
Document Representation
Retrieved documents are represented to the LLM as structured JSON. This includes a numerical document ID (e.g., [1], [2]) which allows the LLM to provide reliable inline citations.
Sources: backend/onyx/chat/README.md, backend/onyx/prompts/deep_research/orchestration_layer.py:129-140
Context Reminders
Instruction follow-rate is improved by adding "reminders" as the final user message in the context window. If a search tool was utilized, a citation reminder is automatically appended to ensure the agent grounds its response in the retrieved sources.
Sources: backend/onyx/chat/README.md
Reporting and Synthesis
The final stage of the deep research process involves synthesizing gathered information into a structured report.
Sub-Agent Reports
When a research_agent finishes its task, a research_sub_agent prompt is used to organize findings. This report focuses strictly on facts, removes duplicates, and flags contradictory information. It is intended for consumption by the orchestrator, not the end user.
Sources: backend/onyx/prompts/deep_research/research_agent.py:37-52
Final User Report
The final_answer_generator produces the end-user-facing document. It is instructed to:
- Structure Logically: Use Markdown headers and formatted sections.
- Be Thorough: Responses are encouraged to be several pages long.
- Inline Citations: Use the
[n]format strictly based on source document IDs. - Avoid Preambles: Skip lengthy introductions and get straight to the facts.
Sources: backend/onyx/prompts/deep_research/orchestration_layer.py:110-126
Implementation Details
The backend execution relies on Celery workers to handle the asynchronous nature of deep research tasks.
| Component | Logic |
|---|---|
| Primary Worker | Coordinates core tasks and model updates. |
| Docfetching Worker | Fetches external documents for indexing (supports RAG). |
| LLM Loop | Manages the "Turn" logic, including context truncation and tool execution. |
| LLM Step | A single inference call that handles token-by-token streaming for reasoning and answers. |
Sources: AGENTS.md, backend/onyx/chat/README.md
The system further implements "reasoning model variants" of prompts (e.g., ORCHESTRATOR_PROMPT_REASONING) to leverage models with native chain-of-thought capabilities, encouraging deeper investigation of knowledge gaps before concluding the research.
Sources: backend/onyx/prompts/deep_research/orchestration_layer.py:143-176