The Agent Search stage uses an LLM reasoning loop to orchestrate other retriever stages as callable tools. Instead of executing a fixed sequence of stages, the LLM dynamically decides which stages to invoke, with what arguments, and how many iterations to perform based on the query and intermediate results.
Stage Category : FILTER (Adaptive retrieval)Transformation : Query → LLM reasoning (1-N iterations) → Refined documents
When to Use Use Case Description Multi-hop queries Questions requiring following references across documents Iterative refinement Broad search followed by intelligent narrowing Complex filtering logic When the right filter conditions depend on query semantics Tree/hierarchy navigation Navigating hierarchical document indexes top-down Exploratory search When the best search strategy isn’t known upfront
When NOT to Use Scenario Recommended Alternative Simple keyword or vector search feature_searchKnown metadata filter conditions attribute_filterFixed pipeline with known stages Chain stages directly Latency-critical applications (< 1s) Direct stage execution Cost-sensitive high-volume queries Pre-configured pipelines
Parameters Parameter Type Default Description strategystring iterative_refinementReasoning strategy (see Strategies below) stageslist[string] from strategy Which retriever stages the agent can invoke as tools system_promptstring from strategy Custom system prompt for the LLM. Supports {{INPUT.*}} variables max_iterationsinteger 5Maximum reasoning iterations (1-20) timeout_secondsfloat 60.0Total timeout for the reasoning loop (5-300s) providerstring auto LLM provider (openai, google, anthropic) model_namestring auto Specific model to use
Strategies Strategy Default Tools Best For iterative_refinementfeature_search, attribute_filter Progressive narrowing of results multi_hopfeature_search, attribute_filter, llm_filter Following cross-document references tree_navigationfeature_search, attribute_filter Hierarchical index traversal customuser-specified Full control over tools and prompt
The agent can invoke any registered retriever stage as a tool. Each stage is presented to the LLM with a simplified parameter schema:
Tool What the LLM Sees Typical Use feature_searchSemantic similarity search with query and top_k Vector search attribute_filterFilter by field, operator, and value Metadata filtering llm_filterFilter by natural language criteria Semantic filtering rerankRe-score documents by relevance to query Result refinement llm_enrichGenerate new fields using LLM analysis Information extraction taxonomy_enrichClassify documents against a taxonomy Categorization
Configuration Examples Iterative Refinement
Custom Strategy with Specific Tools
Multi-Hop with LLM Filter
Tree Navigation
{ "stage_type" : "filter" , "stage_id" : "agent_search" , "parameters" : { "strategy" : "iterative_refinement" , "max_iterations" : 5 , "timeout_seconds" : 30.0 } }
Use the custom strategy when you need precise control over which tools the agent can access and how it should reason. The built-in strategies provide sensible defaults for common patterns.
How It Works
Initialize : The LLM receives the user query, available tools, and system promptReason : The LLM analyzes the query and decides which tool to call with what argumentsExecute : The selected stage runs as a sub-execution with the LLM-provided parametersObserve : Results are summarized and fed back to the LLM as tool call resultsIterate : The LLM decides whether to call another tool or stopReturn : Final accumulated results are returned as the stage output
Each tool call creates a sub-state execution of the target stage, inheriting namespace and collection context from the parent. Results from each iteration replace the previous results, giving the LLM a fresh working set to refine.
Metric Value Latency 2-30s (depends on iterations and sub-stages) Memory O(N) per iteration result set Cost LLM API calls + sub-stage costs per iteration Complexity O(iterations * sub-stage complexity)
Common Pipeline Patterns Agent as First Stage [ { "stage_type" : "filter" , "stage_id" : "agent_search" , "parameters" : { "strategy" : "iterative_refinement" , "stages" : [ "feature_search" , "attribute_filter" ], "max_iterations" : 3 } }, { "stage_type" : "sort" , "stage_id" : "rerank" , "parameters" : { "inference_name" : "baai_bge_reranker_v2_m3" , "query" : "{{INPUT.query}}" , "document_field" : "content" } }, { "stage_type" : "reduce" , "stage_id" : "limit" , "parameters" : { "limit" : 10 } } ]
Complex Query Decomposition [ { "stage_type" : "filter" , "stage_id" : "agent_search" , "parameters" : { "strategy" : "custom" , "stages" : [ "feature_search" , "attribute_filter" , "llm_filter" ], "system_prompt" : "Break down the user's complex query into sub-queries. Use feature_search for each sub-query, attribute_filter to narrow by metadata, and llm_filter to validate relevance. Combine the best results." , "max_iterations" : 5 , "timeout_seconds" : 45.0 } }, { "stage_type" : "reduce" , "stage_id" : "deduplicate" , "parameters" : { "strategy" : "field" , "fields" : [ "document_id" ] } } ]
The stage returns execution metadata in stage_statistics:
Field Description iterations_usedNumber of reasoning iterations completed timeout_hitWhether the timeout was reached strategyStrategy that was used stages_invokedList of tool calls made (name + arguments) total_llm_costTotal LLM API cost for the reasoning loop model_usedLLM model that was used
Error Handling Error Behavior Sub-stage execution fails Error message returned to LLM; it can retry or try a different approach Timeout reached Returns results accumulated so far (graceful degradation) Max iterations reached Returns latest results from last successful tool call Unknown stage in tools list Stage is skipped (logged as warning) LLM returns no tool calls Loop ends; returns current results Empty collection Returns empty result set (no error)
