Knowledge Filters

Filter knowledge base searches using static filters or agentic filters.

knowledge_filters.py
"""
Knowledge Filters
=============================

Filter knowledge base searches using static filters or agentic filters.

Static filters are set at agent creation time and apply to every search.
Agentic filters let the agent dynamically choose filter values at runtime.
"""

from agno.agent import Agent
from agno.filters import EQ
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.models.openai import OpenAIResponses
from agno.vectordb.pgvector import PgVector, SearchType

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
knowledge = Knowledge(
    vector_db=PgVector(
        table_name="recipes_filters_demo",
        db_url=db_url,
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

# ---------------------------------------------------------------------------
# Create Agent With Static Filters
# ---------------------------------------------------------------------------
# Static filters: only retrieve documents matching these criteria
agent_static = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    knowledge=knowledge,
    search_knowledge=True,
    # Use FilterExpr objects for type-safe filtering
    knowledge_filters=[EQ("cuisine", "thai")],
    markdown=True,
)

# ---------------------------------------------------------------------------
# Create Agent With Agentic Filters
# ---------------------------------------------------------------------------
# Agentic filters: the agent decides filter values dynamically
agent_agentic = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    knowledge=knowledge,
    search_knowledge=True,
    # Let the agent choose filter values based on the user's query
    enable_agentic_knowledge_filters=True,
    markdown=True,
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    knowledge.insert(url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf")

    print("--- Static filters (cuisine=thai) ---")
    agent_static.print_response(
        "What soup recipes do you have?",
        stream=True,
    )

    print("\n--- Agentic filters ---")
    agent_agentic.print_response(
        "Find me a Thai dessert recipe.",
        stream=True,
    )

Index the filter metadata

Before running, replace the knowledge construction with this version. It uses a fresh vector table and a content catalog so the agent can discover filter keys:

from agno.db.sqlite import SqliteDb

knowledge = Knowledge(
    content_db=SqliteDb(db_file="tmp/knowledge_filters_contents.db"),
    vector_db=PgVector(
        table_name="recipes_filters_labelled_demo",
        db_url=db_url,
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

Replace the insertion inside if __name__ == "__main__": with:

knowledge.insert(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    metadata={"cuisine": "thai"},
)

The archived insertion supplies no cuisine value, so it cannot satisfy EQ("cuisine", "thai"). Re-ingest into the fresh table and catalog before either agent runs; existing unlabelled chunks will not gain metadata merely by changing the filter. These filters select retrieval results; enforce access permissions separately.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno "psycopg[binary]" beautifulsoup4 openai pgvector pypdf sqlalchemy

Export your OpenAI API key

export OPENAI_API_KEY="your_openai_api_key_here"

Run PgVector

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

Run the example

Save the code above as knowledge_filters.py, then run:

python knowledge_filters.py

Full source: cookbook/02_agents/07_knowledge/knowledge_filters.py