Troubleshooting similarity matching failures

Similarity routing is the first step in agent selection. It compares a user's prompt with the configured similarity phrases for each agent to identify the best match. This process helps route common requests efficiently and reduces unnecessary large language model (LLM) calls.

The request is sent to the LLM for agent selection when agent confidence is below the configured threshold and similarity routing cannot identify a suitable match.

The Router Agent logs these events. By reviewing the logs, you can identify gaps in similarity phrase coverage, adjust thresholds, and improve routing accuracy over time.

Understanding similarity routing

The following configuration elements control similarity routing behavior.

Table 1. Similarity routing configuration settings
Configuration	Description
`similarityThreshold`	The minimum similarity score that is required for a routing match.
`similarityPhrases`	Example phrases that represent expected user requests for an agent.

When the highest-scoring agent falls below the configured threshold, the Router Agent records a log entry similar to the following example:

SimilarityRouter: no match above threshold=<value>, topScore=<value>, query=<prompt>

Reviewing similarity matching failures

Use OpenSearch to identify requests that similarity routing did not match to an agent.

On the OpenSearch dashboard, select Discover to open the search interface.
In the search bar, enter the following query:
```
"SimilarityRouter: no match above threshold"
```
For more information about query syntax, see the OpenSearch documentation.
Set the date range for the period that you want to analyze.
In the field selector, select the following fields:
- ext_requestId
- message
- Any additional fields, such as timestamp
Review the returned log entries.
Review recurring prompt patterns in the results.
On the Results page, click Download as CSV to export the data for further analysis.

Example

The following example shows a typical log entry:

SimilarityRouter.scoreAll SimilarityRouter: no match above threshold=0.6, topScore=0.5231, query=Check delivery status

Table 2. Log entry fields
Field	Description
`threshold`	The configured `similarityThreshold` value.
`topScore`	The highest cosine similarity score that is calculated across all configured agents.
`query`	The user's prompt that failed the threshold check.

In this example, the highest similarity score was 0.5231, which did not meet the configured threshold of 0.6. Because the highest-scoring agent falls below the configured threshold, similarity routing didn't return a match, and the AI model was used to select an agent.

The log entry is the primary indicator of a similarity matching failure and can help you identify routing gaps.

A consistently low topScore indicates that the agent's similarity phrases don't adequately represent how users express their requests.
A topScore that is consistently close to, but does not meet the configured threshold suggests that the similarity phrases are relevant, and that the similarityThreshold value might be too restrictive.

Review these log entries over time to identify recurring patterns in user requests.

Improving similarity matching performance

Use the exported data to identify opportunities to improve similarity matching performance.

Few or missing similarity phrases: If users frequently submit valid requests that do not match an agent, add 8-15 similarity phrases that reflect the most common ways that users express the agent's capability.

Overly specific similarity phrases

If phrases include specific values, such as order numbers, email addresses, or account identifiers, replace them with more general descriptions.

For example, replace:

Find order 12345

with

Find order by order number

Similarity threshold is too restrictive: If many valid requests have scores that are consistently close to, but do not meet the configured threshold, consider lowering the similarityThreshold value.; Review routing accuracy before you make changes.

Overlapping similarity phrases: If multiple agents use similar or generic phrases, routing confidence might decrease.; Make sure that each agent's phrases focus on its unique capability and avoid language that applies broadly across multiple agents.

Unusual or ambiguous requests: Some user requests are intentionally broad, incomplete, or ambiguous.; These requests often bypass similarity routing and are routed through the AI model. This behavior is expected and typically doesn't require configuration changes.

Agents without similarity phrases: Agents must have similarity phrases to participate in similarity matching.; Add similarity phrases so that these agents can participate in similarity routing.