Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Observe and actbreadcrumb arrow Agent Observabilitybreadcrumb arrow Get startedbreadcrumb arrow Instrument Python
Grafana Cloud

Instrument Python agents

This guide shows you how to install the Agent Observability Python SDK, instrument an LLM call, and verify that generation data reaches Agent Observability.

Before you begin

  • A Grafana Cloud stack with Agent Observability enabled.
  • Python 3.10 or later.
  • Your Agent Observability generation export endpoint URL.
  • A Cloud Access Policy Token. Refer to Collect credentials from Grafana Cloud for step-by-step instructions.

Install the SDK

Bash 
pip install agento11y

To use a provider helper, install the corresponding package:

Bash 
pip install agento11y-openai
pip install agento11y-anthropic
pip install agento11y-gemini

Use a framework integration

If you use LangChain, LangGraph, OpenAI Agents, LlamaIndex, Google ADK, Strands Agents, Claude Agent SDK, LiteLLM, or Pydantic AI, install the corresponding framework package for automatic generation capture:

Bash 
pip install agento11y-langchain
pip install agento11y-langgraph
pip install agento11y-openai-agents
pip install agento11y-llamaindex
pip install agento11y-google-adk
pip install agento11y-strands
pip install agento11y-claude-agent-sdk
pip install agento11y-litellm
pip install agento11y-pydantic-ai

Framework integrations inject callbacks that capture generations automatically. Refer to Instrument agents with frameworks for setup details.

Capture a generation manually

To instrument calls without a framework, use the context manager:

Python 
from agento11y import Client, ClientConfig, GenerationStart, ModelRef, assistant_text_message

client = Client(
    ClientConfig(
        generation_export_endpoint="<AGENTO11Y_ENDPOINT>",
    )
)

with client.start_generation(
    GenerationStart(
        conversation_id="conv-1",
        model=ModelRef(provider="openai", name="gpt-4o"),
    )
) as rec:
    rec.set_result(output=[assistant_text_message("Hello")])

client.shutdown()

Replace AGENTO11Y_ENDPOINT with your Agent Observability API address.

Use environment variables instead

If you set AGENTO11Y_ENDPOINT, AGENTO11Y_PROTOCOL, AGENTO11Y_AUTH_MODE, AGENTO11Y_AUTH_TENANT_ID, and AGENTO11Y_AUTH_TOKEN, the SDK reads them at client construction. Refer to Configure your SDK.

Python 
client = Client()

Use a provider helper

Provider helpers capture generations automatically from your LLM client calls. For example, with OpenAI:

Python 
import openai
from agento11y import Client, ClientConfig
from agento11y_openai import chat

client = Client(
    ClientConfig(
        generation_export_endpoint="<AGENTO11Y_ENDPOINT>",
    )
)
openai_client = openai.OpenAI()

response = chat.completions.create(
    client,
    {"model": "gpt-4o", "messages": [{"role": "user", "content": "What is observability?"}]},
    lambda request: openai_client.chat.completions.create(**request),
)

client.shutdown()

Configure authentication in code

For Grafana Cloud, use basic auth with your Cloud Access Policy Token:

Python 
from agento11y import Client, ClientConfig
from agento11y.config import GenerationExportConfig, AuthConfig

client = Client(
    ClientConfig(
        generation_export=GenerationExportConfig(
            protocol="http",
            endpoint="<AGENTO11Y_ENDPOINT>",
            auth=AuthConfig(
                mode="basic",
                tenant_id="<INSTANCE_ID>",
                basic_password="<API_KEY>",
            ),
        ),
    )
)

Set up traces and metrics

The SDK emits OpenTelemetry spans and metrics alongside generation data. To export them, configure a TracerProvider and MeterProvider in your application before creating the client. Without this, traces and metrics are silently lost.

Refer to Set up traces and metrics for Grafana Cloud OTLP options and SDK configuration for setup snippets.

Verify data

Open Agent Observability in Grafana Cloud and navigate to Conversations. Your generation should appear within a few seconds. Check your Traces and Metrics data sources for SDK-emitted spans and metrics.

Next steps