RAG-powered Conversational Agent

POST

https://api.sciphi.ai/v3/retrieval/agent

POST

/v3/retrieval/agent

1 from r2r import (
2     R2RClient,
3     ThinkingEvent,
4     ToolCallEvent,
5     ToolResultEvent,
6     CitationEvent,
7     FinalAnswerEvent,
8     MessageEvent,
9 )
10 
11 client = R2RClient()
12 # when using auth, do client.login(...)
13 
14 # Basic synchronous request
15 response = client.retrieval.agent(
16     message={
17         "role": "user",
18         "content": "Do a deep analysis of the philosophical implications of DeepSeek R1"
19     },
20     rag_tools=["web_search", "web_scrape", "search_file_descriptions", "search_file_knowledge", "get_file_content"],
21 )
22 
23 # Advanced analysis with streaming and extended thinking
24 streaming_response = client.retrieval.agent(
25     message={
26         "role": "user",
27         "content": "Do a deep analysis of the philosophical implications of DeepSeek R1"
28     },
29     search_settings={"limit": 20},
30     rag_tools=["web_search", "web_scrape", "search_file_descriptions", "search_file_knowledge", "get_file_content"],
31     rag_generation_config={
32         "model": "anthropic/claude-3-7-sonnet-20250219",
33         "extended_thinking": True,
34         "thinking_budget": 4096,
35         "temperature": 1,
36         "top_p": None,
37         "max_tokens": 16000,
38         "stream": True
39     }
40 )
41 
42 # Process streaming events with emoji only on type change
43 current_event_type = None
44 for event in streaming_response:
45     # Check if the event type has changed
46     event_type = type(event)
47     if event_type != current_event_type:
48         current_event_type = event_type
49         print() # Add newline before new event type
50 
51         # Print emoji based on the new event type
52         if isinstance(event, ThinkingEvent):
53             print(f"
54 🧠 Thinking: ", end="", flush=True)
55         elif isinstance(event, ToolCallEvent):
56             print(f"
57 🔧 Tool call: ", end="", flush=True)
58         elif isinstance(event, ToolResultEvent):
59             print(f"
60 📊 Tool result: ", end="", flush=True)
61         elif isinstance(event, CitationEvent):
62             print(f"
63 📑 Citation: ", end="", flush=True)
64         elif isinstance(event, MessageEvent):
65             print(f"
66 💬 Message: ", end="", flush=True)
67         elif isinstance(event, FinalAnswerEvent):
68             print(f"
69 ✅ Final answer: ", end="", flush=True)
70 
71     # Print the content without the emoji
72     if isinstance(event, ThinkingEvent):
73         print(f"{event.data.delta.content[0].payload.value}", end="", flush=True)
74     elif isinstance(event, ToolCallEvent):
75         print(f"{event.data.name}({event.data.arguments})")
76     elif isinstance(event, ToolResultEvent):
77         print(f"{event.data.content[:60]}...")
78     elif isinstance(event, CitationEvent):
79         print(f"{event.data.id}")
80     elif isinstance(event, MessageEvent):
81         print(f"{event.data.delta.content[0].payload.value}", end="", flush=True)
82     elif isinstance(event, FinalAnswerEvent):
83         print(f"{event.data.generated_answer[:100]}...")
84         print(f"   Citations: {len(event.data.citations)} sources referenced")
85 
86 # Conversation with multiple turns (synchronous)
87 conversation = client.conversations.create()
88 
89 # First message in conversation
90 results_1 = client.retrieval.agent(
91     message={"role": "user", "content": "What does DeepSeek R1 imply for the future of AI?"},
92     rag_generation_config={
93         "model": "anthropic/claude-3-7-sonnet-20250219",
94         "extended_thinking": True,
95         "thinking_budget": 4096,
96         "temperature": 1,
97         "top_p": None,
98         "max_tokens": 16000,
99         "stream": False
100     },
101     conversation_id=conversation.results.id
102 )
103 
104 # Follow-up query in the same conversation
105 results_2 = client.retrieval.agent(
106     message={"role": "user", "content": "How does it compare to other reasoning models?"},
107     rag_generation_config={
108         "model": "anthropic/claude-3-7-sonnet-20250219",
109         "extended_thinking": True,
110         "thinking_budget": 4096,
111         "temperature": 1,
112         "top_p": None,
113         "max_tokens": 16000,
114         "stream": False
115     },
116     conversation_id=conversation.results.id
117 )
118 
119 # Access the final results
120 print(f"First response: {results_1.generated_answer[:100]}...")
121 print(f"Follow-up response: {results_2.generated_answer[:100]}...")

Try it

1 {
2   "results": {
3     "messages": [
4       {
5         "role": "assistant",
6         "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.",
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             "document_search_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": "\n                                    e43864f5-a36f-548e-aacd-6f8d48b30c7f\n                                    ",
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": "\n                                    2acb499e-8428-543b-bd85-0d9098718220\n                                    ",
84               "rawIndex": 9,
85               "score": 0.64,
86               "snippetEndIndex": 418,
87               "snippetStartIndex": 320,
88               "sourceType": "chunk",
89               "startIndex": 393,
90               "text": "\n                                    Document Title: DeepSeek_R1.pdf\n                                    \n\nText: could achieve an accuracy of ...\n                                    "
91             }
92           ]
93         }
94       }
95     ],
96     "conversation_id": "a32b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d"
97   }
98 }

Engage with an intelligent agent for information retrieval, analysis, and research.

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_call: 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.

Engage with an intelligent agent for information retrieval, analysis, and research. 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_call`: 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.

Request

This endpoint expects an object.

messageobjectOptional

Current message to process

search_modeenumOptional

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

Allowed values:

search_settingsobjectOptional

The search configuration object for retrieving context.

rag_generation_configobjectOptional

Configuration for RAG generation in 'rag' mode

research_generation_configobjectOptional

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

rag_toolslist of enumsOptional

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

Allowed values:

research_toolslist of enumsOptional

List of tools to enable for Research mode. Available tools: rag, reasoning, critique, python_executor

Allowed values:

task_promptstringOptional

Optional custom prompt to override default

include_title_if_availablebooleanOptionalDefaults to true

Pass document titles from search results into the LLM context window.

conversation_idstringOptionalformat: "uuid"

ID of the conversation

max_tool_context_lengthintegerOptional

Maximum length of returned tool context

use_system_contextbooleanOptional

Use extended prompt for generation

modeenumOptional

Mode to use for generation: ‘rag’ for standard retrieval or ‘research’ for deep analysis with reasoning capabilities

Allowed values:

needs_initial_conversation_namebooleanOptional

If true, the system will automatically assign a conversation name if not already specified previously.

messageslist of objectsOptionalDeprecated

List of messages (deprecated, use message instead)

toolslist of stringsOptionalDeprecated

List of tools to execute (deprecated, use rag_tools or research_tools instead)

task_prompt_overridestringOptionalDeprecated

Optional custom prompt to override default

Response

Successful Response

resultsobject

RAG-powered Conversational Agent

RAG Mode (Default)

Research Mode

Available Tools

Streaming Output

Conversations

Headers

Request

Response

Errors

RAG Mode (Default)

Research Mode

Available Tools

Streaming Output

Conversations