{
  "schema_version": 2,
  "id": "develop/ai/context-engine/intent-router/developer-guide",
  "title": "Redis Intent Router developer guide",
  "url": "https://redis.io/docs/latest/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.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-10-30T15:58:10-04:00",
  "page_type": "content",
  "content_hash": "9d9112c54faf4334c2fee314b6d09a8cbb49dfb83601d897c8baed95e775dab9",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "This page is the starting point for adding Intent Router to an application. It shows the steps an integration follows, helps you choose between the Python package, the TypeScript client, the Iris command-line interface (CLI), and Hypertext Transfer Protocol (HTTP) requests, and shows how to connect to a Router. It then points to the pages that cover each task in detail."
    },
    {
      "id": "integration-workflow",
      "title": "Integration workflow",
      "role": "content",
      "text": "1. Get a Router's data-plane endpoint, its ID, and an agent key with a grant on it.\n1. Author the Router's intents and their example phrasings.\n1. Match each incoming query and dispatch on the target of the best intent.\n1. Add examples for the queries that match the wrong intent or none.\n\nPlatform teams create the Router and the agent keys. See [Manage Routers](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-routers)."
    },
    {
      "id": "choose-a-client",
      "title": "Choose a client",
      "role": "content",
      "text": "| Client | Use it when | Package and guide |\n|:-------|:------------|:------------------|\n| Python | Your application or agent uses Python. | Install [`redis-iris`](https://pypi.org/project/redis-iris/) and follow the [quickstart](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart). `IntentRouter` matches and authors intents with methods such as `match`, `define`, and `add_examples`. Its `client` property exposes the generated data-plane client for anything those methods don't wrap, and its `service` property administers Routers. The generated clients' methods return the response as `.headers` and `.result`. |\n| TypeScript | Your application or agent uses JavaScript or TypeScript. | Install [`@redis-iris/intent-router`](https://www.npmjs.com/package/@redis-iris/intent-router) with `npm install @redis-iris/intent-router`. `IntentRouter` calls the data plane, and `IntentRouterService` calls the control plane. Methods take positional arguments with request options last, and return `{ headers, result }`. |\n| CLI | You work from a shell, a script, or continuous integration. | The `iris intent-router` commands ship in the same [`redis-iris`](https://pypi.org/project/redis-iris/) package. |\n| HTTP | You need language-independent access or don't want a package dependency. | No package required. Send requests as shown in the [API reference](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/api-reference). |\n\nThe `redis-iris` package requires Python 3.11 or later. The TypeScript client requires Node.js 22 or later. The TypeScript client is a generated client, not a unified software development kit (SDK) equivalent to Python's `redis-iris` package."
    },
    {
      "id": "connect-to-a-router",
      "title": "Connect to a Router",
      "role": "content",
      "text": "Data-plane requests need:\n\n* The data plane's base URL.\n* The Router's ID, which starts with `rtr_`.\n* An agent key with a grant on the Router, sent as a bearer token on every request. Matching needs `read`, and authoring needs `write`.\n\nExport them as `IRIS_INTENT_ROUTER_URL`, `IRIS_INTENT_ROUTER_ID`, and `IRIS_INTENT_ROUTER_API_KEY`. The CLI reads these variables, and in Python `IntentRouter.from_env()` builds a client from them. The TypeScript client doesn't read the environment, so the examples pass the same values to its constructor.\n\nAdministration requests go to the control plane and need its URL and the admin token, which your platform team holds. The Python package and the CLI read them from `IRIS_INTENT_ROUTER_SERVICE_URL` and `IRIS_INTENT_ROUTER_SERVICE_TOKEN`. See [Manage Routers](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-routers#before-you-begin).\n\nKeep the admin token out of application configuration. An agent key can't create, change, or delete Routers."
    },
    {
      "id": "work-with-intents",
      "title": "Work with intents",
      "role": "content",
      "text": "Create or replace intents one at a time (`define` in Python, `intents add` in the CLI), add several at once with the bulk operation (`define_many`, or `intents add --file`), and manage examples separately from an intent's configuration. See [Manage intents and examples](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-intents)."
    },
    {
      "id": "match-queries",
      "title": "Match queries",
      "role": "content",
      "text": "Send each query to `match` and read the best item's target. An empty list means no intent is close enough. See [Match queries](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/match)."
    },
    {
      "id": "handle-errors",
      "title": "Handle errors",
      "role": "content",
      "text": "Every client raises an error that carries the HTTP status and the problem `type`. Match on the `type`. A `409` from a Router that isn't serving, a `424` from the embedding provider, or a `503` is worth retrying with backoff. A `412` means the intent changed since you read it. A `401` means the key is invalid, and a `403` means it lacks the action the operation needs. See [service limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/limits#handle-request-errors)."
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "* [Quickstart](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart)\n* [Python and CLI package reference](https://pypi.org/project/redis-iris/)\n* [TypeScript client reference](https://www.npmjs.com/package/@redis-iris/intent-router)\n* [Data-plane API reference](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/api-reference)\n* [Control-plane API reference](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/control-plane-api-reference)"
    }
  ],
  "examples": []
}