Skip to main content

RagTool

Description

The RagTool is designed to answer questions by leveraging the power of Retrieval-Augmented Generation (RAG) through CrewAI’s native RAG system. It provides a dynamic knowledge base that can be queried to retrieve relevant information from various data sources. This tool is particularly useful for applications that require access to a vast array of information and need to provide contextually relevant answers.

Example

The following example demonstrates how to initialize the tool and use it with different data sources:
Code

Supported Data Sources

The RagTool can be used with a wide variety of data sources, including:
  • 📰 PDF files
  • 📊 CSV files
  • 📃 JSON files
  • JSONL files (.jsonl and .ndjson)
  • 📝 Text
  • 📁 Directories/Folders
  • 🌐 HTML Web pages
  • 📽️ YouTube Channels
  • 📺 YouTube Videos
  • 📚 Documentation websites
  • 📝 MDX files
  • 📄 DOCX files
  • 🧾 XML files
  • 📬 Gmail
  • 📝 GitHub repositories
  • 🐘 PostgreSQL databases
  • 🐬 MySQL databases
  • 🤖 Slack conversations
  • 💬 Discord messages
  • 🗨️ Discourse forums
  • 📝 Substack newsletters
  • 🐝 Beehiiv content
  • 💾 Dropbox files
  • 🖼️ Images
  • ⚙️ Custom data sources

Parameters

The RagTool accepts the following parameters:
  • summarize: Optional. Whether to summarize the retrieved content. Default is False.
  • adapter: Optional. A custom adapter for the knowledge base. If not provided, a CrewAIRagAdapter will be used.
  • config: Optional. Configuration for the underlying CrewAI RAG system. Accepts a RagToolConfig TypedDict with optional embedding_model (ProviderSpec) and vectordb (VectorDbConfig) keys. All configuration values provided programmatically take precedence over environment variables.

Adding Content

You can add content to the knowledge base using the add method:
Code
JSONL files contain one JSON value per line. The JSONL loader supports local files; recognizing a JSONL URL does not fetch its content.

Agent Integration Example

Here’s how to integrate the RagTool with a CrewAI agent:
Code

Vector Database

RagTool stores content in a local Qdrant database by default, with OpenAI’s text-embedding-3-small as the embedder. To use ChromaDB, install it with pip install "crewai[chromadb]" and set "provider": "chromadb" in the vectordb config.
Content that an earlier version stored in ChromaDB is not read by the Qdrant default. Add it again, or set the chromadb provider.

Advanced Configuration

You can customize the behavior of the RagTool by providing a configuration dictionary:
Code

Embedding Model Configuration

The embedding_model parameter accepts a crewai.rag.embeddings.types.ProviderSpec dictionary with the structure:

Supported Providers

These providers use ChromaDB and need pip install "crewai[chromadb]": bedrock, cohere, google-generativeai, huggingface, instructor, jina, ollama, onnx, openclip, roboflow, sentence-transformer, text2vec. The others (such as openai, azure, openrouter, google-vertex, voyageai, watsonx, oracle and custom) work without it.
main.py
Config Options:
  • api_key (str): OpenAI API key
  • model_name (str): Model to use. Default: text-embedding-ada-002. Options: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
  • dimensions (int): Number of dimensions for the embedding
  • organization_id (str): OpenAI organization ID
  • api_base (str): Custom API base URL
  • api_version (str): API version
  • default_headers (dict): Custom headers for API requests
Environment Variables:
  • OPENAI_API_KEY or EMBEDDINGS_OPENAI_API_KEY: api_key
  • OPENAI_ORGANIZATION_ID or EMBEDDINGS_OPENAI_ORGANIZATION_ID: organization_id
  • OPENAI_MODEL_NAME or EMBEDDINGS_OPENAI_MODEL_NAME: model_name
  • OPENAI_API_BASE or EMBEDDINGS_OPENAI_API_BASE: api_base
  • OPENAI_API_VERSION or EMBEDDINGS_OPENAI_API_VERSION: api_version
  • OPENAI_DIMENSIONS or EMBEDDINGS_OPENAI_DIMENSIONS: dimensions
main.py
Config Options:
  • api_key (str): Cohere API key
  • model_name (str): Model to use. Default: large. Options: embed-english-v3.0, embed-multilingual-v3.0, large, small
Environment Variables:
  • COHERE_API_KEY or EMBEDDINGS_COHERE_API_KEY: api_key
  • EMBEDDINGS_COHERE_MODEL_NAME: model_name
main.py
Config Options:
  • api_key (str): VoyageAI API key
  • model (str): Model to use. Default: voyage-2. Options: voyage-3, voyage-3-lite, voyage-code-3, voyage-large-2
  • input_type (str): Type of input. Options: document (for storage), query (for search)
  • truncation (bool): Whether to truncate inputs that exceed max length. Default: True
  • output_dtype (str): Output data type
  • output_dimension (int): Dimension of output embeddings
  • max_retries (int): Maximum number of retry attempts. Default: 0
  • timeout (float): Request timeout in seconds
Environment Variables:
  • VOYAGEAI_API_KEY or EMBEDDINGS_VOYAGEAI_API_KEY: api_key
  • VOYAGEAI_MODEL or EMBEDDINGS_VOYAGEAI_MODEL: model
  • VOYAGEAI_INPUT_TYPE or EMBEDDINGS_VOYAGEAI_INPUT_TYPE: input_type
  • VOYAGEAI_TRUNCATION or EMBEDDINGS_VOYAGEAI_TRUNCATION: truncation
  • VOYAGEAI_OUTPUT_DTYPE or EMBEDDINGS_VOYAGEAI_OUTPUT_DTYPE: output_dtype
  • VOYAGEAI_OUTPUT_DIMENSION or EMBEDDINGS_VOYAGEAI_OUTPUT_DIMENSION: output_dimension
  • VOYAGEAI_MAX_RETRIES or EMBEDDINGS_VOYAGEAI_MAX_RETRIES: max_retries
  • VOYAGEAI_TIMEOUT or EMBEDDINGS_VOYAGEAI_TIMEOUT: timeout
main.py
Config Options:
  • model_name (str): Ollama model name (e.g., llama2, mistral, nomic-embed-text)
  • url (str): Ollama API endpoint URL. Default: http://localhost:11434/api/embeddings
Environment Variables:
  • OLLAMA_MODEL or EMBEDDINGS_OLLAMA_MODEL: model_name
  • OLLAMA_URL or EMBEDDINGS_OLLAMA_URL: url
main.py
Config Options:
  • model_name (str): Bedrock model ID. Default: amazon.titan-embed-text-v1. Options: amazon.titan-embed-text-v1, amazon.titan-embed-text-v2:0, cohere.embed-english-v3, cohere.embed-multilingual-v3
  • session (Any): Boto3 session object for AWS authentication
Environment Variables:
  • AWS_ACCESS_KEY_ID: AWS access key
  • AWS_SECRET_ACCESS_KEY: AWS secret key
  • AWS_REGION: AWS region (e.g., us-east-1)
main.py
Config Options:
  • deployment_id (str): Required - Azure OpenAI deployment ID
  • api_key (str): Azure OpenAI API key
  • api_base (str): Azure OpenAI resource endpoint
  • api_version (str): API version. Example: 2024-02-01
  • model_name (str): Model name. Default: text-embedding-ada-002
  • api_type (str): API type. Default: azure
  • dimensions (int): Output dimensions
  • default_headers (dict): Custom headers
Environment Variables:
  • AZURE_OPENAI_API_KEY or EMBEDDINGS_AZURE_API_KEY: api_key
  • AZURE_OPENAI_ENDPOINT or EMBEDDINGS_AZURE_API_BASE: api_base
  • EMBEDDINGS_AZURE_DEPLOYMENT_ID: deployment_id
  • EMBEDDINGS_AZURE_API_VERSION: api_version
  • EMBEDDINGS_AZURE_MODEL_NAME: model_name
  • EMBEDDINGS_AZURE_API_TYPE: api_type
  • EMBEDDINGS_AZURE_DIMENSIONS: dimensions
main.py
Config Options:
  • api_key (str): Google AI API key
  • model_name (str): Model name. Default: gemini-embedding-001. Options: gemini-embedding-001, text-embedding-005, text-multilingual-embedding-002
  • task_type (str): Task type for embeddings. Default: RETRIEVAL_DOCUMENT. Options: RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY
Environment Variables:
  • GOOGLE_API_KEY, GEMINI_API_KEY, or EMBEDDINGS_GOOGLE_API_KEY: api_key
  • EMBEDDINGS_GOOGLE_GENERATIVE_AI_MODEL_NAME: model_name
  • EMBEDDINGS_GOOGLE_GENERATIVE_AI_TASK_TYPE: task_type
main.py
Config Options:
  • model_name (str): Model name. Default: textembedding-gecko. Options: text-embedding-004, textembedding-gecko, textembedding-gecko-multilingual
  • project_id (str): Google Cloud project ID. Default: cloud-large-language-models
  • region (str): Google Cloud region. Default: us-central1
  • api_key (str): API key for authentication
Environment Variables:
  • GOOGLE_APPLICATION_CREDENTIALS: Path to service account JSON file
  • GOOGLE_CLOUD_PROJECT or EMBEDDINGS_GOOGLE_VERTEX_PROJECT_ID: project_id
  • EMBEDDINGS_GOOGLE_VERTEX_MODEL_NAME: model_name
  • EMBEDDINGS_GOOGLE_VERTEX_REGION: region
  • EMBEDDINGS_GOOGLE_VERTEX_API_KEY: api_key
main.py
Config Options:
  • api_key (str): Jina AI API key
  • model_name (str): Model name. Default: jina-embeddings-v2-base-en. Options: jina-embeddings-v3, jina-embeddings-v2-base-en, jina-embeddings-v2-small-en
Environment Variables:
  • JINA_API_KEY or EMBEDDINGS_JINA_API_KEY: api_key
  • EMBEDDINGS_JINA_MODEL_NAME: model_name
main.py
Config Options:
  • url (str): Full URL to HuggingFace inference API endpoint
Environment Variables:
  • HUGGINGFACE_URL or EMBEDDINGS_HUGGINGFACE_URL: url
main.py
Config Options:
  • model_name (str): HuggingFace model ID. Default: hkunlp/instructor-base. Options: hkunlp/instructor-xl, hkunlp/instructor-large, hkunlp/instructor-base
  • device (str): Device to run on. Default: cpu. Options: cpu, cuda, mps, xpu
  • instruction (str): Instruction prefix for embeddings
Environment Variables:
  • EMBEDDINGS_INSTRUCTOR_MODEL_NAME: model_name
  • EMBEDDINGS_INSTRUCTOR_DEVICE: device
  • EMBEDDINGS_INSTRUCTOR_INSTRUCTION: instruction
main.py
Config Options:
  • model_name (str): Sentence Transformers model name. Default: all-MiniLM-L6-v2. Options: all-mpnet-base-v2, all-MiniLM-L6-v2, paraphrase-multilingual-MiniLM-L12-v2
  • device (str): Device to run on. Default: cpu. Options: cpu, cuda, mps, xpu
  • normalize_embeddings (bool): Whether to normalize embeddings. Default: False
Environment Variables:
  • EMBEDDINGS_SENTENCE_TRANSFORMER_MODEL_NAME: model_name
  • EMBEDDINGS_SENTENCE_TRANSFORMER_DEVICE: device
  • EMBEDDINGS_SENTENCE_TRANSFORMER_NORMALIZE_EMBEDDINGS: normalize_embeddings
main.py
Config Options:
  • preferred_providers (list[str]): List of ONNX execution providers in order of preference
Environment Variables:
  • EMBEDDINGS_ONNX_PREFERRED_PROVIDERS: preferred_providers (comma-separated list)
main.py
Config Options:
  • model_name (str): OpenCLIP model architecture. Default: ViT-B-32. Options: ViT-B-32, ViT-B-16, ViT-L-14
  • checkpoint (str): Pretrained checkpoint name. Default: laion2b_s34b_b79k. Options: laion2b_s34b_b79k, laion400m_e32, openai
  • device (str): Device to run on. Default: cpu. Options: cpu, cuda, mps, xpu
Environment Variables:
  • EMBEDDINGS_OPENCLIP_MODEL_NAME: model_name
  • EMBEDDINGS_OPENCLIP_CHECKPOINT: checkpoint
  • EMBEDDINGS_OPENCLIP_DEVICE: device
main.py
Config Options:
  • model_name (str): Text2Vec model name from HuggingFace. Default: shibing624/text2vec-base-chinese. Options: shibing624/text2vec-base-multilingual, shibing624/text2vec-base-chinese
Environment Variables:
  • EMBEDDINGS_TEXT2VEC_MODEL_NAME: model_name
main.py
Config Options:
  • api_key (str): Roboflow API key. Default: "" (empty string)
  • api_url (str): Roboflow inference API URL. Default: https://infer.roboflow.com
Environment Variables:
  • ROBOFLOW_API_KEY or EMBEDDINGS_ROBOFLOW_API_KEY: api_key
  • ROBOFLOW_API_URL or EMBEDDINGS_ROBOFLOW_API_URL: api_url
main.py
Config Options:
  • model_id (str): WatsonX model identifier
  • url (str): WatsonX API endpoint
  • api_key (str): IBM Cloud API key
  • project_id (str): WatsonX project ID
  • space_id (str): WatsonX space ID (alternative to project_id)
  • batch_size (int): Batch size for embeddings. Default: 100
  • concurrency_limit (int): Maximum concurrent requests. Default: 10
  • persistent_connection (bool): Use persistent connections. Default: True
  • Plus 20+ additional authentication and configuration options
Environment Variables:
  • WATSONX_API_KEY or EMBEDDINGS_WATSONX_API_KEY: api_key
  • WATSONX_URL or EMBEDDINGS_WATSONX_URL: url
  • WATSONX_PROJECT_ID or EMBEDDINGS_WATSONX_PROJECT_ID: project_id
  • EMBEDDINGS_WATSONX_MODEL_ID: model_id
  • EMBEDDINGS_WATSONX_SPACE_ID: space_id
  • EMBEDDINGS_WATSONX_BATCH_SIZE: batch_size
  • EMBEDDINGS_WATSONX_CONCURRENCY_LIMIT: concurrency_limit
  • EMBEDDINGS_WATSONX_PERSISTENT_CONNECTION: persistent_connection
main.py
Config Options:
  • embedding_callable (type[EmbeddingFunction]): Custom embedding function class
Note: Custom embedding functions must implement the EmbeddingFunction protocol defined in crewai.rag.core.base_embeddings_callable. The __call__ method should accept input data and return embeddings as a list of numpy arrays (or compatible format that will be normalized). The returned embeddings are automatically normalized and validated.

Notes

  • All config fields are optional unless marked as Required
  • API keys can typically be provided via environment variables instead of config
  • Default values are shown where applicable

Conclusion

The RagTool provides a powerful way to create and query knowledge bases from various data sources. By leveraging Retrieval-Augmented Generation, it enables agents to access and retrieve relevant information efficiently, enhancing their ability to provide accurate and contextually appropriate responses.