convex-agents-rag

Purpose

Enables agents to search through custom content and knowledge bases to provide accurate, context-grounded responses. RAG combines LLM capabilities with semantic search.

When to Use This Skill

• Agents need to reference a knowledge base or document collection
• Grounding answers in specific data (policies, product docs, etc.)
• Semantic search across custom content
• Building a search + generation system (FAQ, documentation, support)
• Reducing hallucinations by constraining responses to known information
• Managing user-specific or team-specific knowledge namespaces

Setup

Install and configure RAG in your convex.config.ts:

import { defineApp } from "convex/server";
import agent from "@convex-dev/agent/convex.config";
import rag from "@convex-dev/rag/convex.config";

const app = defineApp();
app.use(agent);
app.use(rag);

export default app;

Add Content

Ingest documents into a namespace:

import { rag } from "@convex-dev/rag";

export const addContent = action({
  args: { userId: v.string(), key: v.string(), text: v.string() },
  handler: async (ctx, { userId, key, text }) => {
    const namespace = `user:${userId}`;
    await rag.addContent(ctx, components.rag, {
      namespace,
      key,
      text,
      filters: { filterNames: [filename] },
    });
  },
});

Search and Generate

Use RAG with agents:

export const answerWithContext = action({
  args: { threadId: v.string(), userId: v.string(), question: v.string() },
  handler: async (ctx, { threadId, userId, question }) => {
    const { thread } = await myAgent.continueThread(ctx, { threadId });

    const context = await rag.search(ctx, components.rag, {
      namespace: `user:${userId}`,
      query: question,
      limit: 10,
    });

    const augmentedPrompt = `# Context:\n\n${context.text}\n\n# Question:\n\n${question}`;
    const result = await thread.generateText({ prompt: augmentedPrompt });

    return result.text;
  },
});

Key Principles

• Namespaces isolate data: Use user:userId or team:teamId for multi-tenant safety
• Hybrid search: Combine text and vector search for better results
• Filtering: Use filterNames to target specific documents

Next Steps

• See fundamentals for basic agent setup
• See context for advanced context customization