A search for error code P0420 needs an exact match; a search phrased differently from a relevant document needs a match by meaning. Hybrid search uses keyword and vector search together so neither kind of query depends on the weaker method alone. In retrieval-augmented generation (RAG), it helps find passages that an agent can use as context for an answer. section 6.3.1 section 6.2.1
Think of hybrid search as two searches followed by a decision about which results to use:
- Keyword search, such as TF-IDF or BM25, favors literal terms. It is useful for names, codes, jargon, and exact phrases, but can miss related wording. section 6.2.1 section 6.3.1
- Vector search uses embeddings to find conceptually related passages even when words differ. On its own, it can miss a crucial exact term or return a passage that feels related but does not answer the question. section 6.2.1 section 6.3.1
- Fusion combines the ranked results. Reciprocal Rank Fusion (RRF) uses each passage’s position in the two lists rather than comparing their incompatible raw scores. A passage ranked highly by both searches receives a stronger combined score. section 6.3.3
With RRF, each passage receives a contribution of 1/(k + rank) from each list in which it appears; the contributions are added. The constant k is typically 60. Using ranks avoids having to calibrate a BM25 score against a cosine-similarity score. An agent can instead call separate semantic and keyword tools, inspect what they return, and choose relevant context; that is a different way to coordinate the two searches. section 6.3.3
From vector-only retrieval to hybrid retrieval
Suppose a grounded RAG agent can answer one question about a script but cannot answer a question whose key time term vector search fails to retrieve. Give it a semantic-search tool for conceptual questions and a keyword-search tool for exact words or phrases. Instruct it to use both when appropriate, quote retrieved passages, cite their reference markers, and say when the evidence is absent. Better retrieval helps only if the final answer stays tied to the passages found. section 6.3.2 section 6.3.3
Listing 6.7 02_RAG_agent_hybrid.py
agent = Agent(
name="Script Agent",
instructions="""
## ROLE
You answer questions about the movie *Back to the Future*.
You have access to two search tools: #1
1. `search_script_with_vector_similarity` - Use for
semantic/conceptual searches
2. `search_script_with_keyword` - Use for exact
word/phrase searches
Use both tools when appropriate to get comprehensive
results. #1
## GROUNDING RULES
IMPORTANT: You must always provide exact references
from the script. #2
- Quote relevant passages directly from the search
Results #2
- Use the [Reference X] markers to cite specific
passages
- Do not make up information that isn't in the script
- If the script doesn't contain the requested
information, say so clearly
- Always ground your answers in the actual script text
provided by the search tools
## ANSWER FORMAT
Format your answers like this: #3
Based on the script:
[Quote from Reference 1]: "exact text from script"
[Quote from Reference 2]: "exact text from script"
Your interpretation: [your analysis based on the
quotes]
""",
tools=[search_script_with_vector_similarity, search_script_with_keyword], #4
)
The agent instructions show the two search tools, when to use them, and how to cite or decline an answer based on retrieved script passages. section 6.3.3
Choose retrieval methods for the data and questions at hand rather than assuming vector search is sufficient. For a larger knowledge base, metadata filters, partitioning, and other searches may also matter. Check answers against retrieved passages: combining searches improves coverage, but the resulting context still needs verification. section 6.3.1 section 11.1.4 section 6.3.2
