Use the agent catalog

The agent catalog automatically discovers and tracks your agents. It groups generations by agent name and effective version, then shows usage patterns over time.

Before you begin

Instrument your agent and send generations to Grafana Cloud. For instructions, refer to Get started with Grafana Cloud.
Set an agent name in your instrumentation and export OpenTelemetry metrics to compare activity and performance.
Ensure your role has permission to view Agent Observability data.

Browse agents

Navigate to Agents in Agent Observability to view discovered agents. The agent list shows:

Agent name and risk signals.
Last seen timestamp.
Generation count and activity trend.
Error rate, P95 latency, tokens, and estimated cost.

Generation counts on Agents and the agent detail activity chart count LLM calls, not tool executions. A generation that calls several tools still counts as one generation; subsequent LLM calls count separately.

Demo agents seeded through the onboarding wizard display a Demo badge. Recognized coding-agent launchers and subagents display a code icon ({}) with a Coding agent tooltip.

Search and filter agents

To filter the catalog:

In Filter agent by name…, enter an agent name or substring, for example, chunnel. Search matches agent names without regard to case or accents, for example, jose matches josé-agent.
Matching loaded rows remain visible while the search runs. If no loaded rows match yet, the table displays Searching agents… until the catalog request completes. When the request finishes, the returned catalog results update the table, or the table displays No data found if there aren’t any matches.
To clear the filter, click the clear icon (×) in the search box or delete the text. The table displays Loading agents… while the full catalog reloads.

If a catalog search fails, the table clears the retained results and displays an error. Metric queries load independently and don’t extend the catalog search message.

Toolbar provider, model, and agent filters continue to apply during a name search, including while metrics are loading or unavailable. You can also select risk signal filters to identify anonymous, stale, or high-churn agents.

Focus the catalog on a time range

Use the time range picker to inspect agents and activity from a specific period. Changing the time range resets the agent list while new data loads. Generation, token, cost, and error metrics update for that range.

When you select a time range, the catalog displays agents whose observed lifetime overlaps that window:

An agent appears if it was first seen at or before the end of the range and last seen at or after the start of the range.
Newer activity after the end of the selected window doesn’t hide an agent that was present in the range. In a 10:00 to 11:00 window, for example, an agent observed at 10:30 stays visible even after another generation at 11:05.
Agents first seen after the window ends or last seen before the window starts remain excluded.

Lifetime overlap includes the following limits:

Inactive gaps: Range eligibility checks whether the agent’s overall lifetime overlaps the window rather than proving activity within that period. An agent observed only at 09:00 and 12:00, for example, also qualifies for a 10:00 to 11:00 window.
Global catalog values: Metadata, sorting, and pagination cursors remain global. The Last seen column, for example, displays the agent’s latest overall activity across all time, not its latest activity within the selected time range.

High churn flags agents with many versions first seen in the selected range. The threshold scales from five versions over seven days, with a minimum of two. Open the agent to compare its versions and investigate unexpected prompt or release changes. Stale flags agents last active more than seven days before the end of the selected range.

Understand agent versions

By default, Agent Observability uses the SDK-declared agent_version as the user-facing catalog version. If your instrumentation sends agent_version=v1 and later agent_version=v2, the agent catalog shows those as separate versions even when the prompt text is the same.

If no agent_version is set, Agent Observability computes a fallback version as a SHA-256 hash of the system prompt. Adding, removing, or modifying a tool doesn’t create a new fallback version, so a changing tool surface, for example, from MCP tools, doesn’t proliferate versions. Tool changes are still recorded in the version’s tool snapshot.

Advanced producers can also send an effective_version override to control catalog identity separately from the visible agent_version label.

Set a stable agent_version in your SDK instrumentation when you want catalog, Quality, and Performance views to compare declared releases. Without agent_version, the agent can still appear in the catalog, but per-version Performance charts may not have a matching Prometheus metric label.

The version history for each agent shows:

When each version was first and last seen.
Which models each version used.
The tool and prompt footprint for each version.

Numbered releases, for example, 1.0.0, 2.0.0, and 3.0.0, stay in version order. Named versions, for example, input-safety-v1, appear before, between, or after those releases based on when they’re first seen. The timeline, quality and performance charts, and previous-version comparisons use the same order.

Compare versions

Use the agent catalog to compare metrics across versions:

Token usage and estimated cost trends.
Error rates and latency distributions.
Evaluation score changes.

This helps you determine whether a prompt change improved or degraded quality.

Analyze prompts

Use the agent detail page to review prompt and tool changes for each version. Prompt insights summarize the active system prompt and highlight patterns that may affect quality, latency, or cost.

When agent rating is configured, run an agent score analysis to get a judge-model assessment of the selected version. The result appears on the agent overview and prompts views so you can compare the rating with quality and performance trends.

Model cards

Agent Observability maintains model cards with metadata about each LLM model your agents use. Model cards show pricing tiers, context windows, and capabilities. The catalog syncs model card data periodically to keep information current. Model card prices are public list prices. To use the prices you pay, refer to Configure your model prices.