agent-governance-telemetry 0.1.0

Framework-agnostic agent governance and telemetry library

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

pip install agent-governance

Quick Start

1. Set Platform URL

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

2. Add Decorator to Your Agent

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

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

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

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

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

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

# Optional
export AGENT_GOVERNANCE_API_KEY=your-api-key

Decorator Parameters

@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

# 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.