Vector Search

Vector search compares an embedded query with the embeddings stored for knowledge documents.

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="docs",
        db_url=db_url,
        search_type=SearchType.vector,
    ),
)

How It Works

The embedder converts the query to a vector.
The vector database compares it with stored document vectors.
The database orders results using its configured distance metric.

PgVector uses cosine distance by default. It also supports L2 distance and maximum inner product.

When to Use Vector Search

Query Pattern	Why Test Vector Search
Conceptual questions	Embedding similarity can retrieve related language
Natural-language queries	The query and documents use the same embedding space
Varied vocabulary	Relevant documents may use different terms than the query

Test hybrid or keyword search when specific tokens such as IDs and error codes affect relevance.

Configuration

Basic Setup

Set the API key used by OpenAIEmbedder:

export OPENAI_API_KEY=your_openai_api_key_here

from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.vectordb.pgvector import PgVector, SearchType

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

With Reranking

Set the API keys used by the default OpenAI embedder and Cohere reranker:

export OPENAI_API_KEY=your_openai_api_key_here
export COHERE_API_KEY=your_cohere_api_key_here

Pass CohereReranker to Knowledge to reorder the vector-search candidates:

from agno.knowledge.knowledge import Knowledge
from agno.knowledge.reranker.cohere import CohereReranker
from agno.vectordb.pgvector import PgVector, SearchType

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="docs",
        db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        search_type=SearchType.vector,
    ),
    reranker=CohereReranker(),
)

See Reranking for candidate pool sizing.

Example

Install dependencies

uv pip install -U agno cohere openai pgvector psycopg pypdf sqlalchemy

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

Export the OpenAI API key

export OPENAI_API_KEY=your_openai_api_key_here

from agno.knowledge.embedder.openai import OpenAIEmbedder
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="recipes",
        db_url=db_url,
        search_type=SearchType.vector,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

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

results = knowledge.search("chicken coconut soup", max_results=5)
for doc in results:
    print(doc.content[:200])