Skip to main content
Give your agents access to documents for retrieval-augmented generation. TurnCall supports three retrieval modes so you can choose the right strategy for your use case.

​
Retrieval Modes

ModeBehaviorBest For
promptFull document text injected into system prompt at call/chat startSmall docs (<5KB): FAQs, company info
autoPer-turn semantic search via pgvector, context injected before LLMProduct catalogs, policies
toolLLM calls query_knowledge tool when it decides to searchLarge tech docs, archives

​
Setup

1

Create a knowledge base

curl -X POST http://localhost:8090/v1/knowledge-bases \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "product-docs", "description": "Product documentation"}'
2

Upload a document

curl -X POST http://localhost:8090/v1/knowledge-bases/KB_ID/documents \
  -H "Authorization: Bearer tc_xxx" \
  -F "file=@product-catalog.pdf"
Supported file types: PDF, TXT, Markdown, DOCX, CSV, JSON, YAML, XML, TSV. Max 10 MB.
3

Link to an agent

Choose the retrieval mode that fits your content:
curl -X POST http://localhost:8090/v1/agents/AGENT_ID/knowledge-bases \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "KB_ID", "mode": "prompt"}'
Debug your knowledge base by running a test search: 
curl -X POST http://localhost:8090/v1/knowledge-bases/KB_ID/search \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the return policy?", "top_k": 3}'

​
Configuration

​
Knowledge Base Settings

FieldDefaultDescription
embedding_modeltext-embedding-3-smallOpenAI embedding model
chunk_size512Tokens per chunk
chunk_overlap64Overlap between chunks
FieldDefaultDescription
moderequiredprompt, auto, or tool
priority0Ordering when multiple KBs are linked
top_k5Number of chunks to retrieve (auto/tool)
similarity_threshold0.7Minimum cosine similarity
tool_description—Required for tool mode

​
Architecture

Upload → Extract Text (PDF/TXT/DOCX) → Chunk (token-based) → Embed (OpenAI) → Store (pgvector)

Voice: transport.input → STT → user_agg → [KnowledgeRetrievalProcessor] → LLM → TTS
Chat:  inbound message → session → [KB retrieval] → LLM completion → reply
Requires PostgreSQL with the pgvector extension: CREATE EXTENSION IF NOT EXISTS vector;