Knowledge / RAG

Knowledge lets an agent find relevant passages in your documents before it answers. Use it for policies, manuals, FAQs, product documentation, and other narrative material. If the agent must filter exact fields or look up records by ID, use a Knowledge Graph instead.

How it works

• Create a knowledge base and upload documents to it.
• SyntheticBrew splits and indexes each uploaded document automatically. No restart or manual indexing step is required.
• Link one or more knowledge bases to an agent, and add the Knowledge capability to that agent. The capability automatically injects a knowledge_search tool — you do not assign the tool manually.
• When the agent calls knowledge_search, SyntheticBrew runs a vector similarity search across the agent’s linked knowledge bases and returns the most relevant passages.
• The agent uses those passages as context for its response. Test the result and keep instructions explicit; retrieval reduces unsupported answers but does not guarantee correctness.

# Indexing + retrieval flow:
#
#   Upload faq.md, returns-policy.pdf  --> indexed automatically
#
#   Agent (with the Knowledge capability + a linked KB) calls
#     knowledge_search("return policy for electronics")
#   --> SyntheticBrew finds the most relevant passages from returns-policy.pdf
#   --> Agent answers: "Our electronics return policy..."

What happens to an upload

SyntheticBrew keeps the indexed passages and the original file name, but it does not keep a downloadable copy of the uploaded file. Keep your source document in your own document or source-control system.

• Indexing starts automatically. The file shows indexing, then ready or error, in Admin and the files API.
• There is no re-index action. To update a document, delete its existing file entry and upload the new version. Uploading the same file name again without deleting the old entry creates another document; it does not overwrite the first one.
• Changing the embedding model does not update existing documents. Delete and upload the affected documents again so they are indexed by the new model.

Supported files

Upload .txt, .md, .csv, .pdf, and .docx files up to 50 MB through Admin or the API. They are indexed automatically; no service restart is needed.

Isolation

Each knowledge base is independent, and an agent searches only the knowledge bases linked to it. Link sales materials to the sales agent and HR policies to the HR agent, and neither can read the other’s documents — useful for multi-tenant and role-based setups. One knowledge base can be linked to multiple agents, and one agent can use multiple knowledge bases.

Best practices

• Keep documents focused — smaller, topic-specific documents work better than large monolithic ones.
• Use clear headings — Markdown headings help the chunking algorithm split documents at logical boundaries.
• Update regularly — keep knowledge bases current. Delete an outdated file entry before uploading its replacement so the agent does not search both versions.
• Tell the agent to cite sources — add instructions in the system prompt to reference which document the answer came from.
• Set honest boundaries — instruct the agent to say “I don’t know” rather than hallucinate when the knowledge base does not contain the answer.

Setting up knowledge

Admin Dashboard

1. Go to Knowledge in the sidebar and create a knowledge base (give it a name and an embedding model).
2. Upload .txt, .md, .csv, .pdf, or .docx files. Each file indexes automatically; wait for its status to reach ready.
3. On the Knowledge page, link the knowledge base to the agent.
4. Open the agent, add and enable the Knowledge capability, choose Top-K and similarity threshold values, and save.

knowledge_search is now available to the agent, scoped to its linked knowledge bases.

API

# Create a knowledge base
curl -X POST "$SYNTHETICBREW_URL/api/v1/knowledge-bases" \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "product-docs", "description": "Product documentation", "embedding_model_id": "your-embedding-model"}'

# Upload a file (indexed automatically; supported: txt, md, csv, pdf, docx)
curl -X POST "$SYNTHETICBREW_URL/api/v1/knowledge-bases/product-docs/files" \
  -H "Authorization: Bearer bb_your_token" \
  -F "file=@./docs/faq.md"

# List files and watch indexing status (uploading -> indexing -> ready)
curl "$SYNTHETICBREW_URL/api/v1/knowledge-bases/product-docs/files" \
  -H "Authorization: Bearer bb_your_token"

# Link a knowledge base to an agent (the agent also needs the Knowledge capability)
curl -X POST "$SYNTHETICBREW_URL/api/v1/knowledge-bases/product-docs/agents/sales-bot" \
  -H "Authorization: Bearer bb_your_token"

# To update a document, delete its existing file entry, then upload the
# replacement. Uploading the same name twice creates two document entries.

---

What’s next

• Agents & Lifecycle
• Tools
• Schemas