Metadata-Version: 2.5
Name: amp-instrumentation
Version: 0.4.2
Summary: Automatic instrumentation for Python agent applications, monitored via WSO2 Agent Management Platform
Project-URL: Repository, https://github.com/wso2/agent-manager
Author-email: WSO2 <hansi@wso2.org>
Maintainer-email: WSO2 <hansi@wso2.org>
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http
Requires-Dist: opentelemetry-sdk
Requires-Dist: requests
Requires-Dist: traceloop-sdk==0.62.4
Requires-Dist: wrapt<2.0.0
Description-Content-Type: text/markdown

# WSO2 Agent Manager Instrumentation

Zero-code OpenTelemetry instrumentation for Python agents using the Traceloop SDK, with trace visibility in the WSO2 Agent Manager.

## Overview

`amp-instrumentation` enables zero-code instrumentation for Python agents, automatically capturing traces for LLM calls, MCP requests, and other operations. It seamlessly wraps your agent’s execution with OpenTelemetry tracing powered by the Traceloop SDK.

For agents on a custom or non-frontier framework, or anywhere you want full control over the spans you emit, it also ships `init_otel()`, a one-line OpenTelemetry exporter setup so you can instrument the agent yourself against AMP's instrumentation contract. See [Manual instrumentation](#manual-instrumentation).

## Features

- **Zero Code Changes**: Instrument existing applications without modifying code
- **Automatic Tracing**: Traces LLM calls, MCP requests, database queries, and more
- **OpenTelemetry Compatible**: Uses industry-standard OpenTelemetry protocol
- **Flexible Configuration**: Configure via environment variables
- **Framework Agnostic**: Works with any Python application built using a wide range of agent frameworks supported by the TraceLoop SDK
- **Manual path**: `init_otel()` for agents that emit their own OpenTelemetry GenAI spans
- **Conversation on the root span**: the conversation ID is copied onto each trace's root span, so the Agent Manager can list and filter traces by conversation cheaply. See [Conversation ID](#conversation-id)

## Installation

```bash
pip install amp-instrumentation
```

Each release of `amp-instrumentation` pins a specific Traceloop SDK version, so a given `amp-instrumentation` version always installs a fully determined SDK. To use a different Traceloop SDK version, install a different `amp-instrumentation` version.

## Quick Start

### 1. Register Your Agent

First, register your agent at the [WSO2 Agent Manager](https://github.com/wso2/agent-manager) to obtain your agent API key and configuration details.

### 2. Set Required Environment Variables

```bash
export AMP_OTEL_ENDPOINT="https://amp-otel-endpoint.com" # AMP OTEL endpoint
export AMP_AGENT_API_KEY="your-agent-api-key" # Agent-specific key generated after registration
```

Optional: prompt and completion content is captured by default. To suppress it, set `TRACELOOP_TRACE_CONTENT=false`.

### 3. Run Your Application

Use the `amp-instrument` command to wrap your application run command:

```bash
# Run a Python script
amp-instrument python my_script.py

# Run with uvicorn
amp-instrument uvicorn app:main --reload

# Run with any package manager
amp-instrument poetry run python script.py
amp-instrument uv run python script.py
```

That's it! Your application is now instrumented and sending traces to the WSO2 Agent Manager.

## Conversation ID

Frameworks such as LangGraph record the conversation (for example the `thread_id`) on the spans they create, not on a server span or your own agent span that wraps them. Both `amp-instrument` and `init_otel()` add a span processor that copies it onto the trace's root span as `gen_ai.conversation.id`, while the root is still open.

The processor reads each span that ends, in this order, and takes the first non-empty string (an integer becomes its decimal string; booleans and floats are ignored):

1. `gen_ai.conversation.id`
2. `session.id`
3. `langfuse.session.id`
4. `traceloop.association.properties.session_id`
5. `traceloop.association.properties.conversation_id`
6. `traceloop.association.properties.thread_id`
7. `langsmith.metadata.session_id`
8. `langsmith.metadata.thread_id`

It never overwrites an existing ID: a root that already has any of these attributes is left alone, and the first ID found is kept. There is nothing to configure. If the root span has a remote parent (your agent is called by another service that sends a `traceparent`), the attribute is set on your local root, but the trace's own root lives in the calling service and has to carry the ID itself.

## Manual instrumentation

If your agent uses a framework the Traceloop SDK doesn't cover — or you want to emit your own spans — instrument it yourself and send the spans to AMP. `init_otel()` configures the OpenTelemetry exporter (the same `AMP_OTEL_ENDPOINT` / `AMP_AGENT_API_KEY` environment variables as above); it does no instrumentation itself, so you control the spans:

```python
import json
from opentelemetry import trace
from amp_instrumentation import init_otel

init_otel()  # reads AMP_OTEL_ENDPOINT and AMP_AGENT_API_KEY from the environment
tracer = trace.get_tracer("my-agent")

with tracer.start_as_current_span("chat") as span:
    span.set_attribute("gen_ai.operation.name", "chat")
    span.set_attribute("gen_ai.system", "openai")
    span.set_attribute("gen_ai.request.model", "gpt-4o-mini")
    span.set_attribute("gen_ai.input.messages", json.dumps(input_messages))
    response = call_model(...)
    span.set_attribute("gen_ai.response.model", response.model)
    span.set_attribute("gen_ai.output.messages", json.dumps(response.messages))
    span.set_attribute("gen_ai.usage.input_tokens", response.usage.input_tokens)
    span.set_attribute("gen_ai.usage.output_tokens", response.usage.output_tokens)
```

Spans that follow AMP's instrumentation contract — the OpenTelemetry GenAI semantic conventions — render with the full trace view in the Agent Manager and run through evaluators; spans that don't still appear, just without the rich view. The contract and the full supported-attribute reference are published in the WSO2 Agent Manager documentation: see [Manual instrumentation](https://wso2.com/agent-platform/docs/latest/guides/amp-instrumentation/#manual-instrumentation) on the WSO2 Agent Manager Instrumentation page.

`init_otel()` is idempotent and is roughly ten lines of vanilla OpenTelemetry SDK setup (`TracerProvider` + `BatchSpanProcessor` + an OTLP/HTTP exporter to `<AMP_OTEL_ENDPOINT>/v1/traces` with the `x-amp-api-key` header) — use it so you don't have to write that yourself.
