Execute RAG Endpoint

**RAG**

Retrieval-Augmented Generation (RAG) combines a large language model with your organization's own knowledge base to deliver accurate, context-aware responses grounded in the organization specific documents.

Catalyst QuickML is equipped with RAG system under Generative AI services, to deliver responses grounded in the organization's own documents with ground truth citations of the documents for traceability. Multiple RAG modes have been introduced each designed for a different use case. Every mode exposes its own dedicated parameters, giving you absolute control over how the RAG system generates responses.

Let's take a quick look at the RAG modes:   
* Response Generation : Response Generation is the standard RAG mode where model generates response grounded with relevant chunks of information from the documents   
* Agentic RAG : An agent layer on top of RAG that can reason over complex queries, decompose them into sub-queries, and handle conversational interactions
* Document Search : It is retrieval-only task, doesn't generate a response but returns the most relevant chunks of content from the documents.

**Execute RAG Endpoint**

Create a RAG endpoint from a saved RAG configuration. The RAG mode, selected large language model, respective parameters, and document store are captured from the saved configuration at the time of endpoint creation. It cannot be overridden through the SDK.

The SDK method you call depends on the RAG mode the endpoint was configured with:

<table style="width:100%; border: 1px solid #ccc; border-collapse: collapse; font: 15px/24px zoho-puvi-regular;">
  <thead>
    <tr style="background-color: #f2f2f2;">
      <th style="border: 1px solid #ccc; padding: 10px; text-align: left; font: 15px/24px zoho-puvi-semibold;">RAG mode</th>
      <th style="border: 1px solid #ccc; padding: 10px; text-align: left; font: 15px/24px zoho-puvi-semibold;">SDK method</th>
    </tr>
  </thead>
  <tbody>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">Response Generation</td><td style="border: 1px solid #ccc; padding: 10px;">generate_rag_response(endpoint_key, prompt)</td></tr>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">Document Search</td><td style="border: 1px solid #ccc; padding: 10px;">search_documents(endpoint_key, query)</td></tr>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">Agentic RAG (without history)</td><td style="border: 1px solid #ccc; padding: 10px;">ask_rag_agent(endpoint_key, prompt)</td></tr>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">Agentic RAG (with history)</td><td style="border: 1px solid #ccc; padding: 10px;">converse_with_rag_agent(endpoint_key, prompt, conversation_id)</td></tr>
  </tbody>
</table>
<br>

Note:

1. You will need to have the RAG endpoint created and published in your project using the Catalyst console, before you execute the code snippets below.

2. QuickML is currently available to Catalyst users accessing from the US, IN, and EU data centers

### a. Generate a RAG Response

The  `generate_rag_response(endpoint_key, prompt)`  method sends a question to a published RAG endpoint. The service retrieves the most relevant content from the endpoint's document store and returns a summarised response grounded in that content.

**Parameters used**

**Sample Code Snippet**   
# Create a QuickML instance.
quickml = app.quick_ml()

# Generate RAG Response
    # Replace with your endpoint key copied from the Catalyst console.
    endpoint_key = "<ENDPOINT_KEY>"

# Enter your question.
    prompt = "<YOUR_PROMPT>"

response = quickml.generate_rag_response (
    endpoint_key,
    prompt
    )

print(response)

The syntax of the  response received  is shown below:

{
  "status": "success",
  "result": [
    {
      "content": "The answer, grounded in the retrieved documents.",
      "citations": [
        {
          "document_name": "employee_handbook_2026.pdf",
          "document_id": "doc_10294",
          "chunk_id": "chunk_58",
          "page_number": 14,
          "text": "The excerpt of source text the answer was grounded in.",
          "score": 0.91
        }
      ],
      "usage": {
        "input_tokens": 1420,
        "output_tokens": 112,
        "total_tokens": 1532
      }
    }
  ]
}

Use this method for document-based question answering, summarization, and support assistants

### b. Search Documents

The  `search_documents(endpoint_key, query)`  method performs retrieval only. It returns the chunks of content from the document store that most closely match the query, without generating a response.

**Parameters used**

**Sample Code Snippet**   
# Create a QuickML instance.
quickml = app.quick_ml()

# Search Documents

# Replace with your endpoint key copied from the Catalyst console.
    endpoint_key = "<ENDPOINT_KEY>"

# Enter your search query.
    query = "<SEARCH_QUERY>"

response = quickml.search_documents (
    endpoint_key,
    query
    )

print(response)

The syntax of the  response received  is shown below:

{
  "status": "success",
  "result": [
    {
      "chunk_id": "chunk_58",
      "document_name": "employee_handbook_2026.pdf",
      "document_id": "doc_10294",
      "page_number": 14,
      "text": "The retrieved chunk of content that matched the query.",
      "score": 0.91
    },
    {
      "chunk_id": "chunk_59",
      "document_name": "employee_handbook_2026.pdf",
      "document_id": "doc_10294",
      "page_number": 15,
      "text": "The next most relevant chunk of content.",
      "score": 0.84
    }
  ]
}

Use this method when your application needs the raw retrieved passages for downstream processing, ranking, or custom rendering

### c. Ask a RAG Agent

The  `ask_rag_agent(endpoint_key, prompt)`  method sends a single message to an Agentic RAG endpoint. The agent can decompose complex queries into sub-queries, refine them, and perform multi-step reasoning over the document store before returning a response.

Note : Each call is independent. No conversation context is retained.

**Parameters used**

**Sample Code Snippet**   
# Create a QuickML instance.
quickml = app.quick_ml()

# Ask RAG Agent

# Replace with your endpoint key copied from the Catalyst console.
    endpoint_key = "<ENDPOINT_KEY>"

# Enter your prompt.
    prompt = "<YOUR_PROMPT>"

response = quickml.ask_rag_agent (
     endpoint_key,
     prompt
    )
    print(response)

The syntax of the  response  received is shown below:

{
  "status": "success",
  "result": [
    {
      "content": "The agent's answer after reasoning over the document store.",
      "sub_queries": [
        "First decomposed sub-query the agent generated.",
        "Second decomposed sub-query the agent generated."
      ],
      "citations": [
        {
          "document_name": "policy_v3.pdf",
          "document_id": "doc_10877",
          "chunk_id": "chunk_12",
          "page_number": 3,
          "text": "The excerpt of source text the answer was grounded in.",
          "score": 0.88
        }
      ],
      "usage": {
        "input_tokens": 3180,
        "output_tokens": 204,
        "total_tokens": 3384
      }
    }
  ]
}

### d.  Converse with a RAG Agent

The  `converse_with_rag_agent(endpoint_key, prompt, conversation_id)`  method sends a message to an Agentic RAG endpoint while retaining the context of previous turns. Use this method to build multi-turn assistants that answer follow-up questions from the same document store.

**Parameters used**

<table style="width:100%; border: 1px solid #ccc; border-collapse: collapse; font: 15px/24px zoho-puvi-regular;">
  <thead>
    <tr style="background-color: #f2f2f2;">
      <th style="border: 1px solid #ccc; padding: 10px; text-align: left; font: 15px/24px zoho-puvi-semibold;">Parameter</th>
      <th style="border: 1px solid #ccc; padding: 10px; text-align: left; font: 15px/24px zoho-puvi-semibold;">Description</th>
      <th style="border: 1px solid #ccc; padding: 10px; text-align: left; font: 15px/24px zoho-puvi-semibold;">Values</th>
    </tr>
  </thead>
  <tbody>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">endpoint_key</td><td style="border: 1px solid #ccc; padding: 10px;">The unique ID of the RAG endpoint published in your project</td><td style="border: 1px solid #ccc; padding: 10px;">String</td></tr>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">prompt</td><td style="border: 1px solid #ccc; padding: 10px;">The query which is sent to the model</td><td style="border: 1px solid #ccc; padding: 10px;">String</td></tr>
    <tr><td style="border: 1px solid #ccc; padding: 10px;">conversation_id</td><td style="border: 1px solid #ccc; padding: 10px;">Identifies the conversation thread the message belongs to</td><td style="border: 1px solid #ccc; padding: 10px;">String</td></tr>
  </tbody>
</table>
<br>
Note: In the first request, you can either ignore or pass "-1" as the value of conversation_id. The response automatically generates and returns a unique conversation ID along with the response, which you must pass in each subsequent requests to continue the same thread .

**Sample Code Snippet**   
# Create a QuickML instance.
quickml = app.quick_ml()

# Converse with RAG Agent

# Replace with your endpoint key copied from the Catalyst console.
    endpoint_key = "<ENDPOINT_KEY>"

# Enter your prompt.
    prompt = "<YOUR_PROMPT>"

# For the first request, use "-1".
    # For subsequent requests, use the conversation ID returned in the previous response.
    conversation_id = "<CONVERSATION_ID>"

response = quickml.converse_with_rag_agent (
     endpoint_key,
     prompt,
     conversation_id
    )
    print(response)

The syntax of the  response  received is shown below:

{
  "status": "success",
  "result": [
    {
      "conversation_id": "55663000000288001 ",
      "content": "The agent's answer, informed by earlier turns in this conversation.",
      "citations": [
        {
          "document_name": "policy_v3.pdf",
          "document_id": "doc_10877",
          "chunk_id": "chunk_12",
          "page_number": 3,
          "text": "The excerpt of source text the answer was grounded in.",
          "score": 0.88
        }
      ],
      "usage": {
        "input_tokens": 3612,
        "output_tokens": 188,
        "total_tokens": 3800
      }
    }
  ]
}

**Where to find the endpoint information**   
Create an endpoint for your Saved RAG configuration and access the endpoint details page to view the Endpoint URL, required headers and a sample request response.

Info : Refer to the  SDK Scopes table  to determine the required permission level for performing the above operation.

RAG

Retrieval-Augmented Generation (RAG) combines a large language model with your organization’s own knowledge base to deliver accurate, context-aware responses grounded in the organization specific documents.

Catalyst QuickML is equipped with RAG system under Generative AI services, to deliver responses grounded in the organization’s own documents with ground truth citations of the documents for traceability. Multiple RAG modes have been introduced each designed for a different use case. Every mode exposes its own dedicated parameters, giving you absolute control over how the RAG system generates responses.

Let’s take a quick look at the RAG modes:

Response Generation : Response Generation is the standard RAG mode where model generates response grounded with relevant chunks of information from the documents
Agentic RAG : An agent layer on top of RAG that can reason over complex queries, decompose them into sub-queries, and handle conversational interactions
Document Search : It is retrieval-only task, doesn’t generate a response but returns the most relevant chunks of content from the documents.

Execute RAG Endpoint

The SDK method you call depends on the RAG mode the endpoint was configured with:

RAG mode	SDK method
Response Generation	generate_rag_response(endpoint_key, prompt)
Document Search	search_documents(endpoint_key, query)
Agentic RAG (without history)	ask_rag_agent(endpoint_key, prompt)
Agentic RAG (with history)	converse_with_rag_agent(endpoint_key, prompt, conversation_id)

Note:

You will need to have the RAG endpoint created and published in your project using the Catalyst console, before you execute the code snippets below.
QuickML is currently available to Catalyst users accessing from the US, IN, and EU data centers

a. Generate a RAG Response

The generate_rag_response(endpoint_key, prompt) method sends a question to a published RAG endpoint. The service retrieves the most relevant content from the endpoint’s document store and returns a summarised response grounded in that content.

Parameters used

Parameter	Description	Values
endpoint_key	The unique ID of the RAG endpoint published in your project	String
prompt	The query which is sent to the model.	String

Sample Code Snippet

copy

# Create a QuickML instance.
quickml = app.quick_ml()
# Generate RAG Response
# Replace with your endpoint key copied from the Catalyst console.
endpoint_key = "<ENDPOINT_KEY>"

# Enter your question.
prompt = "<YOUR_PROMPT>"

response = quickml.generate_rag_response (
endpoint_key,
prompt
)

print(response)

The syntax of the response received is shown below:

copy

         {
  "status": "success",
  "result": [
    {
      "content": "The answer, grounded in the retrieved documents.",
      "citations": [
        {
          "document_name": "employee_handbook_2026.pdf",
          "document_id": "doc_10294",
          "chunk_id": "chunk_58",
          "page_number": 14,
          "text": "The excerpt of source text the answer was grounded in.",
          "score": 0.91
        }
      ],
      "usage": {
        "input_tokens": 1420,
        "output_tokens": 112,
        "total_tokens": 1532
      }
    }
  ]
}
    

Use this method for document-based question answering, summarization, and support assistants

b. Search Documents

The search_documents(endpoint_key, query) method performs retrieval only. It returns the chunks of content from the document store that most closely match the query, without generating a response.

Parameters used

Parameter	Description	Values
endpoint_key	The unique ID of the RAG endpoint published in your project	String
query	The search query is sent to the document store.	String

Sample Code Snippet

copy

# Create a QuickML instance.
quickml = app.quick_ml()
# Search Documents

# Replace with your endpoint key copied from the Catalyst console.
endpoint_key = "<ENDPOINT_KEY>"

# Enter your search query.
query = "<SEARCH_QUERY>"

response = quickml.search_documents (
endpoint_key,
query
)

print(response)

The syntax of the response received is shown below:

copy

         {
  "status": "success",
  "result": [
    {
      "chunk_id": "chunk_58",
      "document_name": "employee_handbook_2026.pdf",
      "document_id": "doc_10294",
      "page_number": 14,
      "text": "The retrieved chunk of content that matched the query.",
      "score": 0.91
    },
    {
      "chunk_id": "chunk_59",
      "document_name": "employee_handbook_2026.pdf",
      "document_id": "doc_10294",
      "page_number": 15,
      "text": "The next most relevant chunk of content.",
      "score": 0.84
    }
  ]
}
    

Use this method when your application needs the raw retrieved passages for downstream processing, ranking, or custom rendering

c. Ask a RAG Agent

The ask_rag_agent(endpoint_key, prompt) method sends a single message to an Agentic RAG endpoint. The agent can decompose complex queries into sub-queries, refine them, and perform multi-step reasoning over the document store before returning a response.

Note : Each call is independent. No conversation context is retained.

Parameters used

Parameter	Description	Values
endpoint_key	The unique ID of the RAG endpoint published in your project	String
prompt	The query which is sent to the model	String

Sample Code Snippet

copy

# Create a QuickML instance.
quickml = app.quick_ml()
# Ask RAG Agent

# Replace with your endpoint key copied from the Catalyst console.
endpoint_key = "<ENDPOINT_KEY>"

# Enter your prompt.
prompt = "<YOUR_PROMPT>"

response = quickml.ask_rag_agent (
 endpoint_key,
 prompt
)
print(response)

The syntax of the response received is shown below:

copy

         {
  "status": "success",
  "result": [
    {
      "content": "The agent's answer after reasoning over the document store.",
      "sub_queries": [
        "First decomposed sub-query the agent generated.",
        "Second decomposed sub-query the agent generated."
      ],
      "citations": [
        {
          "document_name": "policy_v3.pdf",
          "document_id": "doc_10877",
          "chunk_id": "chunk_12",
          "page_number": 3,
          "text": "The excerpt of source text the answer was grounded in.",
          "score": 0.88
        }
      ],
      "usage": {
        "input_tokens": 3180,
        "output_tokens": 204,
        "total_tokens": 3384
      }
    }
  ]
}
    

d. Converse with a RAG Agent

The converse_with_rag_agent(endpoint_key, prompt, conversation_id) method sends a message to an Agentic RAG endpoint while retaining the context of previous turns. Use this method to build multi-turn assistants that answer follow-up questions from the same document store.

Parameters used

Parameter	Description	Values
endpoint_key	The unique ID of the RAG endpoint published in your project	String
prompt	The query which is sent to the model	String
conversation_id	Identifies the conversation thread the message belongs to	String

Note: In the first request, you can either ignore or pass "-1" as the value of conversation_id. The response automatically generates and returns a unique conversation ID along with the response, which you must pass in each subsequent requests to continue the same thread .

Sample Code Snippet

copy

# Create a QuickML instance.
quickml = app.quick_ml()
# Converse with RAG Agent

# Replace with your endpoint key copied from the Catalyst console.
endpoint_key = "<ENDPOINT_KEY>"

# Enter your prompt.
prompt = "<YOUR_PROMPT>"

# For the first request, use "-1".
# For subsequent requests, use the conversation ID returned in the previous response.
conversation_id = "<CONVERSATION_ID>"

response = quickml.converse_with_rag_agent (
 endpoint_key,
 prompt,
 conversation_id
)
print(response)

The syntax of the response received is shown below:

copy

         {
  "status": "success",
  "result": [
    {
      "conversation_id": "55663000000288001 ",
      "content": "The agent's answer, informed by earlier turns in this conversation.",
      "citations": [
        {
          "document_name": "policy_v3.pdf",
          "document_id": "doc_10877",
          "chunk_id": "chunk_12",
          "page_number": 3,
          "text": "The excerpt of source text the answer was grounded in.",
          "score": 0.88
        }
      ],
      "usage": {
        "input_tokens": 3612,
        "output_tokens": 188,
        "total_tokens": 3800
      }
    }
  ]
}
    

Where to find the endpoint information
Create an endpoint for your Saved RAG configuration and access the endpoint details page to view the Endpoint URL, required headers and a sample request response.