Agentic RAG Reasoning Loop
Relevant source files
The following files were used as context for generating this wiki page:
The Agentic RAG Reasoning Loop is a multi-agent orchestration framework designed to answer complex clinical questions by decomposing them into researchable tasks. Built on the DeepAgents harness, the system coordinates specialized subagents through a plan–research–verify cycle to ensure that medical answers are grounded in retrieved evidence and verified for sufficiency.
This reasoning loop moves beyond simple one-shot retrieval by implementing a deterministic sufficiency check. If the gathered evidence is deemed incomplete, the loop triggers targeted follow-up research rounds, converging on missing information until a high-confidence clinical answer can be synthesized.
Sources: README.md:144-158, am_diag/agents/prompts.py:8-23
Core Architecture
The loop is managed by an Orchestrator that delegates tasks to three primary subagents. The process is iterative and gated by a numerical sufficiency threshold.
Agent Roles and Responsibilities
| Agent | Responsibility | Key Output |
|---|---|---|
| Planner | Decomposes complex clinical vignettes into focused sub-questions and maps them to retrieval recipes. | AgentPlan |
| Researcher | Executes parallel searches across multiple retrieval tools (entity, relation, chunk, community) to gather evidence. | EvidenceItem[] |
| Verifier | Assesses the gathered evidence against the original question for coverage and depth. | SufficientContext |
| Orchestrator | Coordinates the execution flow, manages iterations, and performs final synthesis. | ClinicalAnswer |
Sources: am_diag/agents/prompts.py:8-58, README.md:144-153
Logical Flow Diagram
The following diagram illustrates the iterative nature of the reasoning loop, highlighting the parallel research phase and the verification gate.
The diagram shows the transition from decomposition to parallel evidence gathering, followed by a sufficiency evaluation that can trigger additional planning cycles.
Sources: README.md:144-158, am_diag/agents/prompts.py:8-23
Subagent Details
The Planner
The Planner acts as the initial architect for the inquiry. It analyzes the input question and generates an AgentPlan, which consists of multiple SubQuestion objects. Each sub-question is assigned a specific "recipe" for retrieval, such as hybrid_rrf for general search or text2cypher for structured graph queries.
Sources: am_diag/agents/prompts.py:25-37, am_diag/common/data_models/agent.py
The Researcher
Researchers are spawned in parallel to handle specific sub-questions. They utilize a suite of tools to interact with the Neo4j knowledge graph and vector stores. Their primary goal is to return distilled EvidenceItems with relevance scores and citations, avoiding the fabrication of clinical facts.
Sources: am_diag/agents/prompts.py:39-50, README.md:150-151
The Verifier
The Verifier performs a critical quality control function. It evaluates the current evidence pool against the following metrics:
- Coverage Score (0-10): Completeness of the answer relative to the question.
- Evidence Depth (0-10): Level of clinical detail provided.
- Missing Pieces: Explicit identification of gaps.
- Targeted Follow-ups: New sub-questions generated to address identified gaps.
Sources: am_diag/agents/prompts.py:52-64, am_diag/common/data_models/agent.py
Data Structures
The loop relies on standardized data models to pass state between agents and the final output.
ClinicalAnswer Model
The final output of the loop is a structured ClinicalAnswer which provides transparency into the reasoning process.
| Field | Type | Description |
|---|---|---|
answer | string | The grounded clinical response. |
sources | list | Citations linked to specific claims. |
confidence | float | 0.0 to 1.0 score of internal confidence. |
answerable | bool | Flag indicating if enough evidence was found. |
caveats | string | Clinical limitations or warnings. |
Sources: am_diag/agents/prompts.py:66-77, am_diag/common/data_models/agent.py
Sequence of Operations
The sequence diagram below shows the interactions between the Orchestrator and subagents during a typical reasoning cycle.
This diagram depicts the communication flow where the Orchestrator maintains state and determines the next step based on the Verifier's feedback.
Sources: am_diag/agents/prompts.py:8-23, README.md:154-158
Conclusion
The Agentic RAG Reasoning Loop provides a robust mechanism for clinical decision support by treating medical inquiry as a multi-step research process. By separating planning, research, and verification, the system minimizes hallucinations and ensures that final answers are strictly grounded in the knowledge graph and medical literature, with clear citations and confidence assessments.