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

Instrument Go agents

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

Note

Agent Observability is referred to as “Sigil” in SDKs, package names, and configuration. For example, the Go module is github.com/grafana/sigil-sdk/go.

Before you begin

  • A running Agent Observability instance or Grafana Cloud stack with Agent Observability enabled.
  • Go 1.23 or later.
  • Your Agent Observability generation export endpoint URL.
  • A Cloud Access Policy Token with the sigil:write scope. Refer to Collect credentials from Grafana Cloud for step-by-step instructions.

Install the SDK

Bash 
go get github.com/grafana/sigil-sdk/go

Capture a generation

Go 
package main

import (
	"context"

	"github.com/grafana/sigil-sdk/go/sigil"
)

func main() {
	cfg := sigil.DefaultConfig()
	cfg.GenerationExport.Protocol = sigil.GenerationExportProtocolHTTP
	cfg.GenerationExport.Endpoint = "<SIGIL_ENDPOINT>"
	cfg.GenerationExport.Auth = sigil.AuthConfig{
		Mode:     sigil.ExportAuthModeTenant,
		TenantID: "<TENANT_ID>",
	}

	client := sigil.NewClient(cfg)
	defer func() { _ = client.Shutdown(context.Background()) }()

	ctx, rec := client.StartGeneration(context.Background(), sigil.GenerationStart{
		ConversationID: "conv-1",
		Model:          sigil.ModelRef{Provider: "openai", Name: "gpt-4o"},
	})
	defer rec.End()

	_ = ctx // pass ctx to downstream calls for trace propagation

	rec.SetResult(sigil.Generation{
		Output: []sigil.Message{sigil.AssistantTextMessage("Hello from Sigil")},
	}, nil)
}

Replace SIGIL_ENDPOINT and TENANT_ID with your values.

Use environment variables instead

If you set SIGIL_ENDPOINT, SIGIL_PROTOCOL, SIGIL_AUTH_MODE, SIGIL_AUTH_TENANT_ID, and SIGIL_AUTH_TOKEN, the SDK reads them at client construction. Refer to Configure your SDK.

Go 
client := sigil.NewClient(sigil.Config{})

Use a provider helper

Provider helpers wrap LLM client calls to capture generations automatically. Helpers are available for OpenAI, Anthropic, and Gemini:

Bash 
go get github.com/grafana/sigil-sdk/go-providers/openai
go get github.com/grafana/sigil-sdk/go-providers/anthropic
go get github.com/grafana/sigil-sdk/go-providers/gemini

Use a framework integration

A Google ADK framework integration is available:

Bash 
go get github.com/grafana/sigil-sdk/go-frameworks/google-adk

Configure authentication in code

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

Go 
cfg.GenerationExport.Auth = sigil.AuthConfig{
	Mode:          sigil.ExportAuthModeBasic,
	TenantID:      "<INSTANCE_ID>",
	BasicPassword: "<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 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 Agent 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