python-sdk

agentlensai

Python SDK for AgentLens — observability and audit trail for AI agents.

Installation

pip install agentlensai

Quick Start — Auto-Instrumentation

The fastest way to get started. One call instruments all installed LLM providers automatically.

import agentlensai

session_id = agentlensai.init(
    agent_id="my-agent",
    api_key="als_xxx",  # or set AGENTLENS_API_KEY
)

# That's it! All OpenAI/Anthropic/etc. calls are now tracked.
import openai
client = openai.OpenAI()
client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)
# ^ This call is automatically captured by AgentLens

# When done:
agentlensai.shutdown()

init() Parameters

Parameter	Default	Description
url	http://localhost:3400	Server URL (positional)
server_url	—	Server URL (keyword, takes precedence)
cloud	False	Use AgentLens Cloud (https://api.agentlens.ai)
api_key	AGENTLENS_API_KEY env	API key
agent_id	"default"	Agent identifier
session_id	auto-generated	Session ID
redact	False	Strip prompt/completion content
pii_patterns	None	List of regex patterns for PII filtering
pii_filter	None	Custom filter function for strings
sync_mode	False	Send events synchronously
integrations	"auto"	Which providers to instrument

Environment Variables

Env Var	Description
AGENTLENS_SERVER_URL	Server URL
AGENTLENS_API_KEY	API key

Manual Client Usage

from agentlensai import AgentLensClient

client = AgentLensClient("http://localhost:3400", api_key="als_xxx")

# Query events
result = client.query_events(agent_id="my-agent", limit=10)
for event in result.events:
    print(event.event_type, event.timestamp)

# Log an LLM call manually
from agentlensai import LogLlmCallParams, LlmMessage, TokenUsage

result = client.log_llm_call(
    session_id="sess-1",
    agent_id="my-agent",
    params=LogLlmCallParams(
        provider="openai",
        model="gpt-4",
        messages=[LlmMessage(role="user", content="Hello")],
        completion="Hi there!",
        finish_reason="stop",
        usage=TokenUsage(input_tokens=5, output_tokens=3, total_tokens=8),
        cost_usd=0.001,
        latency_ms=450,
    ),
)
print(result.call_id)

# Context manager
with AgentLensClient("http://localhost:3400") as client:
    health = client.health()

Async Client

from agentlensai import AsyncAgentLensClient

async def main():
    async with AsyncAgentLensClient("http://localhost:3400", api_key="als_xxx") as client:
        events = await client.query_events(agent_id="my-agent")
        health = await client.health()

PII Filtering

Filter sensitive data before it leaves your application.

Built-in Patterns

import agentlensai
from agentlensai import PII_EMAIL, PII_SSN, PII_CREDIT_CARD, PII_PHONE

agentlensai.init(
    agent_id="my-agent",
    pii_patterns=[PII_EMAIL, PII_SSN, PII_CREDIT_CARD, PII_PHONE],
)
# All email addresses, SSNs, credit cards, and phone numbers
# are replaced with [REDACTED] before sending.

Custom Filter

import re

def my_filter(text: str) -> str:
    return re.sub(r"password=\S+", "password=[REDACTED]", text)

agentlensai.init(
    agent_id="my-agent",
    pii_filter=my_filter,
)

Full Redaction

agentlensai.init(agent_id="my-agent", redact=True)
# All prompt/completion content is stripped entirely.

Provider Examples

OpenAI

import agentlensai
import openai

agentlensai.init(agent_id="my-agent")

client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
)
# Automatically tracked!

Anthropic

import agentlensai
import anthropic

agentlensai.init(agent_id="my-agent")

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
# Automatically tracked!

Selective Instrumentation

# Only instrument OpenAI
agentlensai.init(agent_id="my-agent", integrations="openai")

# Instrument specific providers
agentlensai.init(agent_id="my-agent", integrations=["openai", "anthropic"])

Error Handling

from agentlensai import (
    AgentLensError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    AgentLensConnectionError,
    RateLimitError,
    QuotaExceededError,
    BackpressureError,
)

try:
    client.get_event("bad-id")
except NotFoundError:
    print("Event not found")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except AgentLensConnectionError:
    print("Server unreachable")

Lessons API (Deprecated)

Lesson methods are deprecated. Use lore-sdk instead.