Lens quickstart

Trace one agent turn with the Redis Iris SDK, then find it in Lens and read it back with the read API.

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. Self-managed, get them from your administrator, who hands them off 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.

Install the SDK

Install the Redis Iris SDK, which includes Lens instrumentation, and the Lens read client:

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:

export IRIS_LENS_ENDPOINT='<iris-host>'
export IRIS_LENS_API_KEY='<lens-ingest-key>'
export IRIS_LENS_AGENT_ID='lens-quickstart'

export LENS_URL='<iris-host>'
export LENS_INSTANCE_ID='<lens-instance-id>'
export LENS_API_KEY='<lens-read-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.

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.
  2. Select the lens-quickstart agent.
  3. Select the session that matches the printed session ID.
  4. 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:

export TURN_ID='<printed-turn-id>'

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 --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: <total-tokens>

Next steps

RATE THIS PAGE
Back to top ↑