Skip to main content
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:
1

Query Analysis

The agent analyzes the user’s question to understand what type of information would be helpful.
2

Search Strategy

Based on the analysis, the system formulates one or more searches (vector, keyword, or hybrid).
3

Information Retrieval

The knowledge base returns the most relevant content chunks.
4

Context Integration

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:
  • Traditional RAG
  • Agentic RAG
# 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]))

​
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: 
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: 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. 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. 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. 
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

# 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: 
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: 
"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: 
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. 
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

When agents search through knowledge bases, sometimes you need more control than just “find similar content.” Maybe you want to search only within specific documents, exclude outdated information, or focus on content from particular sources. That’s where filtering comes in—it lets you precisely target which content gets retrieved. Think of filtering like adding smart constraints to a library search. Instead of searching through every book, you can tell the librarian: “Only look in the science section, published after 2020, but exclude textbooks.” Knowledge filtering works the same way—you specify criteria based on the metadata attached to your content.
1

Metadata Assignment

When you add content, attach metadata like department, document type, date, or any custom attributes.
2

Filter Construction

Build filters using dictionary format or filter expressions to define your search criteria.
3

Targeted Search

The knowledge base only searches through content that matches your filter conditions.
4

Contextual Results

You get precisely the information you need from exactly the right sources.

​
Basic Dictionary Filters

The simplest way to filter is using dictionary format. All conditions are combined with AND logic: 
# Filter by single field
results = knowledge.search(
    "deployment process",
    filters={"department": "engineering"}
)

# Filter by multiple fields (all must match)
results = knowledge.search(
    "deployment process",
    filters={"department": "engineering", "type": "documentation", "status": "published"}
)

# Use with agents
agent.print_response(
    "What's our deployment process?",
    knowledge_filters=[{"department": "engineering", "type": "documentation"}]
)

​
Working with Metadata

Good filtering starts with thoughtful metadata design: 
# Rich, searchable metadata
good_metadata = {
    "document_type": "policy",
    "department": "hr",
    "category": "benefits",
    "audience": "all_employees",
    "last_updated": "2024-01-15",
    "version": "2.1",
    "tags": ["health_insurance", "401k", "vacation"],
    "sensitivity": "internal"
}

# Sparse, hard to filter metadata
poor_metadata = {
    "type": "doc",
    "id": "12345"
}
Metadata Best Practices:
  • Be Consistent: Use standardized values (e.g., always “hr” not sometimes “HR” or “human_resources”)
  • Think Hierarchically: Use nested categories when appropriate (department.team, location.region)
  • Include Temporal Data: Add dates, versions, or other time-based metadata for lifecycle management
  • Add Semantic Tags: Include searchable tags or keywords that might not appear in the content
Dynamic Metadata Assignment: Add metadata programmatically based on content: 
from datetime import datetime

def assign_metadata(file_path: str) -> dict:
    """Generate metadata based on file characteristics."""
    metadata = {}

    # Extract from filename
    if "policy" in file_path.lower():
        metadata["document_type"] = "policy"
    elif "guide" in file_path.lower():
        metadata["document_type"] = "guide"

    # Extract department from path
    if "/hr/" in file_path:
        metadata["department"] = "hr"
    elif "/engineering/" in file_path:
        metadata["department"] = "engineering"

    # Add timestamp
    metadata["indexed_at"] = datetime.now().isoformat()

    return metadata

# Use when adding content
for file_path in document_files:
    knowledge.add_content(
        path=file_path,
        metadata=assign_metadata(file_path)
    )
For advanced filtering with complex logical conditions (OR, NOT, comparisons), see Advanced Filtering.

​
Working with Different Content Types

Use appropriate readers; they handle parsing their formats. 
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

Advanced Filtering

Use filter expressions for complex logical conditions

Content Database

Learn how content metadata is tracked and managed

Vector Databases

Explore storage options for your knowledge base

Hybrid Search

Deep dive into advanced search strategies

Performance Tips

Optimize your knowledge base for speed and accuracy