---

name: rag-query description: "Use and troubleshoot DeepSearcher query, retrieve, and RAG agent workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

DeepSearcher RAG Query

Use this sub-skill when a task is about asking questions over already-loaded DeepSearcher data, retrieving references, choosing or instantiating RAG agents, tuning iteration/token tradeoffs, or diagnosing query-time failures.

Do not use this sub-skill for ingestion, provider configuration, CLI/service operation, or benchmark evaluation. Route those to the sibling sub-skills listed below.

Start Here

1. Confirm that an environment has DeepSearcher installed and that provider/vector DB setup and data loading were already handled.
2. Pick the API surface:
   • Global convenience API: deepsearcher.online_query.query, retrieve, naive_retrieve, or naive_rag_query.
   • Manual agents: DeepSearch, ChainOfRAG, NaiveRAG, or RAGRouter when you already have llm, embedding_model, and vector_db objects.
3. Choose the lowest-cost agent that can answer the request:
   • NaiveRAG for cheap direct retrieval plus one summarization call.
   • DeepSearch for broad reports or surveys where sub-query expansion and reflection are useful.
   • ChainOfRAG for factual or multi-hop questions where intermediate answers and support-doc filtering matter.
   • RAGRouter when you want an LLM to select among multiple RAG agents from descriptions.
4. Inspect returned references before trusting an answer. Query APIs return RetrievalResult objects whose text, reference, metadata, and score fields explain what was used.

Reference Map

• API reference: signatures, return shapes, constructors, RetrievalResult, and router APIs.
• Workflows: query/retrieve patterns, agent selection, token controls, and no-result handling.
• Agent behavior: DeepSearch, ChainOfRAG, NaiveRAG, RAGRouter, CollectionRouter, and wider_text behavior.
• Troubleshooting: parse failures, no results, collection routing, wrapper caveats, token issues, notebook async issues, and relevant compatibility warnings.
• Mock smoke helper: no-network return-shape smoke checks for NaiveRAG and DeepSearch using mock LLM, embedding, and vector DB objects.

Safe Smoke Check

Run the bundled helper only in an environment with DeepSearcher installed. It uses in-memory mocks, performs no network calls, and does not require credentials:

python scripts/mock_rag_smoke.py --agent naive --format json
python scripts/mock_rag_smoke.py --agent deep-search --max-iter 1

Route Elsewhere

• Data loading, chunking, file/web sources, and collection creation: use data-ingestion.
• Provider credentials, model classes, embedding dimensions, and vector DB connection setup: use provider-configuration.
• Console script behavior, CLI help, service deployment, and API server usage: use cli-and-service.
• Benchmark metrics, recall/error/token plots, and evaluation scripts: use evaluation.