Documentation Grafana Cloud Observe and act Agent Observability Guides Coding agents

Instrument coding agents

Coding-agent integrations 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 installation instructions, refer to grafana/agento11y/plugins.

Before you begin

• Agent Observability is enabled on a Grafana Cloud stack. Refer to Set up Agent Observability to enable it.
• The agento11y CLI is installed and on your PATH:

  • On Linux and macOS, use the install script:

    Bash Copy

    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 Copy

    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 Copy

    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

Every coding-agent integration reads the same configuration file, ~/.config/agento11y/config.env, and agento11y login writes it. Re-run agento11y login any time to change settings.

To configure credentials, follow these steps:

1. 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 login flow itself.
2. In Your Grafana Cloud URL, enter the URL you open Grafana on, for example https://my.grafana.net. Login prints the address of the coding-agent setup page for that stack, https://<my>.grafana.net/a/grafana-agento11y-app/setup-coding-agent.
3. On that page, create an API token and copy the connection settings.
4. In Paste from Grafana, paste the block. Login fills the endpoint, instance ID, token, and OTLP settings from it.
5. In Preferences, press Enter to keep the current behavior. To change a preference, set Content capture, Session tags, Guards, Guard timeout (ms), or Automatic tags.

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, integrations 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.

Attribute cost to a user, repository, or branch

Automatic coding-agent tags attach session details as client tags. Client tags appear on every generation and on OpenTelemetry metrics, so dashboards can group token usage and cost by these details.

A matching key that you set in AGENTO11Y_TAGS takes precedence over the automatic value. If a value can’t be resolved, the integration omits its tag.

To enable automatic tags with the interactive prompt, run agento11y login. Answer Yes to Automatic tags, then select user, repo, branch, or any combination from the checklist.

For non-interactive setup, add the following settings to ~/.config/agento11y/config.env:

dotenv Copy

AGENTO11Y_AUTO_CODING_AGENT_TAGS=true
AGENTO11Y_AUTO_CODING_AGENT_TAGS_NAMES=user,repo

Run agento11y doctor in the repository to print the enabled names and their resolved values for the current directory. Review these values before the coding agent sends them. If the user value depends on a signed-in coding-agent account, agento11y doctor displays <depends on the agent>. Set AGENTO11Y_USER_ID to verify the exact value before you start the coding agent.

Branch values have high cardinality, and each branch adds a metric series for each user and repository combination. Start with user,repo, and add branch only when you need per-branch cost.

To compare these labels, use the Break down picker in the token usage and estimated cost charts. For more information, refer to Break a chart down by one or more dimensions.

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.

On the setup page, create a token and click Show the settings to read the connection lines. The page doesn’t cover the preference keys, so add the ones you need:

dotenv Copy

# Connection, copied from the setup page (required)
AGENTO11Y_ENDPOINT=https://agento11y-prod-<REGION>.grafana.net
AGENTO11Y_PROTOCOL=http
AGENTO11Y_AUTH_MODE=basic
AGENTO11Y_AUTH_TENANT_ID=<INSTANCE_ID>
AGENTO11Y_AUTH_TOKEN=glc_<TOKEN>
# OTLP for SDK traces and metrics; in the block only on a stack with a gateway
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-<REGION>.grafana.net/otlp
OTEL_EXPORTER_OTLP_HEADERS='Authorization=Basic <BASE64_OF_OTLP_INSTANCE_ID_AND_TOKEN>'

# Preferences (optional; defaults shown)
# Modes: metadata_only | full
AGENTO11Y_CONTENT_CAPTURE_MODE=metadata_only
AGENTO11Y_TAGS=team=ai,project=demo            # applied to every generation
# Automatic coding-agent tags: user,repo,branch | all
AGENTO11Y_AUTO_CODING_AGENT_TAGS=false
AGENTO11Y_AUTO_CODING_AGENT_TAGS_NAMES=all     # only used when automatic tags are enabled
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

Verify

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

If nothing appears, run agento11y doctor. It checks the saved credentials against the endpoint and reports what came back.

For more detail, enable debug logging and tail the log. For example, for Pi:

Bash Copy

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 token carries the sigil:write scope, which step 1 of the setup page sets.

Next steps

• Browse conversations
• Optimize cost and performance
• Set up guards
• Use the agent catalog
• Use built-in dashboards