RAG Search Tool

Search your uploaded documents for relevant information.

Overview

The RAG (Retrieval-Augmented Generation) search tool lets AI access your uploaded documents. It finds the most relevant document chunks based on semantic similarity.

How It Works

1. Query - AI provides a search query
2. Embed - Query is converted to a vector
3. Match - Vector is compared against document embeddings
4. Return - Most similar chunks are returned

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Search query text
collection	string	Yes	-	RAG collection name
top_k	integer	No	5	Number of results to return
similarity_threshold	float	No	0.5	Minimum similarity score (0-1)
filters	object	No	-	Metadata filters

Usage Examples

Basic Search

import requests

response = requests.post(
    "http://localhost/api/v1/agent/tool-calling",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "tool_name": "rag_search",
        "parameters": {
            "query": "How do I reset my password?",
            "collection": "documentation",
            "top_k": 5
        }
    }
)

results = response.json()["results"]
for result in results:
    print(f"Score: {result['score']:.4f}")
    print(f"Content: {result['content'][:100]}...\n")

Search with Filters

response = requests.post(
    "http://localhost/api/v1/agent/tool-calling",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "tool_name": "rag_search",
        "parameters": {
            "query": "Security guidelines",
            "collection": "policies",
            "top_k": 5,
            "filters": {
                "category": "security",
                "version": "2.0"
            }
        }
    }
)

High Precision Search

response = requests.post(
    "http://localhost/api/v1/agent/tool-calling",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "tool_name": "rag_search",
        "parameters": {
            "query": "API authentication",
            "collection": "docs",
            "top_k": 10,
            "similarity_threshold": 0.9
        }
    }
)

results = response.json()["results"]
print(f"Found {len(results)} highly relevant results")

Use in Agent

# Create agent with RAG search
response = requests.post(
    "http://localhost/api/v1/agent/configs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "documentation_agent",
        "system_prompt": "You are a helpful assistant that uses documentation to answer questions.",
        "model": "gpt-4",
        "builtin_tools": ["rag_search"],
        "tool_config": {
            "rag_search": {
                "default_collection": "documentation",
                "top_k": 5,
                "similarity_threshold": 0.7
            }
        },
        "tool_choice": "auto",
        "max_iterations": 3
    }
)

agent_id = response.json()["id"]

# Chat with agent
chat_response = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": agent_id,
        "message": "How do I configure the API key?"
    }
)

result = chat_response.json()
print(f"Response: {result['response']}")
print(f"Tool calls: {result.get('tool_calls', [])}")

JavaScript Usage

const response = await fetch('http://localhost/api/v1/agent/tool-calling', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tool_name: 'rag_search',
    parameters: {
      query: 'How do I reset my password?',
      collection: 'documentation',
      top_k: 5
    }
  })
});

const results = await response.json();
results.results.forEach(result => {
  console.log(`Score: ${result.score.toFixed(4)}`);
  console.log(`Content: ${result.content.substring(0, 100)}...`);
});

cURL Usage

curl -X POST http://localhost/api/v1/agent/tool-calling \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "rag_search",
    "parameters": {
      "query": "API key configuration",
      "collection": "documentation",
      "top_k": 5
    }
  }'

Response Format

{
  "results": [
    {
      "score": 0.92,
      "content": "To configure API keys, navigate to Settings > API Keys and click 'Generate New Key'...",
      "metadata": {
        "document_id": "doc_abc123",
        "chunk_id": "chunk_xyz789",
        "filename": "user_guide.pdf",
        "page": 15
      }
    }
  ]
}

Best Practices

Query Quality

Good Queries	Poor Queries
"How do I reset my password?"	"password"
"Steps to configure API keys"	"API keys"
"Security best practices for authentication"	"security"

Collection Organization

• Use descriptive collection names
• Group related documents together
• Apply consistent metadata
• Update documents regularly

Threshold Selection

Threshold	Use Case
0.5-0.6	Broad exploration
0.7-0.8	Standard search
0.9-1.0	Precise matching

Troubleshooting

No Results Found

Problem: Search returns empty results

Solution:

• Verify collection name is correct
• Check collection has documents
• Lower similarity_threshold
• Increase top_k value
• Try broader query terms

Low Quality Results

Problem: Results don't match query well

Solution:

• Refine query terms
• Check document content
• Increase top_k for more options
• Review document chunking strategy
• Update documents with better keywords

Collection Not Found

Problem: {"error": "Collection not found"}

Solution:

• Verify collection name spelling
• Check collection exists
• Confirm you have access to collection

Next Steps

• RAG Documentation - Upload and manage documents
• Web Search Tool - Search the internet
• Code Execution Tool - Run code securely
• Agent Documentation - Use tools in agents