---
title: "Instrument Go agents | Grafana Cloud documentation"
description: "Install the AI Observability Go SDK and capture your first generation from a Go agent."
---

# Instrument Go agents

This guide shows you how to install the AI Observability Go 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 Go module is `github.com/grafana/sigil-sdk/go`.

## Before you begin

- A running AI Observability instance or Grafana Cloud stack with AI Observability enabled.
- Go 1.23 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](/docs/grafana-cloud/machine-learning/ai-observability/get-started/grafana-cloud/#create-an-api-key) for step-by-step instructions.

## Install the SDK

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
go get github.com/grafana/sigil-sdk/go
```

## Capture a generation

Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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>/api/v1/generations:export"
	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 a provider helper

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

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

## Configure authentication

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

Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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](/docs/grafana-cloud/machine-learning/ai-observability/get-started/grafana-cloud/#set-up-traces-and-metrics) for Grafana Cloud OTLP options and [SDK configuration](/docs/grafana-cloud/machine-learning/ai-observability/configure/sdk/#opentelemetry-setup) 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

- [Configure SDK options](/docs/grafana-cloud/machine-learning/ai-observability/configure/sdk)
- [Instrument with framework integrations](/docs/grafana-cloud/machine-learning/ai-observability/guides/instrument-agents)