{
  "schema_version": 2,
  "id": "develop/ai/context-engine/intent-router",
  "title": "Redis Intent Router",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/",
  "summary": "Classify a user's message into a named intent and get back the target your application should dispatch to.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T16:57:46-08:00",
  "children": [
    {
      "id": "develop/ai/context-engine/intent-router/concepts",
      "summary": "Understand Routers, intents, examples, targets, scores, and access grants.",
      "title": "Redis Intent Router concepts",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/concepts/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/developer-guide",
      "summary": "Connect an application to Redis Intent Router and work with intents through Python, TypeScript, the Iris CLI, or HTTP.",
      "title": "Redis Intent Router developer guide",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/developer-guide/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/quickstart",
      "summary": "Define two intents, match queries against them, and update an intent with Python, TypeScript, HTTP, or the Iris CLI.",
      "title": "Redis Intent Router quickstart",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/manage-routers",
      "summary": "Choose an embedding model, create a Router, wait for it to be ready, and update, suspend, or delete it.",
      "title": "Manage Routers",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-routers/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/manage-intents",
      "summary": "Create, update, replace, list, and delete intents and their example phrasings.",
      "title": "Manage intents and examples",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-intents/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/match",
      "summary": "Classify a query into intents, read scores and targets, and tune thresholds and result limits.",
      "title": "Match queries to intents",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/match/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/api-reference",
      "summary": "",
      "title": "Redis Intent Router data-plane API",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/api-reference/"
    },
    {
      "id": "develop/ai/context-engine/intent-router/limits",
      "summary": "Find Router, content, and match limits, error types, and retry guidance.",
      "title": "Service limits and errors",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/intent-router/limits/"
    }
  ],
  "page_type": "content",
  "content_hash": "cd0231fa9b034007d983ab03aa270d8435a1b16aa049706d37323ab624cbf0b3",
  "sections": [
    {
      "id": "code-examples",
      "title": "Code examples",
      "role": "example",
      "text": "These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough."
    },
    {
      "id": "what-is-redis-intent-router",
      "title": "What is Redis Intent Router?",
      "role": "content",
      "text": "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.\n\nIt 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.\n\nFor 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.\n\n<div class=\"grid grid-cols-1 md:grid-cols-4 gap-6 my-8\">\n  \n  \n  \n  \n</div>"
    },
    {
      "id": "why-use-redis-intent-router",
      "title": "Why use Redis Intent Router?",
      "role": "content",
      "text": "- **Fast, predictable routing:** Matching embeds the query and runs a vector search over your examples, with no LLM call.\n- **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.\n- **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.\n- **Tunable strictness:** Set a minimum score on the Router, on each intent, or on a single request.\n- **Safe updates:** Replacing an intent never leaves it empty while queries are in flight, and conditional writes prevent lost updates.\n- **Governed access:** Each Router is its own authorization boundary, with separate `read`, `write`, and `full` grants.\n- **Flexible integration:** Use Python, TypeScript, the `iris` command-line interface (CLI), or the Hypertext Transfer Protocol (HTTP) API."
    },
    {
      "id": "concepts",
      "title": "Concepts",
      "role": "content",
      "text": "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)."
    },
    {
      "id": "quick-example",
      "title": "Quick example",
      "role": "content",
      "text": "1. Set up a Router:\n    - **Redis Cloud:** [Create an Intent Router](https://redis.io/docs/latest/operate/iris/intent-router/create-router).\n    - **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.\n1. Install the Redis Iris Python package, which includes the `iris` CLI:\n\n    [code example]\n\n1. 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:\n\n**Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### TypeScript (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\n**Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### TypeScript (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\nThe [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).\n\nRedis Intent Router is available on Redis Cloud and for self-managed deployment on Kubernetes.\n\n- **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.\n- **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."
    },
    {
      "id": "choose-how-to-use-it",
      "title": "Choose how to use it",
      "role": "content",
      "text": "| Use case | How an intent helps |\n| -------- | ------------------- |\n| Agent routing | Send each request to the specialist agent or tool that handles it. |\n| Model selection | Send simple requests to a small model and complex ones to a larger model. |\n| Guardrails | Detect off-topic or disallowed requests before they reach the agent. |\n| Workflow dispatch | Start a pipeline or handler from a natural-language request. |\n\nThe Router doesn't run the target. It returns the target, and your application decides how and whether to act on it."
    },
    {
      "id": "manage-routers-and-intents",
      "title": "Manage Routers and intents",
      "role": "content",
      "text": "- [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.\n- [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."
    },
    {
      "id": "route-at-runtime",
      "title": "Route at runtime",
      "role": "content",
      "text": "- [Developer guide](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/developer-guide): choose a client and connect.\n- [Match queries](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/match): classify text and tune thresholds.\n\nUse 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."
    }
  ],
  "examples": [
    {
      "id": "quick-example-ex0",
      "language": "bash",
      "code": "pip install 'redis-iris>=1.0.0'",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex1",
      "language": "python",
      "code": "from redis_iris.intent_router import IntentRouter, Target\n\nrouter = IntentRouter.from_env()\nprint(router.health())",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex2",
      "language": "typescript",
      "code": "import { IntentRouter } from \"@redis-iris/intent-router\";\n\nfunction requiredEnv(name: string): string {\n  const value = process.env[name];\n  if (!value) throw new Error(`Set ${name}`);\n  return value;\n}\n\nconst router = new IntentRouter({\n  serverURL: requiredEnv(\"IRIS_INTENT_ROUTER_URL\"),\n  routerId: requiredEnv(\"IRIS_INTENT_ROUTER_ID\"),\n  apiKey: requiredEnv(\"IRIS_INTENT_ROUTER_API_KEY\"),\n  retryConfig: { strategy: \"none\" },\n});\nconsole.log((await router.getRouterHealth()).result);",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex3",
      "language": "bash",
      "code": "set -euo pipefail\nROUTER_API=\"${IRIS_INTENT_ROUTER_URL%/}/iris/data/v1/intent/routers/$IRIS_INTENT_ROUTER_ID\"\ncurl --fail-with-body --silent --show-error \\\n  \"$ROUTER_API/health\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY\" | jq .",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex4",
      "language": "bash",
      "code": "set -euo pipefail\niris intent-router health",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex5",
      "language": "python",
      "code": "for intent in (\n    router.define(\n        \"track_order\",\n        description=\"The customer wants to know where an order is.\",\n        target=Target(\"tool\", \"orders.track\", {\"region\": \"eu\"}),\n        examples=[\"where is my order\", \"track my package\", \"has my parcel shipped\"],\n    ),\n    router.define(\n        \"refund\",\n        examples=[\"i want a refund\", \"refund my purchase\", \"i would like my money back\"],\n    ),\n):\n    print(intent.name, intent.example_count, intent.revision)",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex6",
      "language": "typescript",
      "code": "for (const intent of [\n  await router.upsertIntent(\"track_order\", undefined, undefined, {\n    description: \"The customer wants to know where an order is.\",\n    target: { type: \"tool\", ref: \"orders.track\", args: { region: \"eu\" } },\n    examples: [\"where is my order\", \"track my package\", \"has my parcel shipped\"],\n  }),\n  await router.upsertIntent(\"refund\", undefined, undefined, {\n    examples: [\"i want a refund\", \"refund my purchase\", \"i would like my money back\"],\n  }),\n]) {\n  console.log(intent.result.name, intent.result.exampleCount, intent.result.revision);\n}",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex7",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  -X PUT \"$ROUTER_API/intents/track_order\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  --data '{\n    \"description\": \"The customer wants to know where an order is.\",\n    \"target\": {\"type\": \"tool\", \"ref\": \"orders.track\", \"args\": {\"region\": \"eu\"}},\n    \"examples\": [\"where is my order\", \"track my package\", \"has my parcel shipped\"]\n  }' | jq -c '{name, exampleCount, revision}'\ncurl --fail-with-body --silent --show-error \\\n  -X PUT \"$ROUTER_API/intents/refund\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"examples\": [\"i want a refund\", \"refund my purchase\", \"i would like my money back\"]}' \\\n  | jq -c '{name, exampleCount, revision}'",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex8",
      "language": "bash",
      "code": "iris intent-router intents add track_order \\\n  --description \"The customer wants to know where an order is.\" \\\n  --target '{\"type\": \"tool\", \"ref\": \"orders.track\", \"args\": {\"region\": \"eu\"}}' \\\n  --example \"where is my order\" --example \"track my package\" --example \"has my parcel shipped\"\niris intent-router intents add refund \\\n  --example \"i want a refund\" --example \"refund my purchase\" --example \"i would like my money back\"",
      "section_id": "quick-example"
    }
  ]
}