agentwatch-sdk 0.1.0
SDK for AgentWatch — observability for multi-agent AI systems
License: Apache-2.0
Requires Python: >=3.10

# AgentWatch SDK

[![PyPI](https://img.shields.io/pypi/v/agentwatch-sdk)](https://pypi.org/project/agentwatch-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/agentwatch-sdk)](https://pypi.org/project/agentwatch-sdk/)
[![License](https://img.shields.io/pypi/l/agentwatch-sdk)](https://github.com/srir84/aiagent/blob/main/LICENSE)

Observability SDK for multi-agent AI systems. Captures agent interactions, LLM calls, and tool usage with zero-config framework detection.

## Installation

```bash
pip install agentwatch-sdk
```

Install with framework support:

```bash
pip install agentwatch-sdk[openai-agents]   # OpenAI Agents SDK
pip install agentwatch-sdk[langgraph]       # LangGraph
pip install agentwatch-sdk[crewai]          # CrewAI
pip install agentwatch-sdk[google-adk]      # Google ADK
```

## Quick Start

```python
import agentwatch_sdk

agentwatch_sdk.init(
    public_key="aw_pub_...",
    secret_key="aw_sec_...",
    endpoint="http://localhost:8080",
)

# Your agent code here — auto-instrumented for supported frameworks

agentwatch_sdk.shutdown()
```

## Framework Examples

### OpenAI Agents SDK (automatic, zero-config)

```python
import agentwatch_sdk
from agents import Agent, Runner

agentwatch_sdk.init(public_key="...", secret_key="...", endpoint="http://localhost:8080")

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
result = await Runner.run(agent, input="Hello!")

agentwatch_sdk.shutdown()
```

### LangGraph (callback)

```python
import agentwatch_sdk

agentwatch_sdk.init(public_key="...", secret_key="...", endpoint="http://localhost:8080")
engine = agentwatch_sdk.get_engine()

result = app.invoke(
    {"input": "Hello!"},
    config={"callbacks": [engine.langgraph_handler]},
)

agentwatch_sdk.shutdown()
```

### CrewAI (per-crew)

```python
import agentwatch_sdk

agentwatch_sdk.init(public_key="...", secret_key="...", endpoint="http://localhost:8080")
engine = agentwatch_sdk.get_engine()

engine.crewai_instrument(crew)
result = crew.kickoff()

agentwatch_sdk.shutdown()
```

### Google ADK (per-runner)

```python
import agentwatch_sdk

agentwatch_sdk.init(public_key="...", secret_key="...", endpoint="http://localhost:8080")
engine = agentwatch_sdk.get_engine()

engine.adk_instrument(runner)
async for event in runner.run_async(user_id="user1", session_id="s1", new_message=msg):
    print(event)

agentwatch_sdk.shutdown()
```

## Configuration

### `init()` parameters

| Parameter | Env Variable | Default | Description |
|-----------|-------------|---------|-------------|
| `public_key` | `AGENTWATCH_PUBLIC_KEY` | — | API public key (`aw_pub_...`) |
| `secret_key` | `AGENTWATCH_SECRET_KEY` | — | API secret key (`aw_sec_...`) |
| `endpoint` | `AGENTWATCH_ENDPOINT` | `http://localhost:8080` | AgentWatch server URL |
| `flush_interval_ms` | — | `500` | How often to flush buffered spans (ms) |
| `flush_batch_size` | — | `100` | Max spans per flush batch |

Parameters passed to `init()` take precedence over environment variables.

## API Reference

### `agentwatch_sdk.init(**kwargs)`

Initialize the SDK and start background span export. Call this before running your agents. See [Configuration](#configuration) for available parameters.

### `agentwatch_sdk.shutdown()`

Flush any remaining buffered spans and stop the background exporter. Call this when your application exits.

### `agentwatch_sdk.get_engine()`

Returns the internal `AgentWatchEngine` instance. Use this to access framework-specific adapters:

- `engine.langgraph_handler` — LangGraph callback handler
- `engine.crewai_instrument(crew)` — Instrument a CrewAI crew
- `engine.adk_instrument(runner)` — Instrument a Google ADK runner

## Requirements

- Python >= 3.10

## License

Apache-2.0. See [LICENSE](../../LICENSE) for the full text.