Knowledge Bases

Knowledge bases give agents access to your organization’s documents and data. AgentFlow provides a full document pipeline — ingestion, chunking, embedding, and hybrid retrieval — backed by PGVector with tenant isolation.

Creating a knowledge base

From a URL

URL imports use form data and the website_url field:

curl -X POST "https://your-instance.agentflow.ai/api/v1/knowledge-bases/create-from-url" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Product Documentation" \
  -d "description=Public product docs and API reference" \
  --data-urlencode "website_url=https://docs.example.com" \
  -d "chunk_size=1200" \
  -d "overlap_percentage=0.125" \
  -d "vector_db_type=pgvector"

From files

File uploads create a KB with multipart form data on the base knowledge-bases route:

curl -X POST "https://your-instance.agentflow.ai/api/v1/knowledge-bases" \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Product Documentation" \
  -F "description=Uploaded product guides" \
  -F "files=@./product-guide.pdf" \
  -F "files=@./release-notes.md" \
  -F "chunk_size=1200" \
  -F "overlap_percentage=0.15"

The Python SDK mirrors these flows with client.knowledge_bases.create_from_url(...) and client.knowledge_bases.create_from_files(...).

Search

Knowledge base search supports multiple retrieval strategies:

response = await client.knowledge_bases.search(
    "kb_abc123",
    query="How do I configure SSO?",
    limit=10,
    search_type="hybrid",           # "semantic", "keyword", or "hybrid"
    vector_weight=0.7,              # Hybrid vector contribution
    keyword_weight=0.3,             # Hybrid keyword contribution
    enable_mmr=True,                # Maximal Marginal Relevance for diversity
    mmr_lambda=0.5,                 # Balance: 1.0 = relevance, 0.0 = diversity
    neighboring_chunks_count=1,     # Include adjacent chunks for context
)

for document in response.documents:
    metadata = document.metadata or {}
    score = getattr(document, "score", None) or metadata.get("score")
    print(f"Score: {score} | Source: {document.source_file}")
    print(f"  {document.content[:200]}...")

Search responses return documents, total_results, and search_metadata.

Canonical search fields

Field	Description
`query`	Required search text
`limit`	Maximum number of documents to return
`search_type`	`semantic`, `keyword`, or `hybrid`
`vector_weight`	Hybrid vector weight, from `0.0` to `1.0`
`keyword_weight`	Hybrid keyword weight, from `0.0` to `1.0`
`metadata_filters`	Structured metadata filters for narrowing results
`similarity_threshold`	Minimum similarity score before a document is returned
`enable_mmr`	Enable Maximal Marginal Relevance diversity filtering
`mmr_lambda`	MMR balance: `1.0` favors relevance, `0.0` favors diversity
`enable_surrounding_chunks`	Include neighboring chunks around each match
`neighboring_chunks_count`	Number of adjacent chunks to include around each match
`enable_query_rewrite`	Rewrite the query before retrieval when enabled
`enable_query_expansion`	Expand the query before retrieval when enabled
`enable_hyde`	Generate a hypothetical answer to improve semantic retrieval
`alpha`	Hybrid search alpha value; `vector_weight` is the SDK-friendly alias
`rrf_k`	Reciprocal-rank-fusion constant for hybrid result merging
`freshness_boost`	Boost newer chunks when freshness should influence ranking
`freshness_half_life_days`	Half-life window used by freshness boosting
`title_alpha`	Boost chunks whose source title matches the query
`field_alphas`	Per-field weighting for metadata-aware ranking
`rerank`	Enable reranking when supported by the KB configuration
`conversation_id`	Optional conversation context identifier for search telemetry
`filters_sql`	Deprecated and rejected; use `metadata_filters` instead

SQL-like filter strings are intentionally unsupported; use structured metadata fields instead.

Search strategies

Strategy	What it does
Semantic	Embedding-based similarity search using PGVector
Keyword	BM25-style keyword matching
Hybrid	Combines semantic and keyword retrieval with `vector_weight` and `keyword_weight`
MMR	Maximal Marginal Relevance — balances relevance with result diversity
Neighboring chunks	Adds adjacent chunks so cited text keeps nearby context

Binding knowledge bases to agents

Knowledge bases become part of an agent’s context when bound:

from agentflow import AsyncAgentFlow, RunOptions

async with AsyncAgentFlow.from_profile("local") as client:
    agent_id = {agent.name: agent.id for agent in await client.agents.list()}["SupportAgent"]
    kbs = await client.agents.knowledge_bases.list(agent_id)

    # Agent can use assigned KBs during conversations.
    response = await client.agents.run(
        agent_id=agent_id,
        message="How do I configure SSO?",
        options=RunOptions(knowledge_bases=[kbs[0].id]),
    )

    # Search a specific KB through the agent.
    response = await client.agents.knowledge_bases.search(
        agent_id,
        kbs[0].id,
        query="SSO configuration",
        limit=5,
    )

    for document in response.documents:
        print(document.content[:200])

You can also pass knowledge base IDs per-request for ad-hoc retrieval:

POST /api/v1/agent/{agent_id}/chat
{
  "message": "How do I configure SSO?",
  "conversation_id": "conv_001",
  "message_id": "msg_001",
  "knowledge_bases": ["550e8400-e29b-41d4-a716-446655440000"],
  "stream": true
}

Configuration

Chunking

Parameter	Default	Description
`chunk_size`	1200	Maximum tokens per chunk
`overlap_percentage`	0.15	Overlap between consecutive chunks (0.0–1.0)
`chunking_strategy`	auto	Strategy for splitting documents

Vector storage

AgentFlow uses PGVector for vector storage with:

Tenant-scoped collections for data isolation
HNSW indexing for fast approximate nearest neighbor search
Configurable embedding models

Knowledge base lifecycle

# Create from files
POST /api/v1/knowledge-bases

# Create from URL
POST /api/v1/knowledge-bases/create-from-url

# List all knowledge bases
GET /api/v1/knowledge-bases

# Get KB details
GET /api/v1/knowledge-bases/{kb_id}

# Search
POST /api/v1/knowledge-bases/{kb_id}/search

# Get files in a KB
GET /api/v1/knowledge-bases/{kb_id}/files

# Get documents (chunks)
GET /api/v1/knowledge-bases/{kb_id}/documents

# Get summary / stats
GET /api/v1/knowledge-bases/{kb_id}/summary

# Update KB metadata
PUT /api/v1/knowledge-bases/{kb_id}

# Refresh / re-index
POST /api/v1/knowledge-bases/{kb_id}/refresh

# Delete a document
DELETE /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}

# Delete the KB
DELETE /api/v1/knowledge-bases/{kb_id}

Agent-scoped KB endpoints

# List KBs bound to an agent
GET /api/v1/agents/{agent_id}/knowledge-bases

# Bind a KB to an agent
POST /api/v1/agents/{agent_id}/knowledge-bases/{kb_id}

# Unbind a KB from an agent
DELETE /api/v1/agents/{agent_id}/knowledge-bases/{kb_id}

# Search a specific KB through an agent
POST /api/v1/agents/{agent_id}/knowledge-bases/{kb_id}/search

​Knowledge Bases

​Creating a knowledge base

​From a URL

​From files

​Search

​Canonical search fields

​Search strategies

​Binding knowledge bases to agents

​Configuration

​Chunking

​Vector storage

​Knowledge base lifecycle

​Agent-scoped KB endpoints