Filtering

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

These fragments use an initialized knowledge object and existing local documents. Follow Knowledge Quickstart for setup.

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

# Add content with metadata
knowledge.insert(
    path="resumes/",
    metadata={"candidate": "jordan_mitchell", "document_type": "cv", "year": 2025}
)

# Search with filters
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    knowledge_filters={"candidate": "jordan_mitchell"},
)

Why Use Filters

• Personalization: Retrieve documents for a specific candidate or group
• Organization: Select content by department or document type
• Precision: Reduce noise by narrowing results to relevant documents

Manual Filtering

Pass filters explicitly when creating the agent or searching:

# Filter at agent level
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    knowledge_filters={"candidate": "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={"candidate": "jordan_mitchell", "year": 2025}
)

Multiple filters are combined with AND logic. Run-level dictionary filters override agent-level values for the same key.

Metadata filters select retrieval results; they do not authenticate a requester or enforce ownership. Native content ownership uses Knowledge.insert(user_id=...) and the separate user_id search argument, supplied from a trusted identity. See User Isolation for the AgentOS boundary.

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 a candidate 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

Traditional vs Agentic RAG

Filters work with both RAG approaches:

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

# Always inject context into prompt
agent = Agent(
    knowledge=knowledge,
    search_knowledge=False,
    add_knowledge_to_context=True,
    knowledge_filters={"candidate": "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 = {
    "candidate": "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
• Keep metadata categories separate from trusted authorization rules

Supported Vector Databases

Filtering is supported on:

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

Next Steps