Metadata-Version: 2.2
Name: agentmetrics
Version: 0.1.2
Summary: Monitor your AI agents. Track cost, latency, and errors in two lines of code.
License: MIT
Project-URL: Homepage, https://agentmetrics.dev
Project-URL: Repository, https://github.com/andalabx/agentmetrics-sdk
Project-URL: Documentation, https://agentmetrics.dev/docs
Keywords: ai agent monitoring,llm monitoring,ai agent observability,llm observability,langchain monitoring,crewai monitoring,openai cost tracker,llm cost tracking,ai agent tracing,open source llm monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# agentmetrics — Python SDK

[![PyPI](https://img.shields.io/pypi/v/agentmetrics?color=009E80&label=pypi&logo=python&logoColor=white)](https://pypi.org/project/agentmetrics)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-3776AB?logo=python&logoColor=white)](https://pypi.org/project/agentmetrics)
[![License: MIT](https://img.shields.io/badge/license-MIT-009E80)](../LICENSE)

Production observability for AI agents. Track cost, latency, tokens, failures, and tool calls — one decorator, zero infrastructure.

→ **[agentmetrics.dev/docs/sdk/python](https://agentmetrics.dev/docs/sdk/python)**

---

## Install

```bash
pip install agentmetrics
```

Requires Python 3.9 or later.

---

## Quickstart

```python
import os
import agentmetrics

agentmetrics.configure(api_key=os.environ["AGENTMETRICS_API_KEY"])
agentmetrics.instrument()  # auto-patches OpenAI, Anthropic, LiteLLM, and more

@agentmetrics.track(agent_id="my-agent")
def run(task: str) -> str:
    answer = call_llm(task)
    return answer
```

Every call to `run()` reports to your dashboard: duration, cost, token usage, success/failure, and error messages.

---

## API

### `agentmetrics.configure()`

Call once at startup before any `@track` decorators execute.

```python
agentmetrics.configure(
    api_key="am_live_...",       # required
    environment="production",    # optional — tags every run
    sample_rate=1.0,             # optional — float 0.0–1.0
    base_url="https://...",      # optional — override for self-hosted
    batch_size=20,               # optional — events per batch
    flush_interval=2.0,          # optional — seconds between flushes
)
```

### `agentmetrics.instrument()`

Patches installed LLM SDKs to auto-capture token counts and model names on every call. Idempotent.

```python
agentmetrics.instrument()
```

Supported: **OpenAI** (+ Azure, Groq, Together AI) · **Anthropic** · **LiteLLM** · **Google Gemini** · **Cohere** · **Mistral** · **LangChain / LangGraph / CrewAI** · **LlamaIndex**

### `@agentmetrics.track()`

Decorator for sync and async agent functions.

```python
@agentmetrics.track(agent_id="my-agent", metadata={"env": "prod"})
def run(task: str) -> str:
    return call_llm(task)

@agentmetrics.track(agent_id="async-agent")
async def run_async(task: str) -> str:
    return await call_llm_async(task)
```

| Parameter | Type | Description |
|---|---|---|
| `agent_id` | `str` | Identifier shown in the dashboard |
| `metadata` | `dict` | Optional key-value pairs attached to every run |

### `agentmetrics.step()`

Context manager for timing a named phase within a tracked agent.

```python
@agentmetrics.track(agent_id="pipeline")
def run(query: str) -> str:
    with agentmetrics.step("retrieve"):
        docs = vector_search(query)
    with agentmetrics.step("generate"):
        return call_llm(query, docs)
```

### `agentmetrics.tool()`

Context manager for tracking individual tool calls.

```python
@agentmetrics.track(agent_id="research-agent")
def run(query: str) -> str:
    with agentmetrics.tool("web_search"):
        results = web_search(query)
    return summarize(results)
```

### `agentmetrics.flush()`

Blocks until all queued events are sent. Call before process exit in scripts.

```python
agentmetrics.flush(timeout=10.0)
```

### `agentmetrics.trace_id`

Returns the active trace ID from inside a tracked function.

```python
@agentmetrics.track(agent_id="my-agent")
def run(task: str) -> str:
    print(agentmetrics.trace_id)  # e.g. "a3f1c2d4-..."
    return call_llm(task)
```

---

## License

[MIT](../LICENSE)
