{
  "schema_version": 2,
  "id": "develop/ai/context-engine/lens/quickstart",
  "title": "Lens quickstart",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/quickstart/",
  "summary": "Trace one agent turn with the Redis Iris SDK, then find it in Lens and read it back with the read API.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T15:31:39-08:00",
  "page_type": "content",
  "content_hash": "79b2ec3a5130146c35b6e041a0f4787f1f50d12ad4d1834b1bb49091a96f2b4e",
  "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.\n\n\nTrace one agent turn with the Redis Iris software development kit (SDK), then find it in Lens and read it back with the Lens read application programming interface (API)."
    },
    {
      "id": "before-you-begin",
      "title": "Before you begin",
      "role": "content",
      "text": "Get these values. On Redis Cloud, [create Lens and its keys](https://redis.io/docs/latest/operate/iris/lens/create-lens). Self-managed, get them from your administrator, who [hands them off](https://redis.io/docs/latest/operate/iris/lens/self-managed/deploy#hand-off-to-developers) after deploying Lens.\n\n- The Iris host, such as `https://iris.example.com`. The SDK sends turns there, and the read client reads them back from there.\n- An ingest key, for sending turns.\n- Your instance ID and a read key, for reading turns back.\n\nYou also need Python 3.11 or later. The cURL example uses Bash and jq. The example calls OpenAI, so it also needs the `openai` package and an `OPENAI_API_KEY`. Any model client that the `llm-tracing` extra supports works the same way. For the configuration `redis-iris` reads across services, see [SDK and CLI setup](https://redis.io/docs/latest/develop/ai/context-engine/sdk-and-cli)."
    },
    {
      "id": "install-the-sdk",
      "title": "Install the SDK",
      "role": "setup",
      "text": "Install the Redis Iris SDK, which includes Lens instrumentation, and the Lens read client:\n\n[code example]\n\nThe `llm-tracing` extra traces OpenAI, Anthropic, Amazon Bedrock, and LangChain model calls automatically. `redis-agent-lens` is the read client the last step uses."
    },
    {
      "id": "configure-the-sdk",
      "title": "Configure the SDK",
      "role": "configuration",
      "text": "Export these values in the shell where you run the example:\n\n[code example]\n\nSetting `IRIS_LENS_ENDPOINT` turns Lens on. Use the host only, including `https://`. The SDK adds the Lens path. The SDK sends `IRIS_LENS_API_KEY` with every export, and the read client sends `LENS_API_KEY` with every read.\n\nKeep keys out of source control and model prompts."
    },
    {
      "id": "trace-one-turn",
      "title": "Trace one turn",
      "role": "content",
      "text": "Expand the example to copy the complete program. Save it as `quickstart.py`, then run `python quickstart.py`.\n\nThis turn wraps one OpenAI call. The `llm-tracing` extra records the call as a step in the turn.\n\n**Available in:** Python (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n\n\nThe example prints the session ID and the turn ID. Keep both to find the turn."
    },
    {
      "id": "find-the-turn",
      "title": "Find the turn",
      "role": "content",
      "text": "A turn is readable a few seconds after its export.\n\nTo view it in Lens:\n\n1. Open Lens. On Redis Cloud, select **Lens** under **Iris** in the console menu; Lens uses your console sign-in. Self-managed, Lens asks for a credential: paste your read key and select **Connect**. Your administrator [connects Lens to the console](https://redis.io/docs/latest/operate/iris/lens/self-managed/operations#connect-the-console).\n1. Select the `lens-quickstart` agent.\n1. Select the session that matches the printed session ID.\n1. Expand the turn.\n\nThe turn shows the model call as a step, with its prompt, completion, and token counts.\n\nTo read the same turn with the read API, set `TURN_ID` for the cURL example first:\n\n[code example]\n\n**Available in:** Python (Iris), cURL (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n\n\nThe Python example retries until the turn is readable, then prints its outcome and token count:\n\n[code example]"
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "- [Learn the concepts](https://redis.io/docs/latest/develop/ai/context-engine/lens/concepts) behind sessions, turns, and steps.\n- [Instrument an agent](https://redis.io/docs/latest/develop/ai/context-engine/lens/instrument) to record retrievals, model calls, and custom steps.\n- [Integrate with an agent framework](https://redis.io/docs/latest/develop/ai/context-engine/lens/agent-integration) such as LangGraph, the OpenAI Agents SDK, or the Google Agent Development Kit (ADK)."
    }
  ],
  "examples": [
    {
      "id": "install-the-sdk-ex0",
      "language": "bash",
      "code": "python -m venv .venv\nsource .venv/bin/activate\npython -m pip install 'redis-iris[llm-tracing]>=1.0.0'\npython -m pip install 'redis-agent-lens>=1.0.0'",
      "section_id": "install-the-sdk"
    },
    {
      "id": "configure-the-sdk-ex0",
      "language": "bash",
      "code": "export IRIS_LENS_ENDPOINT='<iris-host>'\nexport IRIS_LENS_API_KEY='<lens-ingest-key>'\nexport IRIS_LENS_AGENT_ID='lens-quickstart'\n\nexport LENS_URL='<iris-host>'\nexport LENS_INSTANCE_ID='<lens-instance-id>'\nexport LENS_API_KEY='<lens-read-key>'",
      "section_id": "configure-the-sdk"
    },
    {
      "id": "trace-one-turn-ex0",
      "language": "python",
      "code": "import uuid\n\nfrom openai import OpenAI\nfrom redis_iris import lens\n\nlens.init()\nclient = OpenAI()\n\nsession_id = f\"quickstart-{uuid.uuid4().hex[:8]}\"\n\nwith lens.turn(session_id, user_id=\"user-1042\") as turn:\n    response = client.responses.create(\n        model=\"gpt-4.1-mini\",\n        input=\"Where can I see my refund status?\",\n    )\n    print(response.output_text)\n    turn.set_outcome(\"completed\")\n\nturn_id = turn.trace_id\nprint(f\"Session: {session_id}\")\nprint(f\"Turn: {turn_id}\")",
      "section_id": "trace-one-turn"
    },
    {
      "id": "find-the-turn-ex0",
      "language": "bash",
      "code": "export TURN_ID='<printed-turn-id>'",
      "section_id": "find-the-turn"
    },
    {
      "id": "find-the-turn-ex1",
      "language": "python",
      "code": "import os\nimport time\n\nfrom redis_agent_lens import Lens, errors\n\nwith Lens(\n    server_url=os.environ[\"LENS_URL\"],\n    instance_id=os.environ[\"LENS_INSTANCE_ID\"],\n) as reader:\n    for _ in range(30):\n        try:\n            detail = reader.get_turn(turn_id=turn_id)\n            break\n        except errors.NotFoundErrorResponseContent:\n            time.sleep(2)\n    else:\n        raise RuntimeError(\"The turn isn't readable. Check the iris.lens warnings for an export error.\")\n\nprint(f\"Outcome: {detail.outcome.value}\")\nprint(f\"Tokens: {detail.tokens.total}\")",
      "section_id": "find-the-turn"
    },
    {
      "id": "find-the-turn-ex2",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  \"${LENS_URL%/}/iris/data/v1beta1/lens/instances/$LENS_INSTANCE_ID/turns/$TURN_ID\" \\\n  -H \"Authorization: Bearer $LENS_API_KEY\" \\\n  | jq '{outcome, tokens: .tokens.total}'",
      "section_id": "find-the-turn"
    },
    {
      "id": "find-the-turn-ex3",
      "language": "plaintext",
      "code": "Outcome: COMPLETED\nTokens: <total-tokens>",
      "section_id": "find-the-turn"
    }
  ]
}