Use metrics with agents

Preview Agents use your metrics through MCP Gateway: they search a workspace for a metric, then read the version you released. This guide shows the calls an agent makes, how to pin an agent to one release, and how the /atlan-analytics skills build an analytics agent on top of your metrics.

Before you begin

Metrics app: An administrator has installed the Metrics app. The metric tools appear in MCP Gateway only after that. See Install and manage apps.
MCP client: Your agent’s client is connected to MCP Gateway. See Connect client to MCP Gateway.
Access: The identity the agent signs in with can read the workspace. Every call runs with that identity’s permissions.
A released metric: At least one metric shows Live in Studio. See Release metrics.

How an agent reads a metric

Every call after mcp__initialise also takes session_id and a short rationale, which MCP Gateway records for audit.

Check the metric tools are available

Ask your client for its tool list (tools/list). It should include:

Tool	What it does
`extension__metric__search_metrics`	Finds metrics in one workspace
`extension__metric__search_queries`	Finds saved queries in one workspace
`registry__get_artifact`	Reads one metric or saved query in full
`registry__get_related_artifacts`	Reads a metric’s links, such as `depends_on`

If the two extension__metric__ tools are missing, the Metrics app isn’t installed for your organization.

Search for a metric

The agent calls extension__metric__search_metrics with a workspace_id and either query (ranked search) or name (exact identifier):

Request

{
  "workspace_id": "workspace_…",
  "query": "average order value",
  "limit": 5,
  "rationale": "Find the agreed definition of average order value before writing SQL.",
  "session_id": "…"
}

Each result carries what an agent needs to choose a metric, without the SQL:

Response (one item)

{
  "id": "metric_…",
  "name": "average_order_value",
  "display_name": "Average order value",
  "description": "Average amount a customer pays per completed order.",
  "workspace_id": "workspace_…",
  "version_ordinal": 2,
  "is_released": true,
  "owner_id": "…",
  "version": 2,
  "population": "Completed orders from the online store",
  "grain": "order_id",
  "output": { "alias": "average_order_value", "datatype": "decimal", "unit": "USD" },
  "dimensions": ["order_month", "customer_region"],
  "parameters": ["start_date"],
  "depends_on": ["revenue"],
  "replaced_by": null
}

Search returns the newest revision of each metric, which may not be the released one. Use it to choose a metric, then read the release.

Read the released version

The agent calls registry__get_artifact with the metric’s id and channel set to latest:

Request

{
  "artifact_id": "metric_…",
  "channel": "latest",
  "rationale": "Read the released definition of average_order_value.",
  "session_id": "…"
}

The result is the full released definition under metadata.definition, plus a release record with its release_id, channel, version_label, and release_status. This is the same version Studio shows as Live.If nothing is released on that channel, the call is refused with “no such distributable release”. It never falls back to an unreleased revision. Without channel or release_id, the call reads the newest revision instead.

Pin an agent to one release (optional)

To keep an agent on one exact version even after you release a newer one, pass release_id instead of channel:

{
  "artifact_id": "metric_…",
  "release_id": "rel_…",
  "rationale": "Use the pinned release of average_order_value agreed for the Q3 report.",
  "session_id": "…"
}

To find a release ID, open the metric’s History in Studio and open a version. Its Version page lists the Release ID under Release and revision IDs. You can’t pass channel and release_id together.A pinned read keeps working when newer versions are released. It stops working if that release is withdrawn or the metric is archived.

Search saved queries (optional)

For a question a metric doesn’t cover, the agent can look for trusted SQL with extension__metric__search_queries. Set status to verified to keep only queries whose SQL ran when they were saved. See Search saved queries.Saved queries aren’t released, so the agent always gets the newest revision.

Verify

Compare what the agent read with Studio:

In the agent’s registry__get_artifact result, release.version_label matches the Live label in the catalog’s Release column, for example 0.2.0.
release.channel is latest, or the channel you released on.
metadata.definition.formula matches the formula on the version page in Studio.

If they differ, see An agent reads an old version.

Build an analytics agent with `/atlan-analytics`

The Metrics app adds four guided skills that build a talk-to-data agent on top of your metrics and saved queries, then measure and improve it.

Skill	What it does
`atlan-analytics`	The entry point. Checks your sign-in and warehouse connection, resumes a saved project, and routes to one of the three below.
`atlan-analytics-build`	Builds an agent in seven phases: purpose, scope (five tables or fewer), context published as metrics and saved queries, an eval set, the agent itself, a smoke test, and a baseline score.
`atlan-analytics-improve`	Improves an existing agent one change per round, usually a new metric or saved-query revision, and reports the score on held-out questions.
`atlan-analytics-eval`	Runs an eval: each question goes to a fresh agent, and results are compared with known-good answers. The run is recorded in Atlan with a trace per question.

To run them:

Claude Code with the atlanai plugin: run /atlan-analytics, optionally with build, improve, or eval and a project name, for example /atlan-analytics improve store-analytics.
Any MCP client: use the MCP prompt atlan-analytics that MCP Gateway serves.

What the skills need:

A Snowflake MCP connector signed in to your warehouse. The skills run all SQL through it. MCP Gateway runs none.
python3, for the bundled eval script.
To build the context, the skill downloads the open-source metrics-agent on first use. If it can’t, it falls back to writing the definitions by hand.

The skills keep their state in your project folder under .atlan-analytics/<project>/. That folder holds the eval answers, so the skill asks whether to add it to .gitignore. The skills ask one question at a time and stop after each phase so you can review what they made.

Create and release your first metric: Release a metric and watch an agent read it.
Search metrics: Every input and output field of the search tool.
Get artifact: The read tool.
Connect client to MCP Gateway: Add MCP Gateway to your client.
Troubleshoot Metrics Studio: When an agent can’t find a metric or reads the wrong version.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

Before you begin

How an agent reads a metric

Verify

Build an analytics agent with `/atlan-analytics`

​Before you begin

​How an agent reads a metric

​Verify

​Build an analytics agent with /atlan-analytics

​Related

Before you begin

How an agent reads a metric

Verify

Build an analytics agent with `/atlan-analytics`

Related