Metadata-Version: 2.4
Name: aniket-agentlens-sdk
Version: 0.1.0
Summary: Python tracing SDK for AgentLens, an open-source observability platform for AI agents.
Author-email: Aniket Gopal <gopal.aniket@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/aniketgopal/agentlens
Project-URL: Repository, https://github.com/aniketgopal/agentlens
Project-URL: Issues, https://github.com/aniketgopal/agentlens/issues
Project-URL: Documentation, https://github.com/aniketgopal/agentlens/tree/main/docs
Keywords: agents,ai,llm,observability,security,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests<3.0.0,>=2.32.0
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.2; extra == "dev"
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.1.0; extra == "dev"

# AgentLens Python SDK

`aniket-agentlens-sdk` is the Python tracing SDK for AgentLens.

It lets another Python application instrument agent runs and steps with a small decorator-based API while sending trace data to a running AgentLens backend.

## Install

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

Import path:

```python
from agentlens import AgentLens, trace_agent, trace_step
```

The PyPI distribution name and the Python import name are intentionally different:

- install name: `aniket-agentlens-sdk`
- import name: `agentlens`

## Quick Start

```python
from agentlens import AgentLens, trace_agent, trace_step

AgentLens(
    api_key="al_sk_your_key",
    project_id="proj_your_project",
    endpoint="http://localhost:8000",
).configure()


@trace_step(type="tool_call", name="search_candidates")
def search_candidates(query: str) -> dict[str, object]:
    return {"matches": ["candidate_1", "candidate_2"], "query": query}


@trace_agent(name="candidate_screening_agent")
def run_agent(message: str) -> dict[str, object]:
    result = search_candidates(message)
    return {"message": "done", "result": result}
```

## Runtime Flow

1. `AgentLens(...).configure()` sets the default SDK client.
2. `@trace_agent` creates a traced run.
3. `@trace_step` creates nested steps under the current run.
4. The SDK sends HTTP requests to the AgentLens backend.
5. The backend stores, masks, and analyzes the trace for display in the dashboard.

## Requirements

- Python `>=3.11`
- A running AgentLens backend
- A valid AgentLens `project_id`
- A valid AgentLens ingestion API key

## Links

- Repository: https://github.com/aniketgopal/agentlens
- Documentation: https://github.com/aniketgopal/agentlens/tree/main/docs
