Python tracing 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:

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:

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.

Overview

Get Started

Administration

API Reference

Operations

Basic usage

Data handling

​Basic usage

​Data handling

Basic usage

Data handling