home / skills / sstobo / convex-skills / convex-agents-rag

convex-agents-rag skill

safe

This skill enables agents to search knowledge bases and ground responses with retrieval augmented generation for accurate, contextually grounded answers.

npx playbooks add skill sstobo/convex-skills --skill convex-agents-rag

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.6 KB

---
name: "Convex Agents RAG"
description: "Implements Retrieval-Augmented Generation (RAG) patterns to enhance agents with custom knowledge bases. Use this when agents need to search through documents, retrieve context from a knowledge base, or ground responses in specific data."
---

## 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`:

```typescript
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:

```typescript
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:

```typescript
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

Overview

This skill implements Retrieval-Augmented Generation (RAG) patterns to enhance agents with searchable, custom knowledge bases. It helps agents ground responses in specific documents and reduce hallucinations by combining semantic search with LLM generation. Use it to add contextual retrieval and namespace isolation for user- or team-specific data.

How this skill works

The skill ingests documents into namespaced stores and creates vector and text indexes for hybrid search. Agents query the RAG component to retrieve relevant passages, then augment prompts with retrieved context before generating a final response. Filtering, limits, and namespace isolation let you control scope and precision of retrieved content.

When to use it

When agents must reference product docs, policies, or any specific corpus to answer accurately.
To build support systems, FAQs, or documentation assistants that require grounded answers.
When you need semantic search across custom content rather than keyword matching.
To reduce hallucinations by constraining generation to known information.
When managing multi-tenant data using isolated namespaces for users or teams.

Best practices

Organize content into namespaces like user:userId or team:teamId to prevent cross-tenant leaks.
Combine vector search with text filters (hybrid search) to balance relevance and precision.
Limit retrieved passages and preformat context to keep prompts concise and focused.
Apply filterNames or metadata filters to target specific documents or file types.
Periodically re-ingest or re-index updated documents to keep results current.

Example use cases

Answering customer support queries by retrieving product manual excerpts and generating step-by-step guidance.
Generating policy-compliant responses by grounding agent replies in an organization’s policy documents.
Creating a searchable internal knowledge assistant that returns concise, sourced answers from team docs.
Powering an FAQ bot that combines semantic search with generation to handle follow-up questions.
Providing personalized assistant behavior by storing and retrieving user-specific notes or preferences.

FAQ

How do I prevent documents from being visible across users?

Use namespaces such as user:userId or team:teamId and store content under those namespaces to isolate access.

What retrieval strategy yields the best results?

Start with a hybrid approach: vector similarity for semantic matches plus text/metadata filters to improve precision; tune limit and filter parameters for your corpus.