Search And Retrieval
Search & Retrieval
Search a knowledge base directly or give an agent a knowledge-search tool.
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,
)
knowledge.insert(
name="return-policy",
text_content="Unused items can be returned within 30 days with a receipt.",
)
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. If Knowledge has a query transformer, it rewrites the query first. The database returns Document objects in its ranked order. If Knowledge has a reranker, it fetches a wider candidate pool, reranks it, and returns the top max_results.
Install the PgVector example dependencies and run PostgreSQL with pgvector enabled:
uv pip install -U agno openai pgvector psycopg sqlalchemySet the OpenAI API key used by PgVector's default embedder:
export OPENAI_API_KEY="your_openai_api_key_here"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.
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 |
| Query transformer | Whether a rewritten query, such as a HyDE hypothetical answer, finds answers the question misses |
| 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
Reranking
Reorder search results with a reranker on Knowledge
Query Transformation
Search with a rewritten query, such as a HyDE hypothetical answer
Filtering
Apply metadata filters to knowledge searches
Vector DB
Compare storage and search integrations
Performance Tips
Tune ingestion and retrieval settings