---
title: "Instrument coding agents | Grafana Cloud documentation"
description: "Forward coding-agent sessions to AI Observability without writing SDK code."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Instrument coding agents

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

> Note
> 
> AI Observability is referred to as “Sigil” in plugin names, binaries, and configuration. For example, the shared CLI is `sigil` and the shared configuration file is `~/.config/sigil/config.env`.

## Supported coding agents

For the full list of supported coding agents and per-plugin install instructions, refer to [`grafana/sigil-sdk/plugins`](https://github.com/grafana/sigil-sdk/tree/main/plugins).

## Before you begin

- AI Observability is enabled on a Grafana Cloud stack. Refer to [Use AI Observability on Grafana Cloud](/docs/grafana-cloud/machine-learning/ai-observability/get-started/grafana-cloud) to enable the plugin and collect credentials.
- The `sigil` CLI is on your `PATH`:
  
  Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
  
  ```bash
  brew install grafana/grafana/sigil
  ```

## Configure credentials

Run the launcher for your coding agent. For example:

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

```bash
sigil pi
```

Other launchers follow the same pattern, such as `sigil claude` and `sigil codex`. On the first launch, the launcher prompts you for your Grafana Cloud endpoint, instance ID, token, and OTLP endpoint, then writes them to `~/.config/sigil/config.env`. Subsequent launches reuse them. The same configuration file applies to every coding-agent plugin.

To change credentials later, run `sigil login` again or edit `~/.config/sigil/config.env` by hand.

By default, plugins send only metadata: model, token usage, tool names, and timing. To also send prompts and responses with automatic secret redaction, add to `~/.config/sigil/config.env`:

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

```dotenv
SIGIL_CONTENT_CAPTURE_MODE=full
```

The supported modes are `metadata_only` (default), `no_tool_content`, and `full`.

## 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](/docs/grafana-cloud/machine-learning/ai-observability/guides/guards) for guard rule configuration.

Guards are off by default. To turn them on, add to `~/.config/sigil/config.env`:

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

```dotenv
SIGIL_GUARDS_ENABLED=true
```

By default, transport errors and timeouts let the tool call through (`fail-open`). Set `SIGIL_GUARDS_FAIL_OPEN=false` for strict mode, in which evaluator failures block the call. Adjust `SIGIL_GUARDS_TIMEOUT_MS` (default `1500`) to trade per-call latency for tolerance of slow evaluators.

## Verify

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

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

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

```bash
SIGIL_DEBUG=true sigil pi
tail -f ~/.local/state/sigil/logs/sigil.log
```

Check the following:

- `sigil --version` resolves on your `PATH`.
- `SIGIL_ENDPOINT`, `SIGIL_AUTH_TENANT_ID`, and `SIGIL_AUTH_TOKEN` are set in `~/.config/sigil/config.env`.
- The access policy token has the `sigil:write` scope.

## Next steps

- [Browse conversations](/docs/grafana-cloud/machine-learning/ai-observability/guides/conversations)
- [Set up guards](/docs/grafana-cloud/machine-learning/ai-observability/guides/guards)
- [Use the agent catalog](/docs/grafana-cloud/machine-learning/ai-observability/guides/agent-catalog)
- [Use built-in dashboards](/docs/grafana-cloud/machine-learning/ai-observability/guides/dashboards)