Link Search Menu Expand Document Documentation Menu
Documentation

Agentic query translator processor

Introduced 3.2

The agentic_query_translator search request processor enables natural language search by translating user queries into OpenSearch query domain-specific language (DSL) queries using machine learning (ML) agents. It works with agentic search queries to provide conversational search capabilities:

  1. The processor sends the user’s natural language query to the specified ML agent.
  2. The agent translates the query into OpenSearch DSL.
  3. The original query is replaced with the generated DSL query.

This processor only works with the agentic query type as the top-level query.

Prerequisites

Before using the agentic_query_translator processor, you must have either a conversational or flow agent configured. For more information, see Agents.

Request body fields

The following table lists all available request fields.

Field Data type Required/Optional Description
agent_id String Required The ID of the ML agent that will translate natural language queries into DSL queries.
embedding_model_id String Optional The ID of the embedding model that generates vector embeddings for semantic search using neural queries. This parameter takes precedence over the embedding_model_id specified in the agent configuration. For more information, see Configuring agents for semantic search.

Example

The following example request creates a search pipeline with an agentic_query_translator processor:

PUT /_search/pipeline/agentic_search_pipeline
{
  "request_processors": [
    {
      "agentic_query_translator": {
        "agent_id": "your-agent-id-here"
      }
    }
  ]
}

To enable semantic search capabilities, you can optionally specify an embedding_model_id for the text embedding model that converts queries into vector embeddings:

PUT /_search/pipeline/agentic_search_pipeline
{
  "request_processors": [
    {
      "agentic_query_translator": {
        "agent_id": "your-agent-id-here",
        "embedding_model_id": "your-embedding-model-id"
      }
    }
  ]
}

Usage

To use the processor, run an agentic query:

POST /your-index/_search?search_pipeline=agentic_search_pipeline
{
    "query": {
        "agentic": {
            "query_text": "Show me shoes in white color"
        }
    }
}

The response contains the matching documents:

{
    "took": 6031,
    "timed_out": false,
    "_shards": {
        "total": 8,
        "successful": 8,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 8,
            "relation": "eq"
        },
        "max_score": 0.0,
        "hits": [
            {
                "_index": "products-index",
                "_id": "43",
                "_score": 0.0,
                "_source": {
                    "product_name": "Nike Air Max white",
                    "description": "Red cushioned sneakers",
                    "price": 140.0,
                    "currency": "USD",
                    "in_stock": true,
                    "color": "white",
                    "size": "10",
                    "product_id": "P6001",
                    "category": "shoes",
                    "brand": "Nike"
                }
            },
            {
                "_index": "products-index",
                "_id": "45",
                "_score": 0.0,
                "_source": {
                    "product_name": "Adidas Superstar white",
                    "description": "Classic black sneakers",
                    "price": 100.0,
                    "currency": "USD",
                    "in_stock": true,
                    "color": "white",
                    "size": "8",
                    "product_id": "P6003",
                    "category": "shoes",
                    "brand": "Adidas"
                }
            }
        ]
    }
}
350 characters left

Have a question? .

Want to contribute? or .