{
  "schema_version": 2,
  "id": "develop/ai/context-engine/context-retriever/quickstart",
  "title": "Redis Context Retriever quickstart",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/context-retriever/quickstart/",
  "summary": "Model a data source, generate MCP tools, and call them from an agent using the ctxctl CLI.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-09-25T11:04:30-07:00",
  "page_type": "content",
  "content_hash": "9415a0b9c211017f08631462134f8a436a72833fa3e13cef2980b67d4c324d7a",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Use this quickstart to model a Redis data source as a context surface, generate the retrieval tools that Context Retriever exposes, and call one of those tools as an agent would.\n\nThis quickstart walks you through:\n\n1. [Install the Python client](#install-the-python-client)\n1. [Sign in and create an admin key](#sign-in-and-create-an-admin-key)\n1. [Define your data model](#define-your-data-model)\n1. [Load sample data](#load-sample-data)\n1. [Create a surface](#create-a-surface)\n1. [Create an agent key](#create-an-agent-key)\n1. [List the generated tools](#list-the-generated-tools)\n1. [Call a tool](#call-a-tool)\n1. [Clean up](#clean-up)\n\nThis quickstart uses Redis Cloud. If you're running Context Retriever self-managed, see [Install Context Retriever](https://redis.io/docs/latest/operate/iris/context-retriever/self-managed) instead; every step after sign-in and admin-key creation is the same either way."
    },
    {
      "id": "before-you-begin",
      "title": "Before you begin",
      "role": "content",
      "text": "To complete this quickstart, you need:\n\n* A Redis Cloud account.\n* A Redis Cloud database. If you don't have one, see [Create a database](https://redis.io/docs/latest/operate/rc/databases/create-database).\n* Python 3.11 or later and `pip`.\n* `redis-cli`, to load sample data. See [Install redis-cli](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/install-redis-cli)."
    },
    {
      "id": "install-the-python-client",
      "title": "Install the Python client",
      "role": "setup",
      "text": "The Python client includes the `ctxctl` CLI, which you use to model data, manage keys, and call the tools Context Retriever generates.\n\n[code example]"
    },
    {
      "id": "sign-in-and-create-an-admin-key",
      "title": "Sign in and create an admin key",
      "role": "content",
      "text": "1. Start a session against your Redis Cloud account:\n\n   [code example]\n\n1. Create an admin key. An admin key authorizes operations such as creating surfaces and agent keys.\n\n   [code example]\n\n1. Save the returned key. Export it so later commands can use it:\n\n   [code example]\n\nThis quickstart uses a Redis Cloud account for sign-in and admin-key creation. If you're running Context Retriever self-managed instead, see [Install Context Retriever](https://redis.io/docs/latest/operate/iris/context-retriever/self-managed) to bootstrap your first admin key. Every other step in this quickstart applies to both."
    },
    {
      "id": "define-your-data-model",
      "title": "Define your data model",
      "role": "content",
      "text": "Context Retriever generates tools from a data model, not from CLI flags entered one field at a time. Define your entities in a Python file.\n\nCreate `models.py`:\n\n[code example]"
    },
    {
      "id": "load-sample-data",
      "title": "Load sample data",
      "role": "content",
      "text": "Load a few customer hashes that match the model, so the tool call later in this quickstart returns predictable results:\n\n[code example]\n\nIf you already have data that matches this shape, you can skip this step and use your own keys instead."
    },
    {
      "id": "create-a-surface",
      "title": "Create a surface",
      "role": "content",
      "text": "1. Create a context surface from your model file, pointing it at your Redis Cloud database:\n\n   [code example]\n\n1. Save the returned surface ID:\n\n   [code example]\n\n1. Confirm the surface was created:\n\n   [code example]"
    },
    {
      "id": "create-an-agent-key",
      "title": "Create an agent key",
      "role": "content",
      "text": "An agent key authorizes an agent to call the tools generated for a surface.\n\n1. Create one scoped to the surface you just created:\n\n   [code example]\n\n1. Save the returned key:\n\n   [code example]"
    },
    {
      "id": "list-the-generated-tools",
      "title": "List the generated tools",
      "role": "content",
      "text": "As the admin, confirm which tools Context Retriever generated from your model:\n\n[code example]\n\nThe list includes tools such as a search tool and a get-by-ID tool for each entity you defined."
    },
    {
      "id": "call-a-tool",
      "title": "Call a tool",
      "role": "content",
      "text": "Call a generated tool directly, using the agent key instead of the admin key:\n\n[code example]\n\n> [!NOTE]\n> **What to expect:** A JSON result containing `Jane Doe` and `Jane Roberts`, the two sample customers whose `name` field matches `jane`. The agent never sends a database query directly. It calls a tool that Context Retriever generated from your model."
    },
    {
      "id": "clean-up",
      "title": "Clean up",
      "role": "content",
      "text": "Delete the surface you created, which also revokes its agent keys:\n\n[code example]"
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "* Read [Context Retriever concepts](https://redis.io/docs/latest/develop/ai/context-engine/context-retriever/concepts) to understand tools, providers, and access tags.\n* [Create a Context Retriever service in Redis Cloud](https://redis.io/docs/latest/operate/iris/context-retriever/create-service) using the console instead of the CLI.\n* [Manage admin keys](https://redis.io/docs/latest/operate/iris/context-retriever/view-admin-keys)."
    }
  ],
  "examples": [
    {
      "id": "install-the-python-client-ex0",
      "language": "bash",
      "code": "pip install redis-context-retriever",
      "section_id": "install-the-python-client"
    },
    {
      "id": "sign-in-and-create-an-admin-key-ex0",
      "language": "bash",
      "code": "ctxctl auth login -u <your-redis-cloud-email>",
      "section_id": "sign-in-and-create-an-admin-key"
    },
    {
      "id": "sign-in-and-create-an-admin-key-ex1",
      "language": "bash",
      "code": "ctxctl --output json admin create --name \"quickstart-admin\"",
      "section_id": "sign-in-and-create-an-admin-key"
    },
    {
      "id": "sign-in-and-create-an-admin-key-ex2",
      "language": "bash",
      "code": "export CTX_ADMIN_KEY='<the returned key, starts with cs_admin_>'",
      "section_id": "sign-in-and-create-an-admin-key"
    },
    {
      "id": "define-your-data-model-ex0",
      "language": "python",
      "code": "from context_surfaces.context_model import ContextField, ContextModel\n\nclass Customer(ContextModel):\n    __redis_key_template__ = \"customer:{id}\"\n\n    id: str = ContextField(description=\"Unique customer ID\", is_key_component=True)\n    name: str = ContextField(description=\"Customer name\", index=\"text\")\n    email: str = ContextField(description=\"Customer email address\", index=\"tag\")",
      "section_id": "define-your-data-model"
    },
    {
      "id": "load-sample-data-ex0",
      "language": "bash",
      "code": "redis-cli -h <your-database-host> -p <port> -a '<your-database-password>' HSET customer:1 id 1 name \"Jane Doe\" email \"jane.doe@example.com\"\nredis-cli -h <your-database-host> -p <port> -a '<your-database-password>' HSET customer:2 id 2 name \"John Smith\" email \"john.smith@example.com\"\nredis-cli -h <your-database-host> -p <port> -a '<your-database-password>' HSET customer:3 id 3 name \"Jane Roberts\" email \"jane.roberts@example.com\"",
      "section_id": "load-sample-data"
    },
    {
      "id": "create-a-surface-ex0",
      "language": "bash",
      "code": "ctxctl --output json surface create \\\n     --name \"quickstart-surface\" \\\n     --description \"Quickstart context surface\" \\\n     --models ./models.py \\\n     --redis-addr <your-database-host>:<port> \\\n     --redis-password '<your-database-password>' \\\n     --admin-key \"$CTX_ADMIN_KEY\"",
      "section_id": "create-a-surface"
    },
    {
      "id": "create-a-surface-ex1",
      "language": "bash",
      "code": "export CTX_SURFACE_ID='<the returned surface id>'",
      "section_id": "create-a-surface"
    },
    {
      "id": "create-a-surface-ex2",
      "language": "bash",
      "code": "ctxctl surface describe \"$CTX_SURFACE_ID\" --admin-key \"$CTX_ADMIN_KEY\"",
      "section_id": "create-a-surface"
    },
    {
      "id": "create-an-agent-key-ex0",
      "language": "bash",
      "code": "ctxctl --output json agent create \\\n     --surface-id \"$CTX_SURFACE_ID\" \\\n     --name \"quickstart-agent\" \\\n     --admin-key \"$CTX_ADMIN_KEY\"",
      "section_id": "create-an-agent-key"
    },
    {
      "id": "create-an-agent-key-ex1",
      "language": "bash",
      "code": "export CTX_AGENT_KEY='<the returned key, starts with cs_agent_>'",
      "section_id": "create-an-agent-key"
    },
    {
      "id": "list-the-generated-tools-ex0",
      "language": "bash",
      "code": "ctxctl tools list --agent-key \"$CTX_AGENT_KEY\"",
      "section_id": "list-the-generated-tools"
    },
    {
      "id": "call-a-tool-ex0",
      "language": "bash",
      "code": "ctxctl tools call search_customer_by_text --agent-key \"$CTX_AGENT_KEY\" --args '{\"query\": \"jane\", \"limit\": 5}'",
      "section_id": "call-a-tool"
    },
    {
      "id": "clean-up-ex0",
      "language": "bash",
      "code": "ctxctl surface delete \"$CTX_SURFACE_ID\" --admin-key \"$CTX_ADMIN_KEY\" --confirm",
      "section_id": "clean-up"
    }
  ]
}