Redis Intent Router

Classify a user's message into a named intent and get back the target your application should dispatch to.

What is Redis Intent Router?

Redis Intent Router classifies text into intents that you define. Each intent is a name, a few example phrasings, and an optional target that says what your application should do when the intent matches. Send a query to a Router and it returns the closest intents, best first, with a score for each.

It works like a semantic cache, but returns a structured intent instead of a cached response. Redis embeds the query, finds the nearest examples, groups them by intent, and applies a score threshold. No large language model (LLM) call is involved at match time.

For example, a support application can route "where is my package?" to a track_order intent that points at an order-tracking tool, and "I want my money back" to a refund intent that points at a refund workflow.

Concepts

Learn how Routers, intents, examples, targets, and scores work

Learn more →

Read more

Quickstart

Define two intents and match your first queries

Learn more →

Read more

Manage Routers

Create Routers, choose an embedding model, and control access

Learn more →

Read more

Match queries

Tune thresholds and result limits for accurate routing

Learn more →

Read more

Why use Redis Intent Router?

• Fast, predictable routing: Matching embeds the query and runs a vector search over your examples, with no LLM call.
• Routing you can edit: Add an example or change a threshold and the change applies to the next query. You don't retrain or redeploy anything.
• Dispatch data stays with the intent: A target carries the tool, pipeline, or agent to call, so your application doesn't keep a separate lookup table.
• Tunable strictness: Set a minimum score on the Router, on each intent, or on a single request.
• Safe updates: Replacing an intent never leaves it empty while queries are in flight, and conditional writes prevent lost updates.
• Governed access: Each Router is its own authorization boundary, with separate read, write, and full grants.
• Flexible integration: Use Python, TypeScript, the iris command-line interface (CLI), or the Hypertext Transfer Protocol (HTTP) API.

Concepts

A Router holds your intents and is its own access boundary. Each intent has example phrasings and an optional target, and each match returns intents with a score that a threshold on the Router, the intent, or the request can filter. See Intent Router concepts.

Quick example

1. Set up a Router:

   • Redis Cloud: Create an Intent Router.
   • Self-managed: Deploy with Self-managed Intent Router, then create a Router and an agent key. You need a license key to deploy: contact Redis to request access.

2. Install the Redis Iris Python package, which includes the iris CLI:

   pip install 'redis-iris>=1.0.0'
   

3. Set IRIS_INTENT_ROUTER_URL, IRIS_INTENT_ROUTER_ID, and IRIS_INTENT_ROUTER_API_KEY as shown in the quickstart, connect, and define intents:

from redis_iris.intent_router import IntentRouter, Target

router = IntentRouter.from_env()
print(router.health())

import { IntentRouter } from "@redis-iris/intent-router";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}

const router = new IntentRouter({
  serverURL: requiredEnv("IRIS_INTENT_ROUTER_URL"),
  routerId: requiredEnv("IRIS_INTENT_ROUTER_ID"),
  apiKey: requiredEnv("IRIS_INTENT_ROUTER_API_KEY"),
  retryConfig: { strategy: "none" },
});
console.log((await router.getRouterHealth()).result);

set -euo pipefail
ROUTER_API="${IRIS_INTENT_ROUTER_URL%/}/iris/data/v1/intent/routers/$IRIS_INTENT_ROUTER_ID"
curl --fail-with-body --silent --show-error \
  "$ROUTER_API/health" \
  -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" | jq .

set -euo pipefail
iris intent-router health

for intent in (
    router.define(
        "track_order",
        description="The customer wants to know where an order is.",
        target=Target("tool", "orders.track", {"region": "eu"}),
        examples=["where is my order", "track my package", "has my parcel shipped"],
    ),
    router.define(
        "refund",
        examples=["i want a refund", "refund my purchase", "i would like my money back"],
    ),
):
    print(intent.name, intent.example_count, intent.revision)

for (const intent of [
  await router.upsertIntent("track_order", undefined, undefined, {
    description: "The customer wants to know where an order is.",
    target: { type: "tool", ref: "orders.track", args: { region: "eu" } },
    examples: ["where is my order", "track my package", "has my parcel shipped"],
  }),
  await router.upsertIntent("refund", undefined, undefined, {
    examples: ["i want a refund", "refund my purchase", "i would like my money back"],
  }),
]) {
  console.log(intent.result.name, intent.result.exampleCount, intent.result.revision);
}

curl --fail-with-body --silent --show-error \
  -X PUT "$ROUTER_API/intents/track_order" \
  -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "description": "The customer wants to know where an order is.",
    "target": {"type": "tool", "ref": "orders.track", "args": {"region": "eu"}},
    "examples": ["where is my order", "track my package", "has my parcel shipped"]
  }' | jq -c '{name, exampleCount, revision}'
curl --fail-with-body --silent --show-error \
  -X PUT "$ROUTER_API/intents/refund" \
  -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"examples": ["i want a refund", "refund my purchase", "i would like my money back"]}' \
  | jq -c '{name, exampleCount, revision}'

iris intent-router intents add track_order \
  --description "The customer wants to know where an order is." \
  --target '{"type": "tool", "ref": "orders.track", "args": {"region": "eu"}}' \
  --example "where is my order" --example "track my package" --example "has my parcel shipped"
iris intent-router intents add refund \
  --example "i want a refund" --example "refund my purchase" --example "i would like my money back"

The redis-iris package covers matching, intent authoring, and Router administration in Python and the CLI. For TypeScript, the generated client @redis-iris/intent-router covers the data plane and the control plane. See the developer guide to choose a client, and define intents and match your first queries.

Redis Intent Router is available on Redis Cloud and for self-managed deployment on Kubernetes.

• Redis Cloud: Create an Intent Router and an agent key in the Redis Cloud console.
• Self-managed: See Self-managed Intent Router, then create a Router and an agent key. You need a license key to deploy: contact Redis to request access.

Choose how to use it

The Router doesn't run the target. It returns the target, and your application decides how and whether to act on it.

Manage Routers and intents

• Manage Routers: choose an embedding model, create a Router, and suspend, update, or delete it.
• Manage intents and examples: create, update, replace, and delete intents and their example phrasings.

Route at runtime

• Developer guide: choose a client and connect.
• Match queries: classify text and tune thresholds.

Use the API reference for operations and schemas, and service limits and errors for constraints and recovery guidance.