agent-governance-telemetry 0.1.0
Framework-agnostic agent governance and telemetry library
License: MIT
Requires Python: >=3.9
Keywords: ai, agents, governance, telemetry, monitoring, opentelemetry

# Agent Governance Library

Framework-agnostic Python library for monitoring and governing AI agents with automatic telemetry, cost tracking, and OpenTelemetry integration.

## Features

- **Framework Agnostic**: Works with any Python agent framework (ADK, Strands, LangGraph, custom)
- **Automatic Tracking**: Token counting, cost calculation, duration measurement
- **OpenTelemetry**: Built-in traces, metrics, and logs
- **Zero Impact**: Non-blocking telemetry, graceful error handling
- **Simple Integration**: Single decorator to add governance

## Installation

```bash
pip install agent-governance
```

## Quick Start

### 1. Set Platform URL

```bash
export AGENT_GOVERNANCE_PLATFORM_URL=https://your-platform-url
export AGENT_GOVERNANCE_API_KEY=your-api-key  # optional
```

### 2. Add Decorator to Your Agent

```python
from agent_governance import track_agent

@track_agent(
    agent_id="my-agent-001",
    agent_name="My Agent",
    framework="strands"  # or "adk", "langgraph", "custom"
)
async def my_agent(query: str):
    # Your agent code here
    return result
```

That's it! Every execution is now tracked automatically.

## Usage Examples

### With Strands SDK

```python
from agent_governance import track_agent
from strands import Agent
from strands.models import VertexAIModel

model = VertexAIModel(model="gemini-2.0-flash-exp")
agent = Agent(name="my_agent", model=model)

@track_agent(agent_id="strands-agent-001", framework="strands")
async def execute_agent(query: str):
    response = await agent.run(query)
    return {"result": response.content}
```

### With LangGraph

```python
from agent_governance import track_agent
from langgraph.prebuilt import create_react_agent

agent = create_react_agent(model=llm, tools=[])

@track_agent(agent_id="langgraph-agent-001", framework="langgraph")
async def execute_agent(query: str):
    result = await agent.ainvoke({"messages": [...]})
    return {"result": result}
```

### With Google ADK

```python
from agent_governance import track_agent

@track_agent(agent_id="adk-agent-001", framework="adk")
async def execute_agent(query: str):
    # Your ADK agent code
    return result
```

### With Custom Framework

```python
from agent_governance import track_agent

@track_agent(agent_id="custom-agent-001", framework="custom")
def my_custom_agent(input_data):
    # Any Python function
    result = process(input_data)
    return result
```

## What Gets Tracked

For every agent execution:

| Metric | Description |
|--------|-------------|
| agent_id | Unique identifier |
| agent_name | Human-readable name |
| execution_id | Per-call UUID |
| framework | Framework used |
| timestamp | Execution time |
| duration | Time taken (seconds) |
| input_tokens | Request tokens |
| output_tokens | Response tokens |
| total_tokens | Sum of tokens |
| cost | Calculated cost ($) |
| status | success/error |
| error | Error message if failed |

## Configuration

### Environment Variables

```bash
# Required
export AGENT_GOVERNANCE_PLATFORM_URL=https://your-platform-url

# Optional
export AGENT_GOVERNANCE_API_KEY=your-api-key
```

### Decorator Parameters

```python
@track_agent(
    agent_id="my-agent",           # Required: Unique identifier
    agent_name="My Agent",         # Optional: Display name
    api_key="...",                 # Optional: Override env var
    platform_url="https://...",    # Optional: Override env var
    framework="strands"            # Optional: Framework name
)
```

## Cost Tracking

Automatic cost calculation based on token usage:

| Model | Input (per 1M tokens) | Output (per 1M tokens) |
|-------|----------------------|------------------------|
| gemini-2.0-flash | $0.075 | $0.30 |
| gemini-1.5-pro | $1.25 | $5.00 |
| gpt-4o | $2.50 | $10.00 |
| gpt-4o-mini | $0.15 | $0.60 |

## OpenTelemetry Integration

The library automatically:
- Creates spans for each execution
- Records metrics (executions, tokens, cost, duration)
- Sends traces to your platform
- Exports to OTLP-compatible backends

## Error Handling

The library is designed to never break your agent:
- Telemetry failures are caught and logged
- Non-blocking async operations
- Graceful degradation if platform is unavailable

## Requirements

- Python >= 3.9
- opentelemetry-api >= 1.20.0
- opentelemetry-sdk >= 1.20.0
- opentelemetry-exporter-otlp >= 1.20.0
- requests >= 2.31.0

## Platform Setup

This library requires a governance platform to receive telemetry. You can:

1. Deploy the included platform (see platform documentation)
2. Use any OTLP-compatible backend
3. Build your own receiver

## Development

```bash
# Install in development mode
pip install -e .

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest
```

## License

MIT License - see LICENSE file for details

## Support

- GitHub Issues: https://github.com/yourusername/agent-governance/issues
- Documentation: https://github.com/yourusername/agent-governance#readme

## Contributing

Contributions welcome! Please read CONTRIBUTING.md first.