/agento11y-instrument

name: agento11y-instrument
description: >
  Sets up and instruments a developer's own LLM app or agent to send generations and
  agentic workflow to Grafana Agent Observability (the Agent Observability SDKs) — greenfield setup,
  fixing broken instrumentation, or filling gaps in existing instrumentation. Uses gcx
  for the parts a static prompt can't do: `gcx login` / `gcx cloud stacks` to find the
  stack, and `gcx agento11y agents|conversations|generations` to VERIFY that data actually
  lands — so it iterates (instrument → run → verify → fix) until generations arrive, not
  blindly. Reads the app's code, detects language/framework, classifies instrumentation
  state (none / partial / broken), then runs a fixed gap checklist whose #1 item is the
  silent failure no other prompt catches: the SDK emits OTel spans/metrics but never
  creates a TracerProvider/MeterProvider, so without them all metrics go to a no-op and are
  lost. Also checks agent_version (required for per-version Performance charts), set_result
  completeness, SYNC vs STREAM, parent_generation_ids DAG links, and workflow-step coverage.
  Recommends changes citing file:line and, only with explicit confirmation, applies minimal
  diffs that don't change app behavior. Pulls SDK reference from agento11y's llms.txt rather
  than restating it, and hands off to `agento11y-test-starter` once data flows. It does NOT
  write test suites or set up tenant evaluations, rules, or guards — offline test suites are
  `agento11y-test-starter`, tenant eval rules + guards are `agento11y-prod-setup`;
  does NOT install coding-agent telemetry plugins (that is llms.txt "Path A"); does NOT mint
  or store credentials or invent endpoints. Trigger on phrases like "instrument my app",
  "send my agent's traces to Grafana", "set up AI observability for my app", "my generations
  aren't showing up", "why is Performance empty", "add Agent Observability to my code", "fix my instrumentation".
allowed-tools: Bash, Read, Grep, Glob, Edit, Write, WebFetch

Agent Observability — instrument an LLM app

Help a developer wire **their own** LLM app or agent to Grafana Agent Observability, from zero or from a broken/partial state, and **keep going until data actually lands in the stack**. The value this skill adds over the static instrumentation prompt is two things a prompt can't do:

1. A mechanical **gap checklist** run against the real code — headed by the one failure that is completely silent (missing OTel providers → every metric lost, no error). 2. A **verification loop** through `gcx`: after each change, run the app and check the `gcx agento11y` agents / conversations / generations commands to confirm generations arrived. Diagnose the next gap from what's missing, not from guesswork.

The SDK reference (env vars, provider snippets, field lists, framework adapters, workflow steps) lives in agento11y's `llms.txt` "Path B". Fetch it rather than restating it here; this file holds the flow and the decision logic. A minimal fallback lives in [references/instrumentation.md](references/instrumentation.md) for when the fetch is unavailable.

Rules

• **Reference, don't restate.** Fetch SDK detail from

`https://raw.githubusercontent.com/grafana/agento11y/main/llms.txt` (Path B). Only inline decision logic here. If the fetch fails, fall back to [references/instrumentation.md](references/instrumentation.md).

• **Never invent an endpoint or a token.** Read them from the environment (`AGENTO11Y_ENDPOINT`,

`AGENTO11Y_PROTOCOL`, `AGENTO11Y_AUTH_MODE`, `AGENTO11Y_AUTH_TENANT_ID`, `AGENTO11Y_AUTH_TOKEN`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`) or ask the developer. Never fabricate a URL or mint a token.

• **Target is Grafana Cloud.** The developer supplies the endpoint + token (Step 0), and the gcx

verification loop (Step 5) confirms data landing against the Cloud tenant. Never fabricate the endpoint or token — read them from the environment or ask.

• **Write `AGENTO11Y_*` env vars, never `SIGIL_*`.** `SIGIL_*` is a deprecated legacy fallback. Do

this **even if sibling apps or existing `.env` files in the repo use `SIGIL_*`** — matching a stale local convention perpetuates it. If the app already reads `SIGIL_*`, add the `AGENTO11Y_*` names (the SDK still honors both) and note the old ones are deprecated. Do not "match the siblings."

• **The gcx command group is `gcx agento11y`.** The old name `aio11y` (still the internal Go package

name) does **not** exist as a command — an invocation using aio11y instead of agento11y fails. Every verification command uses the `agento11y` group. Do not emit the old aio11y command name even if prior knowledge suggests it.

• **Gate every code WRITE on explicit confirmation.** Report first (Step 4), apply only after the

developer says yes (Step 5). Read-only gcx verification and re-running the app happen freely inside the loop; editing files does not.

• **Keep diffs small; do not change app behavior.** Instrumentation is additive. No refactors, no

prompt rewrites, no dependency upgrades beyond the SDK/adapter packages actually needed.

• **Never change the model, provider, or the app's LLM config — not even with permission, not even

"just to run the verify loop."** Instrument whatever model the app already uses. This is absolute: changing the model is out of scope for instrumentation, full stop. If a run fails because a provider API key is missing, the only allowed responses are: (a) ask the developer to provide the key for the model the app *already* uses, or (b) skip the live run and report the wiring as verified-by-construction, telling the developer to run it themselves. Do **not** offer to switch the provider, do **not** ask "which provider should I use?", and do **not** add a new provider dependency (e.g. `langchain-anthropic`) to make the run succeed. If the developer separately says they *want* a different model, that is an app change they own