Skip to main content
POST
/
api
/
r2r
/
v3
/
retrieval
/
agent
RAG-powered Conversational Agent
curl --request POST \
  --url https://api.intelligence.io.solutions/api/r2r/v3/retrieval/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "Params": {
    "role": "system",
    "content": "<string>",
    "name": "<string>",
    "function_call": [
      "<any>"
    ],
    "tool_calls": [
      "<any>"
    ],
    "tool_call_id": "<string>",
    "metadata": [
      "<any>"
    ],
    "structured_content": [
      "<any>"
    ],
    "image_url": "<string>",
    "image_data": [
      "<any>"
    ]
  },
  "search_mode": "basic",
  "search_settings": {
    "use_hybrid_search": false,
    "use_semantic_search": true,
    "use_fulltext_search": false,
    "filters": "<string>",
    "limit": 10,
    "offset": "0",
    "include_metadatas": true,
    "include_scores": true,
    "search_strategy": "vanilla",
    "hybrid_settings": {
      "full_text_weight": 1,
      "semantic_weight": 5,
      "full_text_limit": 200,
      "rrf_k": 50
    },
    "chunk_settings": {
      "index_measure": "l2_distance",
      "probes": 10,
      "ef_search": 40,
      "enabled": true
    },
    "graph_settings": {
      "limits": [
        "<any>"
      ],
      "enabled": true
    },
    "num_sub_queries": 5
  },
  "rag_generation_config": {
    "model": "<string>",
    "temperature": 123,
    "top_p": 123,
    "max_tokens_to_sample": 123,
    "stream": true,
    "functions": [
      "<any>"
    ],
    "tools": [
      "<any>"
    ],
    "add_generation_kwargs": [
      "<any>"
    ],
    "api_base": "<string>",
    "response_format": [
      {
        "Base Model": {}
      }
    ],
    "extended_thinking": false,
    "thinking_budget": 123,
    "reasoning_effort": "<string>"
  },
  "research_generation_config": {
    "model": "<string>",
    "temperature": 123,
    "top_p": 123,
    "max_tokens_to_sample": 123,
    "stream": true,
    "functions": [
      "<any>"
    ],
    "tools": [
      "<any>"
    ],
    "add_generation_kwargs": [
      "<any>"
    ],
    "api_base": "<string>",
    "response_format": [
      {
        "Base Model": {}
      }
    ],
    "extended_thinking": false,
    "thinking_budget": 123,
    "reasoning_effort": "<string>"
  },
  "rag_tools": "web_search"
}'
{
  "results": {
    "messages": [
      {
        "role": "assistant",
        "content": "Aristotle (384–322 BC) was an Ancient\n                        Greek philosopher and polymath whose contributions\n                        have had a profound impact on various fields of\n                        knowledge.\n                        Here are some key points about his life and work:\n                        \n\n1. **Early Life**: Aristotle was born in 384 BC in\n                        Stagira, Chalcidice, which is near modern-day\n                        Thessaloniki, Greece. His father, Nicomachus, was the\n                        personal physician to King Amyntas of Macedon, which\n                        exposed Aristotle to medical and biological knowledge\n                        from a young age [C].\n\n2. **Education and Career**:\n                        After the death of his parents, Aristotle was sent to\n                        Athens to study at Plato's Academy, where he remained\n                        for about 20 years. After Plato's death, Aristotle\n                        left Athens and eventually became the tutor of\n                        Alexander the Great [C].\n                        \n\n3. **Philosophical Contributions**: Aristotle\n                        founded the Lyceum in Athens, where he established the\n                        Peripatetic school of philosophy. His works cover a\n                        wide range of subjects, including metaphysics, ethics,\n                        politics, logic, biology, and aesthetics. His writings\n                        laid the groundwork for many modern scientific and\n                        philosophical inquiries [A].\n\n4. **Legacy**:\n                        Aristotle's influence extends beyond philosophy to the\n                          natural sciences, linguistics, economics, and\n                          psychology. His method of systematic observation and\n                          analysis has been foundational to the development of\n                          modern science [A].\n\nAristotle's comprehensive\n                          approach to knowledge and his systematic methodology\n                          have earned him a lasting legacy as one of the\n                          greatest philosophers of all time.\n\nSources:\n                          \n- [A] Aristotle's broad range of writings and\n                          influence on modern science.\n- [C] Details about\n                          Aristotle's early life and education.",
        "metadata": {
          "aggregated_search_results": {
            "chunk_search_results": [
              {
                "document_id": "3e157b3a-8469-51db-90d9-52e7d896b49b",
                "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
                "metadata": {
                  "associated_query": "What is the capital of France?",
                  "title": "example_document.pdf"
                },
                "owner_id": "2acb499e-8428-543b-bd85-0d9098718220",
                "score": 0.23943702876567796,
                "text": "Example text from the document"
              }
            ],
            "document_search_results": [
              {
                "document": {
                  "chunks": [
                    "Chunk 1",
                    "Chunk 2"
                  ],
                  "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
                  "metadata": {},
                  "title": "Document Title"
                }
              }
            ],
            "graph_search_results": [
              {
                "chunk_ids": [
                  "c68dc72e-fc23-5452-8f49-d7bd46088a96"
                ],
                "content": {
                  "description": "Entity Description",
                  "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
                  "metadata": {},
                  "name": "Entity Name"
                },
                "metadata": {
                  "associated_query": "What is the capital of France?"
                },
                "result_type": "entity"
              }
            ],
            "web_search_results": [
              {
                "date": "2021-01-01",
                "link": "https://example.com/page",
                "position": 1,
                "sitelinks": [
                  {
                    "link": "https://example.com/sitelink",
                    "title": "Sitelink Title"
                  }
                ],
                "snippet": "Page snippet",
                "title": "Page Title"
              }
            ]
          },
          "citations": [
            {
              "collection_ids": [
                "122fdf6a-e116-546b-a8f6-e4cb2e2c0a09"
              ],
              "document_id": "\n                                    e43864f5-a36f-548e-aacd-6f8d48b30c7f\n                                    ",
              "endIndex": 396,
              "id": "e760bb76-1c6e-52eb-910d-0ce5b567011b",
              "index": 1,
              "metadata": {
                "chunk_order": 68,
                "document_type": "pdf",
                "license": "CC-BY-4.0",
                "title": "DeepSeek_R1.pdf"
              },
              "owner_id": "\n                                    2acb499e-8428-543b-bd85-0d9098718220\n                                    ",
              "rawIndex": 9,
              "score": 0.64,
              "snippetEndIndex": 418,
              "snippetStartIndex": 320,
              "sourceType": "chunk",
              "startIndex": 393,
              "text": "\n                                    Document Title: DeepSeek_R1.pdf\n                                    \n\nText: could achieve an accuracy of ...\n                                    "
            }
          ]
        }
      }
    ],
    "conversation_id": "a32b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d"
  }
}
This endpoint offers two operating modes:
  • RAG mode: Standard retrieval-augmented generation for answering questions based on knowledge base
  • Research mode: Advanced capabilities for deep analysis, reasoning, and computation

​
RAG Mode (Default)

The RAG mode provides fast, knowledge-based responses using:
  • Semantic and hybrid search capabilities
  • Document-level and chunk-level content retrieval
  • Optional web search integration
  • Source citation and evidence-based responses

​
Research Mode

The Research mode builds on RAG capabilities and adds:
  • A dedicated reasoning system for complex problem-solving
  • Critique capabilities to identify potential biases or logical fallacies
  • Python execution for computational analysis
  • Multi-step reasoning for deeper exploration of topics

​
Available Tools

​
RAG Tools:

  • search_file_knowledge: Semantic/hybrid search on your ingested documents
  • search_file_descriptions: Search over file-level metadata
  • content: Fetch entire documents or chunk structures
  • web_search: Query external search APIs for up-to-date information
  • web_scrape: Scrape and extract content from specific web pages

​
Research Tools:

  • rag: Leverage the underlying RAG agent for information retrieval
  • reasoning: Call a dedicated model for complex analytical thinking
  • critique: Analyze conversation history to identify flaws and biases
  • python_executor: Execute Python code for complex calculations and analysis

​
Streaming Output

When streaming is enabled, the agent produces different event types:
  • thinking: Shows the model’s step-by-step reasoning (when extended_thinking=true)
  • tool_cal: Shows when the agent invokes a tool
  • tool_result: Shows the result of a tool call
  • citation: Indicates when a citation is added to the response
  • message: Streams partial tokens of the response
  • final_answer: Contains the complete generated answer and structured citations

​
Conversations

Maintain context across multiple turns by including conversation_id in each request. After your first call, store the returned conversation_id and include it in subsequent calls. If no conversation name has already been set for the conversation, the system will automatically assign one.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
Params
object

Current message to process

​
search_mode
enum<string>

Pre-configured search modes: basic, advanced, or custom.

Available options:
basic,
advanced,
custom
​
search_settings
object

The search configuration object for retrieving context.

​
rag_generation_config
object

Configuration for RAG generation in 'rag' mode

​
research_generation_config
object

Configuration for generation in ‘research’ mode. If not provided but mode=‘research’, rag_generation_config will be used with appropriate model overrides.

​
rag_tools
enum<string>

List of tools to enable for RAG mode. Available tools: search_file_knowledge, get_file_content, web_search, web_scrape, search_file_descriptions

Available options:
web_search,
web_scrape,
search_file_descriptions,
search_file_knowledge,
get_file_content

Response

200

​
results
object
⌘I