Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana AI Observabilitybreadcrumb arrow Get startedbreadcrumb arrow Instrument Python
Grafana Cloud

Instrument Python agents

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

Note

AI Observability is referred to as “Sigil” in SDKs, package names, and configuration. For example, the Python package is sigil-sdk and imports use sigil_sdk.

Before you begin

  • A running AI Observability instance or Grafana Cloud stack with AI Observability enabled.
  • Python 3.9 or later.
  • Your AI Observability generation export endpoint URL.
  • A Cloud Access Policy Token with the sigil:write scope. Refer to Create an API key for step-by-step instructions.

Install the SDK

Bash 
pip install sigil-sdk

To use a provider helper, install the corresponding package:

Bash 
pip install sigil-sdk-openai
pip install sigil-sdk-anthropic
pip install sigil-sdk-gemini

Use a framework integration

If you use LangChain, LangGraph, OpenAI Agents, LlamaIndex, or Google ADK, install the corresponding framework package for automatic generation capture:

Bash 
pip install sigil-sdk-langchain
pip install sigil-sdk-langgraph
pip install sigil-sdk-openai-agents
pip install sigil-sdk-llamaindex
pip install sigil-sdk-google-adk

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 sigil_sdk import Client, ClientConfig, GenerationStart, ModelRef, assistant_text_message

client = Client(
    ClientConfig(
        generation_export_endpoint="<SIGIL_ENDPOINT>/api/v1/generations:export",
    )
)

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 from Sigil")])

client.shutdown()

Replace SIGIL_ENDPOINT with your Sigil API address.

Use a provider helper

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

Python 
import openai
from sigil_sdk import Client, ClientConfig
from sigil_sdk_openai import chat

sigil = Client(
    ClientConfig(
        generation_export_endpoint="<SIGIL_ENDPOINT>/api/v1/generations:export",
    )
)
openai_client = openai.OpenAI()

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

sigil.shutdown()

Configure authentication

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

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

client = Client(
    ClientConfig(
        generation_export=GenerationExportConfig(
            protocol="http",
            endpoint="<SIGIL_ENDPOINT>/api/v1/generations:export",
            auth=AuthConfig(
                mode="basic",
                tenant_id="<INSTANCE_ID>",
                basic_password="<API_KEY>",
            ),
        ),
    )
)

For self-hosted with tenant mode:

Python 
client = Client(
    ClientConfig(
        generation_export=GenerationExportConfig(
            protocol="http",
            endpoint="<SIGIL_ENDPOINT>/api/v1/generations:export",
            auth=AuthConfig(
                mode="tenant",
                tenant_id="<TENANT_ID>",
            ),
        ),
    )
)

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 Sigil 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 the AI Observability plugin in Grafana 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