# Redis Intent Router

```json metadata
{
  "schema_version": 2,
  "title": "Redis Intent Router",
  "description": "Classify a user's message into a named intent and get back the target your application should dispatch to.",
  "categories": ["docs","develop","ai"],
  "tableOfContents": {"sections":[{"id":"what-is-redis-intent-router","title":"What is Redis Intent Router?"},{"id":"why-use-redis-intent-router","title":"Why use Redis Intent Router?"},{"id":"concepts","title":"Concepts"},{"id":"quick-example","title":"Quick example"},{"id":"choose-how-to-use-it","title":"Choose how to use it"},{"id":"manage-routers-and-intents","title":"Manage Routers and intents"},{"id":"route-at-runtime","title":"Route at runtime"}]}

,
  "codeExamples": [{"codetabsId":"iris_intent_router_quickstart-steprouter-connect","difficulty":"beginner","id":"router-connect","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_quickstart-steprouter-connect"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_quickstart-steprouter-connect"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_quickstart-steprouter-connect"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_quickstart-steprouter-connect"}]},{"codetabsId":"iris_intent_router_quickstart-stepintents-create","difficulty":"beginner","id":"intents-create","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_quickstart-stepintents-create"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_quickstart-stepintents-create"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_quickstart-stepintents-create"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_quickstart-stepintents-create"}]}]
}
```

## Code examples

These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough.


## 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.

<div class="grid grid-cols-1 md:grid-cols-4 gap-6 my-8">
  
  
  
  
</div>

## 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](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/concepts).

## Quick example

1. Set up a Router:
    - **Redis Cloud:** [Create an Intent Router](https://redis.io/docs/latest/operate/iris/intent-router/create-router).
    - **Self-managed:** Deploy with [Self-managed Intent Router](https://redis.io/docs/latest/operate/iris/intent-router/self-managed), then [create a Router and an agent key](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/api-examples). You need a license key to deploy: [contact Redis](https://redis.io/contact/) to request access.
1. Install the Redis Iris Python package, which includes the `iris` CLI:

    ```bash
    pip install 'redis-iris>=1.0.0'
    ```

1. Set `IRIS_INTENT_ROUTER_URL`, `IRIS_INTENT_ROUTER_ID`, and `IRIS_INTENT_ROUTER_API_KEY` as shown in the [quickstart](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart#save-connection-values), connect, and define intents:

**Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris)

##### Python (Iris)

```python
from redis_iris.intent_router import IntentRouter, Target

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

##### TypeScript (Iris)

```typescript
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);
```

##### cURL (Iris)

```bash
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 .
```

##### CLI (Iris)

```bash
set -euo pipefail
iris intent-router health
```



**Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris)

##### Python (Iris)

```python
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)
```

##### TypeScript (Iris)

```typescript
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 (Iris)

```bash
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}'
```

##### CLI (Iris)

```bash
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](https://pypi.org/project/redis-iris/) covers matching, intent authoring, and Router administration in Python and the CLI. For TypeScript, the generated client [@redis-iris/intent-router](https://www.npmjs.com/package/@redis-iris/intent-router) covers the data plane and the control plane. See the [developer guide](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/developer-guide) to choose a client, and [define intents and match your first queries](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart).

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

- **Redis Cloud:** [Create an Intent Router](https://redis.io/docs/latest/operate/iris/intent-router/create-router) and an agent key in the Redis Cloud console.
- **Self-managed:** See [Self-managed Intent Router](https://redis.io/docs/latest/operate/iris/intent-router/self-managed), then [create a Router and an agent key](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/api-examples). You need a license key to deploy: [contact Redis](https://redis.io/contact/) to request access.

## Choose how to use it

| Use case | How an intent helps |
| -------- | ------------------- |
| Agent routing | Send each request to the specialist agent or tool that handles it. |
| Model selection | Send simple requests to a small model and complex ones to a larger model. |
| Guardrails | Detect off-topic or disallowed requests before they reach the agent. |
| Workflow dispatch | Start a pipeline or handler from a natural-language request. |

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](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-routers): choose an embedding model, create a Router, and suspend, update, or delete it.
- [Manage intents and examples](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-intents): create, update, replace, and delete intents and their example phrasings.

## Route at runtime

- [Developer guide](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/developer-guide): choose a client and connect.
- [Match queries](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/match): classify text and tune thresholds.

Use the [API reference](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/api-reference) for operations and schemas, and [service limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/limits) for constraints and recovery guidance.