Grafana Agent observability is a product from Grafana for teams running agents in production. This repo holds the open-source SDKs and the coding-agent plugins that send telemetry to it.

If you want your own app or agent code instrumented, the recommended path is the agento11y-instrument agent skill. gcx is Grafana's CLI for working with Grafana Cloud resources; see the gcx installation docs if you want more detail.

Install gcx with the quick install script:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

Or with Homebrew:

brew install grafana/grafana/gcx

Then install the skill:

gcx agent skills install agento11y-instrument

If gcx is already installed but the skill is missing, update gcx first. Homebrew users can run brew update && brew upgrade gcx; script users can re-run the quick install script.

Use the `agento11y-instrument` skill to instrument this codebase with Grafana Agent observability.

The skill inspects your code, applies the SDK with small diffs after confirmation, and verifies that data lands in Grafana Cloud with gcx agento11y.

If you want to capture sessions from your coding agent instead, or if your agent does not support skills, drop llms.txt into your repo and ask your agent what you want. It handles either case, depending on what your repo is:

• Instrument this codebase with Grafana Agent observability: the agent wires the SDK into your app or agent code.
• Set up Grafana Agent observability for my coding agent: the agent installs one of the plugins/ launchers to capture sessions from popular coding agents.

Or open the Agent Observability plugin in your Grafana Cloud stack and use the onboarding wizard.

Set the AGENTO11Y_* env vars and construct the client. To configure it explicitly instead, see the per-SDK READMEs linked under SDKs.

import { Agento11yClient } from "@grafana/agento11y";

const client = new Agento11yClient(); // reads AGENTO11Y_* env vars

await client.startGeneration(
  { conversationId: "conv-1", model: { provider: "openai", name: "gpt-5" } },
  async (recorder) => {
    recorder.setResult({ output: [{ role: "assistant", content: "Hello" }] });
  },
);

await client.shutdown();

from agento11y import Client, GenerationStart, ModelRef, assistant_text_message

client = Client()  # reads AGENTO11Y_* env vars

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

client.shutdown()

client := agento11y.NewClient(agento11y.Config{}) // reads AGENTO11Y_* env vars
defer func() { _ = client.Shutdown(context.Background()) }()

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

rec.SetResult(agento11y.Generation{
    Output: []agento11y.Message{agento11y.AssistantTextMessage("Hello from Grafana Agent observability")},
}, nil)

Self-contained examples grouped into three tiers. See examples/README.md for the full map.

The getting-started quickstarts each make a real LLM call and record the generation to Grafana Agent observability.

The experiments are offline evals: run an agent over a dataset, grade it, and publish the results. See examples/experiments/README.md.

The reference app is a fuller FastAPI service with framework callbacks and manual instrumentation side by side.

Application SDK hooks evaluate Agent Observability guard rules on your request path before a provider call. A guard can allow the request, deny it, or return transformed input such as redacted messages. Go, Python, and TypeScript hook requests propagate the active conversation and OpenTelemetry trace correlation so Agent Observability can show a denied preflight attempt in conversation detail even when no generation was created. See the SDK READMEs for manual hook evaluation, and the runnable examples/getting-started/go-hooks/, examples/getting-started/python-hooks/, and examples/getting-started/typescript-hooks/ examples for preflight guard setups.

The SDKs default to no_tool_content: full generation messages ship to Agent Observability, but tool-execution arguments and results stay out of spans. The coding-agent plugins default to metadata_only. See Content Capture Modes for the mode matrix, defaults per surface, and the generation, tool-execution, and embedding resolution rules.

To attach custom key/values (team, project, env, request id, end-user id), see Tags and Metadata. It covers which of client tags, per-generation tags, metadata, and user_id reach the generation export vs OTel spans vs metrics, and the cardinality rules for metric labels.

All four connection values (API URL, Instance ID, API token, and OTLP endpoint) live on the Connection tab of the Agent Observability plugin in your stack:

https://<your-stack>.grafana.net/plugins/grafana-agento11y-app

Follow Create a token in Cloud Access Policies on the Connection page and create one token scoped with sigil:write, metrics:write, traces:write, and logs:write. The same token then covers both AGENTO11Y_AUTH_TOKEN (Agent Observability ingest) and OTEL_EXPORTER_OTLP_HEADERS (OTel traces and metrics).

See the Grafana Cloud Agent observability getting started docs for the full setup flow.

Plugins can record sessions from Claude Code, Codex, Copilot CLI, Cursor, OpenCode, and Pi without changing application code. See plugins/README.md for install and config per agent.

• The SDK emits traces and metrics as standard OTLP, so they can use existing OTel pipelines. Conversations and generations go through Agent Observability ingest so Grafana can join them with traces, costs, and scores.
• It uses OTel GenAI semantic conventions where they exist. agento11y-specific fields cover agent versions, generation IDs, and tool executions.
• Prompt and tool changes create agent versions when the producer does not send a version string.
• Evaluators can score live traffic, so teams can find regressions without reviewing every conversation manually.

Contributor notes (proto regeneration, mise tasks, conformance suites) live in docs/development.md. Agent context for working in this repo is in CLAUDE.md.

Apache License 2.0