Build a RAG-Powered Agent

Upload documents, create a knowledge base, and build an agent that answers questions from your own data. Time: ~20 minutes.

What You Will Build

A knowledge base with your custom documents (PDF, TXT, Markdown)
An agent that searches this knowledge base to answer questions
Retrieval-Augmented Generation (RAG) pipeline from scratch
Configurable chunking and similarity search

What is RAG?

Retrieval-Augmented Generation (RAG) is a technique where an AI agent first retrieves relevant documents from a knowledge base, then uses that context to generate accurate, grounded answers. This prevents hallucination and keeps responses tied to your actual data.

Prerequisites

ACP running locally or on a server (see Getting Started)
An API key (from Settings → API Keys)
At least one document file (PDF, TXT, or MD) with your content

Step-by-Step Guide

Create a Knowledge Collection

A collection is a container for related documents. Create one for your project.

curl -X POST http://localhost:8000/api/v1/knowledge/collections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs",
    "description": "Product documentation and user guides",
    "embedding_model": "text-embedding-3-small"
  }'

# Response:
# { "id": "col_abc123", "name": "product-docs", "document_count": 0 }

Upload Documents

Upload PDF, TXT, or Markdown files. Fluxgate automatically chunks them and creates embeddings.

# Upload a PDF
curl -X POST http://localhost:8000/api/v1/knowledge/collections/col_abc123/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@user-guide.pdf"

# Upload a text file
curl -X POST http://localhost:8000/api/v1/knowledge/collections/col_abc123/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@faq.txt"

# Upload Markdown
curl -X POST http://localhost:8000/api/v1/knowledge/collections/col_abc123/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@troubleshooting.md"

Verify Document Processing

Check that all documents have been chunked and indexed.

curl http://localhost:8000/api/v1/knowledge/collections/col_abc123/documents \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# { "documents": [
#   { "id": "doc_1", "filename": "user-guide.pdf", "chunks": 42, "status": "indexed" },
#   { "id": "doc_2", "filename": "faq.txt", "chunks": 15, "status": "indexed" },
#   { "id": "doc_3", "filename": "troubleshooting.md", "chunks": 23, "status": "indexed" }
# ]}

Test Knowledge Search

Before creating the agent, test that search returns relevant results.

curl -X POST http://localhost:8000/api/v1/knowledge/collections/col_abc123/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How do I reset my password?", "top_k": 3 }'

# Response:
# { "results": [
#   { "content": "To reset your password, go to Settings...", "score": 0.92, "source": "faq.txt" },
#   { "content": "Password requirements include...", "score": 0.78, "source": "user-guide.pdf" }
# ]}

Create the RAG Agent

Create an agent that uses the knowledge base as its primary source of truth.

curl -X POST http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rag-assistant",
    "description": "RAG-powered assistant that answers from product documentation",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful product assistant. Always search the knowledge base first to answer questions. Base your answers on the retrieved documents. If the knowledge base does not contain the answer, say so clearly rather than guessing.",
    "knowledge_collection_id": "col_abc123",
    "tags": ["rag", "documentation"]
  }'

# Save the agent ID from the response

Set a Budget Limit

Protect against unexpected costs while testing.

curl -X POST http://localhost:8000/api/v1/budgets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rag-budget",
    "agent_id": "AGENT_ID",
    "period": "daily",
    "limit_usd": 10,
    "action_on_exceed": "alert_only"
  }'

Run Your RAG Agent

Test the agent with questions your documents can answer.

curl -X POST http://localhost:8000/api/v1/agents/AGENT_ID/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "How do I reset my password?" }'

# The agent will:
# 1. Search the knowledge base for relevant chunks
# 2. Use those chunks as context
# 3. Generate an answer grounded in your documentation

Iterate and Improve

Upload more documents, refine the system prompt, and adjust chunking settings.

# Update chunking settings for better results
curl -X PUT http://localhost:8000/api/v1/knowledge/collections/col_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_size": 512,
    "chunk_overlap": 50
  }'

Using the Dashboard Instead

You can do all of the above through the dashboard UI:

Go to the Knowledge Base tab
Click Create Collection and name it
Drag and drop your files into the upload area
Wait for processing to complete (status turns green)
Go to the Agents tab and click Create Agent
Select your knowledge collection in the agent config
Test the agent using the Chat tab

Best Practices

Keep documents focused on a single topic for better retrieval
Use a chunk size of 256-512 tokens for most use cases
Add a chunk overlap of 20-50 tokens to avoid cutting sentences
Test with real questions your users would ask
Monitor retrieval scores to identify low-quality matches

Support Agent

Multi-Agent