> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval-augmented generation

> Prepare retrieval settings, inspect document indexes and chunks, and separate those checks from live knowledge-grounded answers.

Retrieval-augmented generation, or RAG, is intended to bring relevant source material into an agent's response. Prepare clear documents and a small set of questions with known answers before adjusting retrieval settings.

<Note>
  The API exposes index, chunk, and query operations. An index marked successful or a configured embedding-model identifier does not establish semantic vector retrieval or a live knowledge-grounded answer. Conversation execution remains [gated](/agents-platform/overview#current-availability).
</Note>

## Prepare and inspect the source

<Steps>
  <Step title="Read the stored document">
    Follow [document management](/agents-platform/configure/knowledge-base/manage-documents). Check headings, current facts, and source ownership before creating an index. Empty or incomplete source content cannot provide useful answers.
  </Step>

  <Step title="Review index state and chunks">
    Use [Get document RAG indexes](/api-reference/agents-platform/get-document-rag-indexes) to inspect the index state. [Create document RAG index](/api-reference/agents-platform/create-document-rag-index) requires a model selection and write access.

    Inspect [document chunks](/api-reference/agents-platform/list-rag-chunks-for-document). Check that important instructions and their qualifications remain understandable. Do not interpret the index status as proof that an embedding provider ran.
  </Step>

  <Step title="Review the agent attachment">
    Attach the source to an existing agent through `conversation_config.agent.prompt.knowledge_base`. Each locator uses `type`, `name`, `id`, and `usage_mode`, whose values are `auto` or `prompt`. Initial agent creation rejects nonempty knowledge attachments.
  </Step>

  <Step title="Prepare a query review">
    The [Query agent knowledge base](/api-reference/agents-platform/query-agent-knowledge-base) reference describes a separate query operation. Review any returned material against the known answer and source text. A useful result from this operation does not demonstrate retrieval inside a live conversation.
  </Step>
</Steps>

## Retrieval configuration

These fields belong to `conversation_config.agent.prompt.rag`. Save them in a complete [server draft](/agents-platform/deploy/versioning) and inspect the read-back.

| Field | Authoring constraint |
| - | - |
| `enabled` | Boolean; defaults to `false`. |
| `embedding_model` | A supported embedding-model identifier. |
| `max_vector_distance` | Greater than 0 and less than 1; default 0.6. |
| `max_documents_length` | Greater than 0 and less than 10,000,000; default 50,000. |
| `max_retrieved_rag_chunks_count` | Integer from 1 to 20; default 20. |
| `num_candidates` | Optional integer from 1 to 10,000. |
| `query_rewrite_prompt_override` | Optional text from 1 to 1,000 characters. |

These are authoring limits. A specific query operation may impose narrower limits, and a schema field does not establish that every retrieval stage uses it. Avoid tuning values until you can inspect the actual returned material.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does enabling RAG ensure an answer cites the source?" id="faq-rag-citations">
    No. A configuration flag does not prove retrieval, answer grounding, or citation behavior. Keep those as separate checks in the eventual conversation review.
  </Accordion>

  <Accordion title="What should the review questions cover?" id="faq-rag-review-questions">
    Include an exact factual question, a paraphrase, a question spanning two sections, and a question the source cannot answer. Record which passage supports each expected answer.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.