> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.aiplanet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python tracing SDK

> Record agent runs, steps, tool calls, and feedback as OpenTelemetry traces with the optional Python SDK.

The optional `aiplanet-agentops` Python package records an application's agent
runs, nested steps, tool calls, and feedback as standard OpenTelemetry traces.
It correlates model requests routed through the AI Planet gateway without
patching the OpenAI SDK.

## Basic usage

Install the approved package build with the OTLP export extra, then initialize it
once during application startup:

```python theme={null}
import os

import aiplanet_agentops as agentops

agentops.init(
    app="analytics-assistant",
    tenant="tenant-a",
    environment="production",
    otlp_endpoint=os.environ["AGENTOPS_OTLP_TRACES_ENDPOINT"],
    otlp_headers={"Authorization": os.environ["AGENTOPS_OTLP_AUTHORIZATION"]},
)
```

Wrap each end-to-end task and its meaningful steps:

```python theme={null}
with agentops.run(
    "answer-question",
    input={"question": question},
    user_ref="opaque-user-7",
    session_ref="conversation-42",
    tags=["analytics", "api"],
) as run:
    with agentops.span("classify") as step:
        response = openai_client.chat.completions.create(
            model="fast",
            messages=messages,
            metadata=agentops.gateway_metadata(agent="analytics.classify"),
        )
        step.set_output({"intent": "aggregation"})

    run.set_output({"answerable": True})
```

The metadata helper attaches the active trace, parent span, run, tenant,
application, environment, agent, and optional user/session identifiers. The gateway verifies scope
assertions against the application key before forwarding a request. Operators
configure the gateway and SDK to use the same OTLP-compatible backend; the
gateway then emits one child generation carrying its authoritative route, usage,
cost, latency, and outcome. Requests do not wait for that bounded export.

Runs and spans map to typed backend-neutral observations. Gateway model calls
remain generation observations carrying authoritative model, token, cost, and
latency data; tool, retrieval, guardrail, retry, and application-step spans keep
the control flow around them. Direct provider callers can use
`agentops.generation(...).set_usage(...)` with provider-returned values.

## Data handling

Input and output content is not exported by default. The SDK records redacted
type, size, and digest attributes so repeated calls and loops can still be
identified. Content capture is an explicit opt-in with a maximum size and must
follow your trace backend's access, region, retention, and deletion policy.

Exception details are also disabled by default. Export is asynchronous and
bounded; an unavailable trace backend does not fail the agent request.

Call `agentops.shutdown()` from the application shutdown hook so the final batch
has a bounded opportunity to flush.