Filtering

Filters restrict knowledge searches to documents matching specific criteria. Attach metadata when adding content, then filter by that metadata when searching.

from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge


def create_filtered_agent(knowledge: Knowledge) -> Agent:
    knowledge.insert(
        path="resumes/",
        metadata={"user_id": "jordan_mitchell", "document_type": "cv", "year": 2025},
    )
    return Agent(
        knowledge=knowledge,
        search_knowledge=True,
        knowledge_filters={"user_id": "jordan_mitchell"},
    )

Pass a configured Knowledge instance backed by a vector database that supports metadata filtering.

Why Use Filters

Personalization: Retrieve documents for a specific user or group
Tenant scoping: Apply trusted server-side filters before each search
Precision: Reduce noise by narrowing results to relevant documents

Treat knowledge filters as retrieval constraints. Enforce authorization separately. Run-level knowledge_filters can replace agent defaults. Derive authorization filters in trusted server code and prevent untrusted clients from supplying replacements.

Manual Filtering

Pass filters explicitly when creating the agent or searching:

# Filter at agent level
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    knowledge_filters={"user_id": "jordan_mitchell"},
)

# Filter at query time
agent.print_response(
    "What are Jordan's skills?",
    knowledge_filters={"document_type": "cv"}
)

# Direct search with filters
results = knowledge.search(
    query="programming experience",
    filters={"user_id": "jordan_mitchell", "year": 2025}
)

Keys within one dictionary filter are combined with AND logic.

Agentic Filtering

Let the agent extract filters automatically from the query. The agent analyzes the user’s question and determines which filters to apply.

agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    enable_agentic_knowledge_filters=True,  # Agent infers filters from query
)

# Agent extracts "jordan_mitchell" as user filter from the query
agent.print_response("What skills does Jordan Mitchell have?")

This requires a Contents DB to track available filter keys.

Manual vs Agentic Filtering

Approach	When to Use
Manual	Automation, predictable filters, full control
Agentic	User-facing apps, natural language queries

Traditional vs Agentic RAG

Filters work with both RAG approaches:

Agentic RAG
Traditional RAG

# Agent decides when to search (default)
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    knowledge_filters={"user_id": "jordan_mitchell"},
)

# Always inject context into prompt
agent = Agent(
    knowledge=knowledge,
    search_knowledge=False,
    add_knowledge_to_context=True,
    knowledge_filters={"user_id": "jordan_mitchell"},
)

Use one approach at a time. Agentic RAG (search_knowledge=True) is recommended for most use cases.

Metadata Design

Good metadata enables effective filtering:

# Rich, filterable metadata
metadata = {
    "user_id": "jordan_mitchell",
    "document_type": "cv",
    "department": "engineering",
    "year": 2025,
    "access_level": "internal",
}

# Add with content
knowledge.insert(path="resume.pdf", metadata=metadata)

Tips:

Use consistent values (always "engineering", not sometimes "eng")
Include temporal data for time-based filtering
Add scope metadata for trusted server-side filtering

Supported Vector Databases

Filtering is supported on:

ChromaDB
Couchbase
LanceDB
Milvus
MongoDB
PgVector
Pinecone
Qdrant
SurrealDB
Upstash
Valkey
Weaviate

Next Steps

Advanced Filtering

Complex filters with OR, NOT, and comparisons

Content DB

Required for agentic filtering

Search & Retrieval

How filtering affects search

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Why Use Filters

Manual Filtering

Agentic Filtering

Manual vs Agentic Filtering

Traditional vs Agentic RAG

Metadata Design

Supported Vector Databases

Next Steps

Advanced Filtering

Content DB

Search & Retrieval

​Why Use Filters

​Manual Filtering

​Agentic Filtering

​Manual vs Agentic Filtering

​Traditional vs Agentic RAG

​Metadata Design

​Supported Vector Databases

​Next Steps

Advanced Filtering

Content DB

Search & Retrieval

Why Use Filters

Manual Filtering

Agentic Filtering

Manual vs Agentic Filtering

Traditional vs Agentic RAG

Metadata Design

Supported Vector Databases

Next Steps