# HyDE query transform for Knowledge search

> Agno's Knowledge accepts a query_transformer that rewrites each query before the vector database sees it. HyDE, the first transformer, has a model write a short likely answer and searches with that passage.

- Published: 2026-10-08
- Author: Sannya Singal
- Categories: Changelog
- Canonical: https://www.agno.com/blog/hyde-query-transform-for-knowledge-search
- Markdown: https://www.agno.com/blog/hyde-query-transform-for-knowledge-search.md

Agno's `Knowledge(query_transformer=HyDE())` makes one model call per search, asking for a short passage that answers the question the way a reference document would. The vector database embeds that passage and looks for its neighbours.

Questions and answers rarely share wording. Ask "Why did revenue drop?" and the closest match is a policy note that says "revenue" twice, while the quarterly review that actually explains the drop talks about renewals and churn. A made-up answer reads like that review, so its embedding lands next to it. The passage never reaches the user and doesn't have to be right.

![Four steps left to right. The question Why did revenue drop? goes to HyDE, which makes one model call and writes a likely answer, Large customers delayed their renewals. The vector db embeds that answer and finds passages near it. The reranker scores each result against the question. A dashed line under the steps shows the original question going to the reranker unchanged.](https://www.agno.com/images/v3-1-2-hyde-pipeline.png)

The transform only changes what the vector database searches for. `Knowledge` hands the reranker the original question, so relevance stays tied to what the user asked. Keyword search skips the transform, because lexical matching needs every term present and a generated passage would match nothing. On a hybrid store or page storage, set `include_query=True` to search with the question followed by the passage.

```python
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.query_transformer import HyDE
from agno.models.openai import OpenAIResponses
from agno.vectordb.pgvector import PgVector

knowledge = Knowledge(
    vector_db=PgVector(table_name="docs", db_url=db_url),
    query_transformer=HyDE(model=OpenAIResponses(id="gpt-5.6-luna")),
)
```

HyDE writes with its own `model`, so a small, fast one keeps the extra call cheap. Left unset, it defaults to `OpenAIResponses(id="gpt-5.4")`. `max_characters` caps the passage at 2000 characters by default and trims at a sentence break, and a custom `prompt` must contain `{query}`. When an agent searches through its knowledge tool, the HyDE call counts toward the run's metrics.

`QueryTransformer` is the hook underneath, and you can write your own. Implement `transform(query, run_response=None)` and return the string to search with. The async `atransform` runs it off the event loop unless you override it. We had no OpenAI key, so we wrote a transformer that returns a fixed hypothetical answer in place of the model call, plus a reranker that prints the query it receives. On pgvector with a local FastEmbed embedder and the cookbook's three notes:

```python
from agno.knowledge.query_transformer import QueryTransformer
from agno.knowledge.reranker.base import Reranker

class CannedAnswer(QueryTransformer):
    def transform(self, query, run_response=None):
        return (
            "Revenue fell because several large customers delayed their renewals "
            "and more accounts churned than expected."
        )

class ShowQuery(Reranker):
    candidate_multiplier: int = 1

    def rerank(self, query, documents, limit=None):
        print(f"  reranker scores against: {query!r}")
        return documents

plain = Knowledge(vector_db=vector_db)
hyde = Knowledge(vector_db=vector_db, query_transformer=CannedAnswer(), reranker=ShowQuery())
```

```text
# real output
Searching with the question
  1. revenue-policy
  2. q3-review
  3. hiring
Searching with a hypothetical answer
  reranker scores against: 'Why did revenue drop?'
  1. q3-review
  2. revenue-policy
  3. hiring
```

The same search with `HyDE()` and no API key logged `HyDE could not generate a hypothetical answer, using the query as asked` and returned the plain ranking.

See the [cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/07_knowledge/02_building_blocks/12_hyde_query_transformer.py), and learn more about [query transformation](https://docs.agno.com/knowledge/concepts/search-and-retrieval/query-transformation) in the documentation.