redis-agent-lens

Python management and read clients for Redis Lens. This alpha prerelease contains the control-plane and data-plane REST APIs. Telemetry collection and OTel instrumentation are owned by redis-iris. This package does not import OpenTelemetry, initialize tracing, or export spans.

Installation and status

Prepared version: 0.1.0a3. Not published by this change.

pip install redis-agent-lens==0.1.0a3

Install after publication; pin alpha versions. Breaking changes may occur between alpha releases. Redis AI documentation and package page.

Two independently configured clients

LensService manages the deployment/account's singleton instance. Lens reads one instance. Configure each URL and credential explicitly. Cloud instance responses include endpoint candidates and accessibility metadata; select an appropriate endpoint for the deployment. The package does not select an endpoint or mint a read key.

from redis_agent_lens import Lens, LensService

with LensService(server_url=service_url, token=service_token) as service:
    instance = service.get_instance()

with Lens(server_url=read_url, instance_id=instance.instance_id, api_key=read_key) as lens:
    agents = lens.list_agents()
    sessions = lens.list_sessions(agent_id="support-bot", range="24h")

LensService has get/update instance and cloud-only register/delete instance, list databases, and get network info for control-plane egress allow-listing. Call list_databases() once and select databases whose eligible_roles contain records or content; the request takes no role filter. An empty role list means the database is not ready or cannot fill either role. Records require a Pro or Essentials RAM database; content can use RAM or Flex. Readiness and control-plane accessibility are also returned; registration still performs live checks. On-prem instances are provisioned at startup and have no registration, deletion or discovery routes. Cloud responses include database bindings and endpoint candidates; on-prem get/update responses omit them. Cloud get/update/register/delete and database discovery require the operator JWT, matching SM JSESSIONID cookie and CSRF token. Use a session-aware transport/fetcher to supply these on every request. Network info requires operator read authority. Dependent-resource failures return a typed 424 error across all six management operations.

Cloud registration returns HTTP 201 and creates a new instance ID. Registering when an instance already exists returns a typed 409 conflict, even for the same databases. To change databases, call delete_instance(x_csrf_token=csrf_token) and then register again. Deletion returns no value (HTTP 204); deleting an absent instance, including retrying after success, raises a typed 404. Deletion removes Lens data from reachable bound databases and skips unreachable or deleted databases. Keys for the deleted instance stop working; mint keys for the new instance ID after registering again. The async method is delete_instance_async().

For cloud database selection:

with LensService(server_url=service_url, token=service_token) as service:
    databases = service.list_databases().databases
    records_databases = [db for db in databases if "records" in db.eligible_roles]

Lens has list agents, list sessions, get session, get turn, get content, and get Context Retriever result. instanceId is bound on the client. Session lists require agent and range, support repeated outcome filters, and expose the opaque next cursor without promising snapshot isolation. Preserve the filters across pages. Session detail currently returns retained turn summaries together; the server rejects sessions over its current 10,000-turn cap.

Turn IDs are OTel trace IDs. Turn detail includes component observations and content references. Fetch content separately and inspect availability before using its body: expired/not-captured/masked are valid states, not HTTP failures. The wire envelope contains base64 bytes. The generated body representation is shown in the operation/model reference; no implicit text or JSON parsing occurs.

Credentials and transports

• DP accepts a Bearer instance key with read or full. Cloud UI reads also accept an SM JWT with Lens read authority and matching tenant; supply it via the same api_key/apiKey option. SM JWTs do not authorize OTLP ingest.
• CP uses token; its fallback is LENS_SERVICE_TOKEN.
• DP fallback is LENS_API_KEY. Neither client reads the existing instrumentation credential IRIS_LENS_API_KEY or falls back to the other plane.
• Clients support independent transports, callable credentials, timeouts, and explicit retry configuration. Retries are not enabled by default.
• CP models/errors live under redis_agent_lens.controlplane; DP models/errors retain their own namespace.

Python supports sync/async methods (async suffix _async), context managers, and caller-owned HTTP clients. The SDK takes a service root. For a gateway that already inserts /v1/instances/<id>, adapt its fetcher to avoid duplicating that prefix.

See DP operations and CP operations. Internal grant callbacks, Identity key lifecycle, OTLP ingestion, and planned backend APIs are excluded. Use redis-iris for telemetry collection and instrumentation.