RAG-powered Conversational Agent

POST

1 from r2r import R2RClient
2 
3 client = R2RClient()
4 # when using auth, do client.login(...)
5 
6 response = client.retrieval.agent(
7     message={
8         "role": "user",
9         "content": "What were the key contributions of Aristotle to logic and how did they influence later philosophers?"
10     },
11     search_settings={
12         "use_semantic_search": True,
13         "filters": {"document_id": {"$eq": "3e157b3a-8469-51db-90d9-52e7d896b49b"}},
14         "limit": 10,
15         chunk_settings={
16             "limit": 20, # separate limit for chunk vs. graph
17         },
18         graph_settings={
19             "enabled": True,
20         },
21     },
22     rag_generation_config: {
23         stream: false,
24         temperature: 0.7,
25         max_tokens: 150
26     }
27     include_title_if_available=True,
28     conversation_id="550e8400-e29b-41d4-a716-446655440000"  # Optional for conversation continuity
29 )

Play

200Successful

1 {
2   "results": {
3     "messages": [
4       {
5         "role": "assistant",
6         "content": "Aristotle (384–322 BC) was an Ancient Greek philosopher and polymath whose contributions have had a profound impact on various fields of knowledge. Here are some key points about his life and work:\n\n1. **Early Life**: Aristotle was born in 384 BC in Stagira, Chalcidice, which is near modern-day Thessaloniki, Greece. His father, Nicomachus, was the personal physician to King Amyntas of Macedon, which exposed Aristotle to medical and biological knowledge from a young age [C].\n\n2. **Education and Career**: After the death of his parents, Aristotle was sent to Athens to study at Plato's Academy, where he remained for about 20 years. After Plato's death, Aristotle left Athens and eventually became the tutor of Alexander the Great [C].\n\n3. **Philosophical Contributions**: Aristotle founded the Lyceum in Athens, where he established the Peripatetic school of philosophy. His works cover a wide range of subjects, including metaphysics, ethics, politics, logic, biology, and aesthetics. His writings laid the groundwork for many modern scientific and philosophical inquiries [A].\n\n4. **Legacy**: Aristotle's influence extends beyond philosophy to the natural sciences, linguistics, economics, and psychology. His method of systematic observation and analysis has been foundational to the development of modern science [A].\n\nAristotle's comprehensive approach to knowledge and his systematic methodology have earned him a lasting legacy as one of the greatest philosophers of all time.\n\nSources:\n- [A] Aristotle's broad range of writings and influence on modern science.\n- [C] Details about Aristotle's early life and education.",
7         "metadata": {
8           "aggregated_search_results": {
9             "chunk_search_results": [
10               {
11                 "document_id": "3e157b3a-8469-51db-90d9-52e7d896b49b",
12                 "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
13                 "metadata": {
14                   "associated_query": "What is the capital of France?",
15                   "title": "example_document.pdf"
16                 },
17                 "owner_id": "2acb499e-8428-543b-bd85-0d9098718220",
18                 "score": 0.23943702876567796,
19                 "text": "Example text from the document"
20               }
21             ],
22             "context_document_results": [
23               {
24                 "document": {
25                   "chunks": [
26                     "Chunk 1",
27                     "Chunk 2"
28                   ],
29                   "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
30                   "metadata": {},
31                   "title": "Document Title"
32                 }
33               }
34             ],
35             "graph_search_results": [
36               {
37                 "chunk_ids": [
38                   "c68dc72e-fc23-5452-8f49-d7bd46088a96"
39                 ],
40                 "content": {
41                   "description": "Entity Description",
42                   "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
43                   "metadata": {},
44                   "name": "Entity Name"
45                 },
46                 "metadata": {
47                   "associated_query": "What is the capital of France?"
48                 },
49                 "result_type": "entity"
50               }
51             ],
52             "web_search_results": [
53               {
54                 "date": "2021-01-01",
55                 "link": "https://example.com/page",
56                 "position": 1,
57                 "sitelinks": [
58                   {
59                     "link": "https://example.com/sitelink",
60                     "title": "Sitelink Title"
61                   }
62                 ],
63                 "snippet": "Page snippet",
64                 "title": "Page Title"
65               }
66             ]
67           },
68           "citations": [
69             {
70               "collection_ids": [
71                 "122fdf6a-e116-546b-a8f6-e4cb2e2c0a09"
72               ],
73               "document_id": "e43864f5-a36f-548e-aacd-6f8d48b30c7f",
74               "endIndex": 396,
75               "id": "e760bb76-1c6e-52eb-910d-0ce5b567011b",
76               "index": 1,
77               "metadata": {
78                 "chunk_order": 68,
79                 "document_type": "pdf",
80                 "license": "CC-BY-4.0",
81                 "title": "DeepSeek_R1.pdf"
82               },
83               "owner_id": "2acb499e-8428-543b-bd85-0d9098718220",
84               "rawIndex": 9,
85               "score": 0.64,
86               "snippetEndIndex": 418,
87               "snippetStartIndex": 320,
88               "sourceType": "chunk",
89               "startIndex": 393,
90               "text": "Document Title: DeepSeek_R1.pdf\n\nText: could achieve an accuracy of ..."
91             }
92           ]
93         }
94       }
95     ],
96     "conversation_id": "a32b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d"
97   }
98 }

Engage with an intelligent RAG-powered conversational agent for complex information retrieval and analysis.

This advanced endpoint combines retrieval-augmented generation (RAG) with a conversational AI agent to provide detailed, context-aware responses based on your document collection. The agent can:

Maintain conversation context across multiple interactions
Dynamically search and retrieve relevant information from both vector and knowledge graph sources
Break down complex queries into sub-questions for comprehensive answers
Cite sources and provide evidence-based responses
Handle follow-up questions and clarifications
Navigate complex topics with multi-step reasoning

Key Features:

Hybrid search combining vector and knowledge graph approaches
Contextual conversation management with conversation_id tracking
Customizable generation parameters for response style and length
Source document citation with optional title inclusion
Streaming support for real-time responses
Branch management for exploring different conversation paths

Common Use Cases:

Research assistance and literature review
Document analysis and summarization
Technical support and troubleshooting
Educational Q&A and tutoring
Knowledge base exploration

The agent uses both vector search and knowledge graph capabilities to find and synthesize information, providing detailed, factual responses with proper attribution to source documents.

Request

This endpoint expects an object.

messageobjectOptional

Current message to process

search_modeenumOptional

Default value of custom allows full control over search settings.

Pre-configured search modes: basic: A simple semantic-based search. advanced: A more powerful hybrid search combining semantic and full-text. custom: Full control via search_settings.

If filters or limit are provided alongside basic or advanced, they will override the default settings for that mode.

Allowed values:

search_settingsobjectOptional

The search configuration object. If search_mode is custom, these settings are used as-is. For basic or advanced, these settings will override the default mode configuration.

Common overrides include filters to narrow results and limit to control how many results are returned.

rag_generation_configobjectOptional

Configuration for RAG generation

task_prompt_overridestringOptional

Optional custom prompt to override default

include_title_if_availablebooleanOptionalDefaults to true

Include document titles in responses when available

conversation_idstringOptionalformat: "uuid"

ID of the conversation

toolslist of stringsOptional

List of tools to execute

max_tool_context_lengthintegerOptional

Maximum length of returned tool context

use_system_contextbooleanOptional

Use extended prompt for generation

messageslist of objectsOptionalDeprecated

List of messages (deprecated, use message instead)

Response

Successful Response

resultsobject

RAG-powered Conversational Agent

Headers

Request

Response

Errors