Redis Intent Router concepts

Understand Routers, intents, examples, targets, scores, and access grants.

Intent Router classifies each incoming user message by matching it against example phrases you group into intents. This page explains the parts you work with and how they fit together, so the task pages make sense when you reach them.

It covers Routers, which hold a set of intents and control who can use them, and intents, with their examples, targets, and revisions. It then explains how matching scores a query, when a change takes effect, and which agent-key actions each operation needs.

Routers

A Router is the unit you create, configure, and secure. It holds a set of intents and their examples, an embedding model, and a default minimum score. Each Router has its own access grants, so use separate Routers for workloads that must not share intents.

A Router has an opaque identifier that starts with rtr_. Its embedding model is fixed when you create it and can't change afterward, because every stored example is embedded with it.

A Router is in one of these states:

Administrators manage Routers through the control plane. Applications use the data plane to author intents and match queries. The two planes don't call each other, and a Router serves only after the data plane has applied its current configuration. See Manage Routers to create one, and service limits and errors for the errors a Router returns when it isn't serving.

Intents

An intent is a named classification. Its name is unique within the Router and can contain letters, digits, ., _, and -, starting with a letter or digit. An intent has:

• Examples: phrasings that should match the intent.
• A description: when the intent should win, in your words. Optional.
• A target: what a match dispatches to. Optional.
• A minimum score: how close a query must be for this intent to match. Optional.
• Metadata: labels such as an owner or tags. Optional.

An intent without examples never matches.

Intents and examples are ordered lists. Redis Intent Router returns them in the order you created them, not sorted by name.

Examples

An example is one phrasing of an intent, such as "where is my order" for track_order. Redis embeds each example when you write it.

Add several varied phrasings per intent. Matching compares a query with every example, so more varied examples cover more of the ways people ask. An example identifier starts with exm_ and is derived from the text, so adding the same phrasing twice keeps one example.

Targets

A target tells your application what to do when an intent matches:

The Router checks that args is valid JSON and passes it through untouched. It knows how an intent is dispatched, never what the target does.

Metadata is for descriptive labels. Put dispatch data in the target: metadata rejects the keys type, ref, target, and args.

Revisions

Every intent has a revision that changes with every write to the intent, including a PUT that changes nothing. Adding or deleting examples through the example operations doesn't change it. Send the revision back as expectedRevision to make a write conditional: the write fails with 412 Precondition Failed if someone else changed the intent first.

Matching

To match a query, Redis Intent Router embeds the text, finds the nearest examples in the Router's vector index (50 by default), and groups them by intent. By default an intent scores as its closest example, so one good example is enough for a match. Then it drops intents below their minimum score and returns the rest, best first.

A score is 1 minus the cosine distance between the query and the example, kept between 0 and 1, and higher is closer. Every threshold in the API points the same way: higher is stricter.

The minimum score that applies to an intent, from highest to lowest precedence:

1. The minScore in the match request.
2. The intent's own minScore, when it is above 0.
3. The Router's minScore, which is 0.7 unless you set another.

An intent minScore of 0 means "use the Router's", never "match everything". Only the match request can lower the threshold to 0.

A query with no sufficiently close intent returns 200 with an empty list. That is a normal result, not an error.

See Match queries to tune thresholds and result limits.

Authoring and consistency

Writes keep matching available. When you replace an intent, Redis writes the new examples first and removes the old ones afterward, so a concurrent match never sees an empty intent. Writing the same intent twice produces the same intent, with a new revision.

A write that adds several intents validates all of them first, and writes nothing if any is invalid.

Access

Two credentials guard the service:

• An admin token manages Routers on the control plane. Platform teams hold it.
• An agent key authenticates an application's data-plane requests as a bearer token. It carries a grant for each Router it can use. Redis Iris issues agent keys through its Identity Service, not through the Intent Router API.

A grant lists one or more actions on one Router. A key without the action an operation needs gets 403.

Grants apply to a whole Router. Don't rely on intent names or metadata to separate audiences. Use a separate Router instead.