> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Use metrics with agents

> Let agents search your metrics and saved queries through MCP Gateway, read the released version or pin one, and build analytics agents with /atlan-analytics.

<Badge color="orange">Preview</Badge>

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](/registry/apps/how-tos/install-apps).
* **MCP client**: Your agent's client is connected to MCP Gateway. See [Connect client to MCP Gateway](/gateway/mcp/how-tos/connect-a-client).
* **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](/studios/metrics/how-tos/release-metrics).

## How an agent reads a metric

```mermaid theme={null}
sequenceDiagram
  participant A as Agent
  participant G as MCP Gateway
  A->>G: mcp__initialise
  G-->>A: session_id
  A->>G: registry__list_workspaces
  G-->>A: workspace_id
  A->>G: extension__metric__search_metrics (query)
  G-->>A: matching metrics (newest revision)
  A->>G: registry__get_artifact (channel: latest)
  G-->>A: released definition + release record
  Note over A: Agent writes and runs SQL with its own warehouse access
```

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Search for a metric">
    The agent calls `extension__metric__search_metrics` with a `workspace_id` and either `query` (ranked search) or `name` (exact identifier):

    ```json Request theme={null}
    {
      "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:

    ```json Response (one item) theme={null}
    {
      "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.
  </Step>

  <Step title="Read the released version">
    The agent calls `registry__get_artifact` with the metric's `id` and `channel` set to `latest`:

    ```json Request theme={null}
    {
      "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.
  </Step>

  <Step title="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`:

    ```json theme={null}
    {
      "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 {label}** 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.
  </Step>

  <Step title="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](/tools/mcp/metric/references/metric-search-queries).

    Saved queries aren't released, so the agent always gets the newest revision.
  </Step>
</Steps>

## 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](/studios/metrics/troubleshooting#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.

## Related

* [Create and release your first metric](/studios/metrics/tutorials/first-metric): Release a metric and watch an agent read it.
* [Search metrics](/tools/mcp/metric/references/metric-search-metrics): Every input and output field of the search tool.
* [Get artifact](/tools/mcp/registry/references/registry-get-artifact): The read tool.
* [Connect client to MCP Gateway](/gateway/mcp/how-tos/connect-a-client): Add MCP Gateway to your client.
* [Troubleshoot Metrics Studio](/studios/metrics/troubleshooting): When an agent can't find a metric or reads the wrong version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.