> ## Documentation Index
> Fetch the complete documentation index at: https://spacesail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Search & Retrieval
> Understand how agents intelligently search and retrieve information from knowledge bases to provide accurate, contextual responses.
When an agent needs information to answer a question, it doesn't dump everything into the prompt. Instead, it searches for just the most relevant pieces. This focused approach is what makes knowledge-powered agents both effective and efficient—they get exactly what they need, when they need it.
## How Agents Search Knowledge
Think of an agent's search process like a skilled researcher who knows what to look for and where to find it:
The agent analyzes the user's question to understand what type of
information would be helpful.
Based on the analysis, the system formulates one or more searches (vector,
keyword, or hybrid).
The knowledge base returns the most relevant content chunks.
The retrieved information is combined with the original question to generate
a comprehensive response.
## Agentic Search: The Smart Difference
What makes Agno's approach special? Agents can programmatically decide when to search and how to use results. Think of it as giving your agent the keys to the library instead of handing it a fixed stack of books. You can even plug in custom retrieval logic to match your specific needs.
**Key capabilities:**
* **Automatic Decision Making** - The agent can choose to search when it needs additional information—or skip it when not necessary.
* **Smart Query Generation** - Implement logic to reformulate queries for better recall—like expanding "vacation" to include "PTO" and "time off."
* **Multi-Step Search** - If the first search isn't enough, run follow-up searches with refined queries.
* **Context Synthesis** - Combine information from multiple results to produce a thorough, grounded answer.
### Traditional RAG vs. Agentic RAG
Here's how they compare in practice:
```python theme={null}
# Static approach - always searches with the exact user query
user_query = "What's our return policy?"
results = vector_db.search(user_query, limit=5)
response = llm.generate(user_query + "\n" + "\n\n".join([d.content for d in results]))
```
```python theme={null}
from agno.agent import Agent
# Agent with knowledge configured (see configuration below)
user_query = "What's our return policy?"
# Agent fetches relevant docs when needed
docs = await agent.aget_relevant_docs_from_knowledge(
query=user_query,
num_documents=5,
filters=None,
)
context = "\n\n".join([d["content"] for d in docs]) if docs else ""
answer = await agent.run(user_query, context=context)
```
## Configuring Search in Agno
You configure search behavior on your vector database, and Knowledge uses those settings when retrieving documents. It's a simple setup:
```python theme={null}
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.reranker.cohere import CohereReranker
from agno.vectordb.pgvector import PgVector
from agno.vectordb.search import SearchType
vector_db = PgVector(
table_name="embeddings_table",
db_url=db_url,
# Choose the search strategy per your use case
search_type=SearchType.hybrid, # vector | keyword | hybrid
# Optional: add a reranker for higher quality ordering
reranker=CohereReranker(),
)
knowledge = Knowledge(
vector_db=vector_db,
max_results=5, # default retrieval size
)
```
### Types of Search Strategies
Agno gives you three main approaches. Pick the one that fits your content and how users ask questions:
#### Vector Similarity Search
Finds content by meaning, not just matching words. When you ask "How do I reset my password?", it finds documents about "changing credentials" even though the exact words don't match.
**How it works:**
* Your query becomes a vector (list of numbers capturing meaning)
* The system finds content with similar vectors
* Results are ranked by how close the meanings are
**Best for:** Conceptual questions where users might phrase things differently than your docs.
#### Keyword Search
Classic text search—looks for exact words and phrases in your content. When using PgVector, this leverages Postgres's full-text search under the hood.
**How it works:**
* Matches specific words and phrases
* Supports search operators (where your backend allows)
* Works great when users know the exact terminology
**Best for:** Finding specific terms, product names, error codes, or technical identifiers.
#### Hybrid Search
The best of both worlds—combines semantic understanding with exact-match precision. This is usually your best bet for production.
**How it works:**
* Runs both vector similarity and keyword matching
* Merges results intelligently
* Can add a reranker on top for even better ordering
**Best for:** Most real-world applications where you want both accuracy and flexibility.
```python theme={null}
from agno.vectordb.search import SearchType
from agno.knowledge.reranker.cohere import CohereReranker
vector_db = PgVector(
table_name="embeddings_table",
db_url=db_url,
search_type=SearchType.hybrid,
reranker=CohereReranker(),
)
knowledge = Knowledge(vector_db=vector_db, max_results=5)
```
We recommend starting with hybrid search with reranking for strong
recall and precision.
## What Affects Search Quality
### Content Chunking Strategy
How you split your content matters a lot:
* **Smaller chunks** (200-500 chars): Super precise, but might miss the big picture
* **Larger chunks** (1000-2000 chars): Better context, but less targeted
* **Semantic chunking**: Splits at natural topic boundaries—usually the sweet spot
### Embedding Model Quality
Your embedder is what turns text into vectors that capture meaning:
* **General-purpose** (like OpenAI's text-embedding-3-small): Works well for most content
* **Domain-specific**: Better for specialized fields like medical or legal docs
* **Multilingual**: Essential if you're working in multiple languages
### Practical Configuration
```python theme={null}
# VectorDB controls search strategy; Knowledge controls retrieval size
vector_db = PgVector(table_name="embeddings_table", db_url=db_url, search_type=SearchType.hybrid)
knowledge = Knowledge(vector_db=vector_db, max_results=5)
```
## Making Search Work Better
### Add Rich Metadata
Metadata helps filter and organize results:
```python theme={null}
knowledge.add_content(
path="policies/",
metadata={"type": "policy", "department": "HR", "audience": "employees"},
)
```
### Use Descriptive Filenames
File names can help with search relevance in some backends:
```python theme={null}
"hr_employee_handbook_2024.pdf" # ✅ Clear and descriptive
"document1.pdf" # ❌ Generic and unhelpful
```
### Structure Content Logically
Well-organized content searches better:
* Use clear headings and sections
* Include relevant terminology naturally (don't keyword-stuff)
* Add summaries at the top of long documents
* Cross-reference related topics
### Test with Real Queries
The best way to know if search is working? Try it with actual questions:
```python theme={null}
test_queries = [
"What's our vacation policy?",
"How do I submit expenses?",
"Remote work guidelines",
]
for q in test_queries:
results = knowledge.search(q)
print(q, "->", results[0].content[:100] + "..." if results else "No results")
```
### Analyze What's Being Retrieved
Ask yourself:
* Are results actually relevant to the query?
* Is important information missing from results?
* Are results in a sensible order? (If not, try adding a reranker)
* Should you adjust chunk sizes or metadata?
## Advanced Search Features
### Custom Retrieval Logic for Agents
Provide a `knowledge_retriever` callable to implement your own decisioning (e.g., reformulation, follow-up searches, domain rules). The agent will call this when fetching documents.
```python theme={null}
async def my_retriever(query: str, num_documents: int = 5, filters: dict | None = None, **kwargs):
# Example: reformulate query, then search with metadata filters
refined = query.replace("vacation", "paid time off")
docs = await knowledge.async_search(refined, max_results=num_documents, filters=filters)
return [d.to_dict() for d in docs]
agent.knowledge_retriever = my_retriever
```
### Search with Filtering
Restrict results to subsets based on metadata you stored with documents.
```python theme={null}
results = knowledge.search(
"deployment process",
filters={"department": "engineering", "type": "documentation"},
)
```
### Working with Different Content Types
Use appropriate readers; they handle parsing their formats.
```python theme={null}
from agno.knowledge.reader.pdf_reader import PdfReader
# Add a directory of PDFs using the PDF reader
knowledge.add_content(path="presentations/", reader=PdfReader())
```
## Best Practices for Search & Retrieval
### Content Strategy
* Organize logically; group related content
* Use consistent terminology
* Include context and cross-references
* Keep content current; retire outdated docs
### Technical Optimization
* Choose appropriate chunk sizes and strategies
* Select a quality embedder for your domain
* Configure VectorDB search type (vector/keyword/hybrid)
* Add a reranker for better ordering
### Monitoring and Improvement
* Test with real user queries regularly
* Observe what agents retrieve
* Gather feedback when answers lack context
* Iterate on chunking, metadata, and search configuration
## Next Steps
Learn how content metadata is tracked and managed
Explore storage options for your knowledge base
Deep dive into advanced search strategies
Optimize your knowledge base for speed and accuracy