# Lens quickstart ```json metadata { "schema_version": 2, "title": "Lens quickstart", "description": "Trace one agent turn with the Redis Iris SDK, then find it in Lens and read it back with the read API.", "categories": ["docs","develop","ai"], "tableOfContents": {"sections":[{"id":"before-you-begin","title":"Before you begin"},{"id":"install-the-sdk","title":"Install the SDK"},{"id":"configure-the-sdk","title":"Configure the SDK"},{"id":"trace-one-turn","title":"Trace one turn"},{"id":"find-the-turn","title":"Find the turn"},{"id":"next-steps","title":"Next steps"}]} , "codeExamples": [{"codetabsId":"iris_lens_quickstart-steptrace_turn","difficulty":"beginner","id":"trace_turn","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_lens_quickstart-steptrace_turn"}]},{"codetabsId":"iris_lens_quickstart-stepfind_turn","difficulty":"beginner","id":"find_turn","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_lens_quickstart-stepfind_turn"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_lens_quickstart-stepfind_turn"}]}] } ``` ## Code examples These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough. Trace 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). ## Before you begin 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. - The Iris host, such as `https://iris.example.com`. The SDK sends turns there, and the read client reads them back from there. - An ingest key, for sending turns. - Your instance ID and a read key, for reading turns back. You 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). ## Install the SDK Install the Redis Iris SDK, which includes Lens instrumentation, and the Lens read client: ```bash python -m venv .venv source .venv/bin/activate python -m pip install 'redis-iris[llm-tracing]>=1.0.0' python -m pip install 'redis-agent-lens>=1.0.0' ``` The `llm-tracing` extra traces OpenAI, Anthropic, Amazon Bedrock, and LangChain model calls automatically. `redis-agent-lens` is the read client the last step uses. ## Configure the SDK Export these values in the shell where you run the example: ```bash export IRIS_LENS_ENDPOINT='' export IRIS_LENS_API_KEY='' export IRIS_LENS_AGENT_ID='lens-quickstart' export LENS_URL='' export LENS_INSTANCE_ID='' export LENS_API_KEY='' ``` Setting `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. Keep keys out of source control and model prompts. ## Trace one turn Expand the example to copy the complete program. Save it as `quickstart.py`, then run `python quickstart.py`. This turn wraps one OpenAI call. The `llm-tracing` extra records the call as a step in the turn. **Available in:** Python (Iris) ##### Python (Iris) ```python import uuid from openai import OpenAI from redis_iris import lens lens.init() client = OpenAI() session_id = f"quickstart-{uuid.uuid4().hex[:8]}" with lens.turn(session_id, user_id="user-1042") as turn: response = client.responses.create( model="gpt-4.1-mini", input="Where can I see my refund status?", ) print(response.output_text) turn.set_outcome("completed") turn_id = turn.trace_id print(f"Session: {session_id}") print(f"Turn: {turn_id}") ``` The example prints the session ID and the turn ID. Keep both to find the turn. ## Find the turn A turn is readable a few seconds after its export. To view it in Lens: 1. 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). 1. Select the `lens-quickstart` agent. 1. Select the session that matches the printed session ID. 1. Expand the turn. The turn shows the model call as a step, with its prompt, completion, and token counts. To read the same turn with the read API, set `TURN_ID` for the cURL example first: ```bash export TURN_ID='' ``` **Available in:** Python (Iris), cURL (Iris) ##### Python (Iris) ```python import os import time from redis_agent_lens import Lens, errors with Lens( server_url=os.environ["LENS_URL"], instance_id=os.environ["LENS_INSTANCE_ID"], ) as reader: for _ in range(30): try: detail = reader.get_turn(turn_id=turn_id) break except errors.NotFoundErrorResponseContent: time.sleep(2) else: raise RuntimeError("The turn isn't readable. Check the iris.lens warnings for an export error.") print(f"Outcome: {detail.outcome.value}") print(f"Tokens: {detail.tokens.total}") ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ "${LENS_URL%/}/iris/data/v1beta1/lens/instances/$LENS_INSTANCE_ID/turns/$TURN_ID" \ -H "Authorization: Bearer $LENS_API_KEY" \ | jq '{outcome, tokens: .tokens.total}' ``` The Python example retries until the turn is readable, then prints its outcome and token count: ``` Outcome: COMPLETED Tokens: ``` ## Next steps - [Learn the concepts](https://redis.io/docs/latest/develop/ai/context-engine/lens/concepts) behind sessions, turns, and steps. - [Instrument an agent](https://redis.io/docs/latest/develop/ai/context-engine/lens/instrument) to record retrievals, model calls, and custom steps. - [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).