Metadata-Version: 2.4
Name: agentlens-sdk
Version: 0.2.0
Summary: Python SDK for AgentLens — observability for AI agents
Project-URL: Homepage, https://github.com/ArkFelix7/agentlens
Project-URL: Repository, https://github.com/ArkFelix7/agentlens
Project-URL: Documentation, https://github.com/ArkFelix7/agentlens#readme
Project-URL: Bug Tracker, https://github.com/ArkFelix7/agentlens/issues
Author: AgentLens Contributors
License: MIT
Keywords: agents,ai,anthropic,debugging,llm,observability,openai,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.10.0
Requires-Dist: python-ulid>=2.7.0
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: anthropic>=0.34.0; extra == 'all'
Requires-Dist: langchain-core>=0.3.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# agentlens-sdk

Python SDK for [AgentLens](https://github.com/ArkFelix7/agentlens) — real-time observability and debugging for AI agents.

## Install

```bash
pip install agentlens-sdk
```

With framework extras:

```bash
pip install "agentlens-sdk[openai]"
pip install "agentlens-sdk[anthropic]"
pip install "agentlens-sdk[langchain]"
pip install "agentlens-sdk[all]"
```

## Prerequisites

Start the AgentLens server first:

```bash
pip install agentlens-server
agentlens-server
# Server running at http://localhost:8766
```

Then open the dashboard at `http://localhost:5173`.

## Usage

### Option 1: Auto-instrument (recommended)

```python
from agentlens_sdk import auto_instrument

auto_instrument()  # patches OpenAI + Anthropic clients automatically

# All subsequent OpenAI/Anthropic calls are traced — no other changes needed
import openai
client = openai.AsyncOpenAI()
response = await client.chat.completions.create(...)
```

### Option 2: @trace decorator

```python
from agentlens_sdk import init, trace

init(server_url="ws://localhost:8766/ws")

@trace(name="my_agent")
async def my_agent(query: str) -> str:
    result = await call_llm(query)
    return result
```

### Option 3: Manual spans

```python
from agentlens_sdk import get_tracer

async def my_agent(query: str) -> str:
    with get_tracer().span("my_agent") as span:
        span.set_attribute("query", query)
        result = await call_llm(query)
        span.set_output(result)
        return result
```

## Framework Integrations

### LangChain

```python
from agentlens_sdk.interceptors.langchain_interceptor import AgentLensCallbackHandler

handler = AgentLensCallbackHandler()
chain = my_chain.with_config(callbacks=[handler])
```

### CrewAI

```python
from agentlens_sdk import auto_instrument
auto_instrument()  # CrewAI is auto-detected
```

### AutoGen

```python
from agentlens_sdk import auto_instrument
auto_instrument()  # AutoGen ConversableAgent is auto-detected
```

## Configuration

```python
from agentlens_sdk import init

init(
    server_url="ws://localhost:8766/ws",   # AgentLens server WebSocket URL
    http_url="http://localhost:8766",       # AgentLens server HTTP URL
    session_name="my-agent-v2",            # Optional: name shown in dashboard
)
```

## Design Principles

- **Never raises exceptions** — all SDK operations are silent on failure. Your agent always runs.
- **Non-blocking** — async, buffered, batch-sent. Adds <5ms overhead per traced call.
- **Auto session management** — creates a session on first event, closes it on process exit.
- **Sensitive data redaction** — fields named `api_key`, `token`, `password`, `secret`, `authorization` are automatically replaced with `[REDACTED]`.
- **Graceful degradation** — if the server isn't running, events are silently dropped.

## License

MIT
