Search & Retrieval

Search a knowledge base directly or give an agent a tool that searches it.

from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector, SearchType

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="embeddings",
        db_url=db_url,
        search_type=SearchType.hybrid,
    ),
    max_results=5,
)

results = knowledge.search("What is the return policy?")

How Search Works

Knowledge.search() passes the query, result limit, and filters to the configured vector database. The database returns Document objects in its ranked order. Install the PgVector example dependencies and run PostgreSQL with pgvector enabled:

uv pip install -U agno openai pgvector psycopg sqlalchemy

Search Types

Search Type	Signal	Test With
`SearchType.vector`	Distance between query and document embeddings	Conceptual queries and varied phrasing
`SearchType.keyword`	Database-specific lexical ranking	Product names, IDs, and error codes
`SearchType.hybrid`	Vector and lexical signals	Queries that contain concepts and specific terms

Search algorithms differ by vector database. Evaluate each supported search type with representative queries and expected documents.

Direct and Agentic Retrieval

Pass knowledge to an agent to register the search_knowledge_base tool. search_knowledge=True is the default.

Direct Search
Agentic RAG

results = knowledge.search(
    "What is the return policy?",
    max_results=5,
)

from agno.agent import Agent

agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
)

agent.print_response("What is the return policy?")

The model controls when and how often it calls search_knowledge_base. Set add_knowledge_to_context=True to retrieve knowledge for each string input and add the results to the model context.

Filtering Results

Filter searches by metadata:

from agno.agent import Agent

knowledge.insert(
    path="policies/",
    metadata={"department": "hr", "type": "policy", "year": 2024},
)

results = knowledge.search(
    query="vacation policy",
    filters={"department": "hr", "type": "policy"},
)

agent = Agent(knowledge=knowledge)
agent.print_response(
    "What is the vacation policy?",
    knowledge_filters={"department": "hr"},
)

For OR, NOT, and comparison operators, see Filtering.

Custom Retrieval Logic

Set knowledge_retriever to replace the default Knowledge.retrieve() path:

from typing import Optional

from agno.agent import Agent

def my_retriever(
    query: str,
    num_documents: Optional[int] = None,
    filters=None,
    **kwargs,
):
    expanded_query = query.replace("vacation", "paid time off PTO")
    docs = knowledge.search(
        expanded_query,
        max_results=num_documents,
        filters=filters,
    )
    return [doc.to_dict() for doc in docs]

agent = Agent(knowledge_retriever=my_retriever)

See Custom Retriever for accepted parameters and examples.

Retrieval Decisions

Decision	What to Evaluate
Chunking strategy	Whether each chunk contains enough context for the target questions
Embedder	Whether relevant queries and documents rank near each other
Search type	Whether vector, lexical, or combined signals match the query set
Metadata	Whether available fields support the required filters
Reranker	Whether reranking changes the top results in useful ways

Test Retrieval

Compare results with a set of queries and expected documents:

test_queries = [
    "What is the vacation policy?",
    "How do I submit expenses?",
    "Remote work guidelines",
]

for query in test_queries:
    results = knowledge.search(query)
    print(f"{query} -> {results[0].content[:100]}..." if results else "No results")

Next Steps

Hybrid Search

Configure vector and lexical retrieval signals

Filtering

Apply metadata filters to knowledge searches

Vector DB

Compare storage and search integrations

Performance Tips

Tune ingestion and retrieval settings

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Search & Retrieval

How Search Works

Search Types

Direct and Agentic Retrieval

Filtering Results

Custom Retrieval Logic

Retrieval Decisions

Test Retrieval

Next Steps

Hybrid Search

Filtering

Vector DB

Performance Tips

​How Search Works

​Search Types

​Direct and Agentic Retrieval

​Filtering Results

​Custom Retrieval Logic

​Retrieval Decisions

​Test Retrieval

​Next Steps

Hybrid Search

Filtering

Vector DB

Performance Tips

How Search Works

Search Types

Direct and Agentic Retrieval

Filtering Results

Custom Retrieval Logic

Retrieval Decisions

Test Retrieval

Next Steps