Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IconDean/research-agent/llms.txt

Use this file to discover all available pages before exploring further.

Every report produced by the Deep Research Agent follows a fixed Markdown structure defined by the SYNTHESIS_PROMPT. The structure is not optional or configurable — Gemini receives the prompt with explicit section headings and formatting rules, and the ReportGenerator passes the output directly to stdout. This consistency means downstream tools, renderers, and readers can always expect the same sections in the same order, with citations that are guaranteed to resolve against the numbered Sources list at the end.

​
Report Template

The complete report structure looks like this: 
# [A Compelling Title for the Report]

## Methodology
- **Initial Question:** The original question submitted by the user
- **Searches Conducted:** N search queries issued across both research rounds
- **Sources Analyzed:** N fetched out of N total candidates
- **Blocked Sources:** N sources blocked due to low credibility (score < 0.5)

## Executive Summary
A concise 3–5 sentence summary of the key findings across all sources.

## Main Findings

### Theme Name One
Detailed narrative with inline citations [1] [2]. Findings are grouped by
theme, not by the sub-queries that uncovered them.

### Theme Name Two
Further findings with citations [3]. Sub-headings use ### (H3) level so
they nest cleanly under the H2 Main Findings section.

## Conflicting Information
Contradictions or disagreements found across sources, referencing specific
claims by citation number. If no conflicts were found, this section reads:
"No significant conflicting information was found."

## Confidence Assessment
- **Confidence Level:** Low | Medium | High
- **Rationale:** Brief explanation referencing source quality (credibility
  scores), coverage breadth, and any gaps that remain after both research
  rounds.

## Sources
[1]. [Source Title](https://example.com/page) (Credibility Score: 0.85)
[2]. [Another Source](https://arxiv.org/abs/...) (Credibility Score: 0.91)
[3]. [Third Source](https://reuters.com/...) (Credibility Score: 0.78)

​
Section-by-Section Reference

1

Report Title

The # H1 heading is generated by Gemini as a compelling, descriptive title for the specific report — it is not the raw user question. The title is intended to read like a published article headline that summarises the main finding or framing of the research.
2

Methodology

The Methodology section documents exactly how the research was conducted so readers can assess the basis for the findings. It contains four bullet points:
BulletSource
Initial QuestionThe verbatim question string passed to agent.research()
Searches ConductedLength of context.queries_made at synthesis time
Sources AnalyzedCount of URLs in context.sources_fetched / total in context.source_metadata
Blocked SourcesCount of URLs in source_metadata whose score was ≤ MIN_CREDIBILITY_SCORE (0.5)
The “N fetched out of N total candidates” phrasing makes the filtering ratio immediately visible. A report that fetched 8 out of 30 candidates signals much heavier filtering than one that fetched 18 out of 20.
3

Executive Summary

A self-contained 3–5 sentence paragraph summarising the most important findings. It is written to be readable in isolation — someone who reads only the Executive Summary should understand the core answer to the research question. It contains no inline citations; those appear in Main Findings.
4

Main Findings

The most detailed section. Findings are organised into thematic sub-sections using ### Theme Name (H3) headings. Critically, themes are defined by topic, not by the sub-queries that produced the evidence — material from multiple searches may be merged under one theme, and a single search result may contribute to several themes.Inline citations appear as [1], [2], etc. throughout the narrative. Each citation number corresponds exactly to the entry at that position in the Sources list at the end of the report.
Inline citation numbers [n] map one-to-one to the numbered entries in the Sources section. [1] always refers to the first source in the list, [2] to the second, and so on. The numbering is assigned during synthesis and is consistent across the entire document — the same URL always carries the same citation number wherever it appears.
5

Conflicting Information

This section explicitly addresses disagreements between sources. If sources contradict each other on a material point, the contradiction is described here with citation numbers for both sides. If no meaningful conflicts exist across the fetched sources, the section contains exactly:
No significant conflicting information was found.
The section is always present in the output — it is never omitted — so readers know the agent actively looked for conflicts rather than overlooking them.
6

Confidence Assessment

The confidence assessment provides a structured quality rating for the report as a whole. It contains two fields:
  • Confidence Level — one of Low, Medium, or High
  • Rationale — a brief explanation citing specific factors: the credibility scores of the sources used, the breadth of coverage across sub-queries, and any gaps that remained unresolved after the second research round
The confidence level is determined by Gemini during synthesis, not calculated programmatically. It reflects a holistic judgement over source quality (visible via scores), topic coverage, and the presence of unresolved gaps recorded in context.gaps.
7

Sources

A numbered Markdown list of every source whose content was used in the report. Each entry follows the format:
[N]. [Source Title](URL) (Credibility Score: X.XX)
The credibility score shown is the value computed by score_source at discovery time and stored in ResearchContext.source_metadata. Sources that were discovered but blocked (score ≤ 0.5) do not appear in this list — they are counted in the Methodology section instead.

​
CLI Output Behaviour

When run from the command line, the agent separates progress output from report output so they can be handled independently by shell pipelines.

Progress Events (stderr)

During research, status events are written to stderr so they do not contaminate the report output on stdout. The three event types are:
  • 🔍 Searching — a search_web tool call was issued
  • 📄 Fetching — a fetch_page call succeeded and content was stored
  • 🚫 Blocked — a fetch_page call was rejected due to a low credibility score

Report Output (stdout)

The final report is written to stdout, preceded by a 60-character = separator line so it is easy to locate in combined output:
============================================================
# How Transformers Changed NLP: A Deep Research Report
...
Redirecting stdout captures only the report; redirecting stderr captures only the progress log.

​
Example CLI session

$ python main.py "How do transformer models handle long-context inputs?" \
    2>progress.log >report.md

# progress.log receives lines like:
# 🔍 Searching: transformer long-context attention mechanisms
# 📄 Fetching: https://arxiv.org/abs/2307.03170
# 🚫 Blocked: https://twitter.com/... (score: 0.42)
# 📄 Fetching: https://huggingface.co/blog/...

# report.md receives:
# ============================================================
# # Managing Long Contexts in Transformer Models: Techniques and Trade-offs
# ## Methodology
# ...
Piping stderr and stdout to separate files is the recommended pattern for automated use. The separator line (= × 60) in stdout makes it straightforward to strip with sed or awk if you want only the Markdown content.

Build docs developers (and LLMs) love

Get started for freeTalk to us