Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana Agent Observabilitybreadcrumb arrow Guidesbreadcrumb arrow Coding agents
Grafana Cloud

Instrument coding agents

Coding-agent plugins forward sessions from the coding agent you already use into Agent Observability. Each session shows up there as generations, tool calls, and metrics.

Supported coding agents

For the full list of supported coding agents and per-plugin install instructions, refer to grafana/agento11y/plugins.

Before you begin

  • AI Observability is enabled on a Grafana Cloud stack. Refer to Use AI Observability on Grafana Cloud to enable the plugin and collect credentials.

  • The agento11y CLI is installed and on your PATH:

    • On Linux and macOS, use the install script:

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

      The script downloads the latest release for your OS and architecture, verifies its SHA-256 checksum, and installs the binary to ~/.local/bin. Make sure that directory is on your PATH.

    • On macOS, you can also use Homebrew:

      Bash 
      brew install grafana/grafana/agento11y

    • On Windows, download the windows_amd64 or windows_arm64 zip from the releases page, extract agento11y.exe, and put it on your PATH.

    • On any platform with Go 1.25 or later, you can use go install:

      Bash 
      go install github.com/grafana/agento11y/plugins/agento11y/cmd/agento11y@latest

      go install puts the binary in go env GOPATH/bin (or GOBIN). Make sure that directory is on your PATH.

Configure credentials

Run agento11y login, or run the launcher for your coding agent (such as agento11y pi, agento11y claude, or agento11y codex). On the first launch, the launcher runs the same login flow automatically. Both write to ~/.config/agento11y/config.env, the shared configuration file that every coding-agent plugin reads. Later launches reuse it, and you can re-run agento11y login any time to change a value.

The interactive prompt has two steps:

  1. Connection details: your Grafana Cloud endpoint (the plugin’s API URL), tenant ID (the Instance ID), token, and OTLP endpoint. Find these in Grafana Cloud at https://<your-stack>.grafana.net/plugins/grafana-agento11y-app.
  2. Preferences: content capture mode, session tags, and guards. Every field defaults to the plugin’s current behavior, so press Enter through this step to keep the defaults.

If you can’t run an interactive prompt (for example, in CI, a container, or a scripted setup), write the configuration file directly instead. Refer to Configure without the prompt.

Content capture

By default, plugins send only metadata: model, token usage, tool names, and timing. Prompts, responses, and tool I/O stay on your machine. To also send prompts and responses, with automatic secret redaction, set the Content capture field to Full when you run agento11y login.

The modes are metadata_only (default) and full. You can also set AGENTO11Y_CONTENT_CAPTURE_MODE directly. Refer to Configure without the prompt.

Enable guards

Guards run synchronous checks on tool calls before they execute. When guards are enabled, tool calls that fail evaluation are blocked. Refer to Set up guards for guard rule configuration.

Guards are off by default. To turn them on, set the Guards field in agento11y login:

  • Enabled, fail-open: transport errors and timeouts let the tool call through. This is the safer choice when you first turn guards on.
  • Enabled, fail-closed: a guard error or timeout blocks the tool call.

The Guard timeout field sets how long to wait for a guard before applying the fail mode (default 1500 ms). Raise it to tolerate slow evaluators, or lower it to cap per-call latency. The timeout applies only when guards are enabled.

Configure without the prompt

agento11y login is interactive and needs a terminal. For non-interactive setups, such as CI, containers, or dotfiles, write ~/.config/agento11y/config.env directly. Each prompt maps to an environment variable:

dotenv 
# Connection (required)
AGENTO11Y_ENDPOINT=https://agento11y-prod-<region>.grafana.net
AGENTO11Y_AUTH_TENANT_ID=<instance-id>
AGENTO11Y_AUTH_TOKEN=glc_<token>
# OTLP endpoint for SDK traces and metrics (optional)
AGENTO11Y_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-<region>.grafana.net/otlp

# Preferences (optional; defaults shown)
# Modes: metadata_only | full
AGENTO11Y_CONTENT_CAPTURE_MODE=metadata_only
AGENTO11Y_TAGS=team=ai,project=demo            # applied to every generation
AGENTO11Y_GUARDS_ENABLED=false
AGENTO11Y_GUARDS_FAIL_OPEN=true                # only used when guards are enabled
AGENTO11Y_GUARDS_TIMEOUT_MS=1500               # only used when guards are enabled

Find the connection values in Grafana Cloud at https://<your-stack>.grafana.net/plugins/grafana-agento11y-app.

Verify

Run a turn in your coding agent, then open Conversations in the Agent Observability plugin. The generation appears within a few seconds.

If nothing appears, enable debug logging and tail the log. For example, for Pi:

Bash 
AGENTO11Y_DEBUG=true agento11y pi
tail -f ~/.local/state/agento11y/logs/agento11y.log

Check the following:

  • agento11y --version resolves on your PATH.
  • The endpoint, tenant ID, and token are set in ~/.config/agento11y/config.env.
  • The access policy token has the sigil:write scope.

Next steps