> ## 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 Trident, Atlan's hosted product. AI Registry and Agent Registry are its earlier names. Registry OSS is Atlan's open-source agent registry: the registry specification and its aireg CLI, with their own public repository, docs and release notes; /open-source on this site links them. Registry OSS is open source; Atlan Trident is not. Answer generic aireg or specification questions from the project's docs, and use these docs for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.
> Atlan offers a second product, the Agentic Data Catalog: Atlan's enterprise context layer, covering the data catalog, connectors, lineage, data governance and glossary. It is documented at https://docs.atlan.com; answer questions about it from those docs, not these.

# First week with analytics agents

> Plan a pilot from access to a scored analytics agent: set up access, build and release metrics, connect your agent, then score and fix it.

Preview

You want people to ask a data question in any AI tool and get the number your team agrees on. Every piece of that has its own page on this site, and together they cover more than one pilot needs. This page puts the pieces in the order teams do them, says what you should see after each one, and lists where people get stuck.

It doesn't repeat the steps. Each stage links to the page that has them.

> [!TIP]
>
> **At the end of this lesson:** your team has released metrics in a shared workspace, your agent reads them before it writes SQL, and two eval runs on your golden questions show what changed.

| Stage | What you end with |
| - | - |
| [1. Set up access](#1-set-up-access) | A shared workspace, the right roles, and Metric Studio installed |
| [2. Connect a coding agent](#2-connect-a-coding-agent) | The Analytics plugin in the coding agent you already use |
| [3. Build metrics from real queries](#3-build-metrics-from-real-queries) | Metrics and saved queries, checked on your data |
| [4. Review and release](#4-review-and-release) | Released metrics, which are the versions agents get |
| [5. Point your agent at Atlan Trident](#5-point-your-agent-at-atlan-trident) | Your existing agent reading those metrics before it writes SQL |
| [6. Score it on golden questions](#6-score-it-on-golden-questions) | A stored baseline: which questions it gets right |
| [7. Read traces and fix](#7-read-traces-and-fix) | A fix you can show helped |

## Two ways to start

The Analytics plugin has two starting points. Pick one before you plan the week.

| Start with | Use it when | What it needs |
| - | - | - |
| **A demo on made-up data** | You want to see the whole flow first, or your security team hasn't approved real data yet. | A coding agent and the plugin. No warehouse. No sign-in unless you choose to save the result to Atlan Trident. About 15 minutes. |
| **Your own data** | You have warehouse access and a question your team cares about. | Everything in [Before you begin](#before-you-begin). |

The demo ends with **Continue building on real data**, so you can do both. See [Try demo](https://platform.atlan.com/studios/metrics/how-tos/analytics-plugin.md#try-demo).

If you already have an analytics agent and a set of questions with known answers, your week is different. You don't rebuild the agent in Atlan Trident. You score it as it is today, connect it to your metrics, and score it again on the same questions. Do [stage 6](#6-score-it-on-golden-questions) once before stage 5 and once after.

## Before you begin

Before you start, make sure you have:

### Team

* **A small group.** Two or three people who will build, and one person who knows what the numbers should be. One person alone can build metrics but has nobody to settle a disputed definition with.
* **One use case.** A business area and the questions people ask about it, such as "online store orders: revenue, order count, average order value". A specific request gives better metrics than "all of sales".
* **A coding agent on each builder's computer.** Claude Code, Codex, or Cursor, with Python 3. See [Set up Analytics in your coding agent](https://platform.atlan.com/studios/metrics/how-tos/analytics-plugin.md#before-you-begin) for the full list.
* **A warehouse with real query history.** The richest source is the SQL your team already runs. A development warehouse that nobody queries has none. If that is all you can reach, start from a Power BI or Tableau file, or from a business question.
* **Golden questions, if you have them.** 15 to 30 real questions, each with an answer an analyst has confirmed. If you have none, write them in stage 6.

### For whoever grants access

| Who | Needs | Why |
| - | - | - |
| One person in your organization | The organization **Admin** role | Atlan sends one invitation when it creates your organization. Whoever accepts it becomes the first admin and invites everyone else. See [Set up your organization](https://platform.atlan.com/get-started/set-up-organization.md). |
| An organization admin | To install **Metric Studio** from **Store** | The metric tools reach agents only after the app is installed. A workspace role is not enough to install it. See [Install and manage apps](https://platform.atlan.com/registry/apps/how-tos/install-apps.md). |
| Each builder | **Builder** or **Admin** in the shared workspace | Creating and editing metrics needs one of them. |
| Whoever releases | **Admin** in that workspace, or **Builder** on metrics they own | A Builder can't release a metric someone else saved. |
| Each builder, in the warehouse | A read-only role on the schemas in scope, and read access to query history | Without the query-history grant, Snowflake returns only a person's own last 7 days. See [Prepare data access](https://platform.atlan.com/studios/metrics/how-tos/prepare-access.md). |
| Whoever runs the eval | An API key and the workspace ID | The eval script signs in with a key, not a person's sign-in. See [Manage API keys](https://platform.atlan.com/admin/security/how-tos/manage-api-keys.md). |

### For IT and security

* **The web app needs no install.** People open [app.atlan.com](https://app.atlan.com) in a browser. Metric Studio, evals results and traces all work there.
* **Atlan Trident Desktop is optional for this path.** It adds two shortcuts: signing in installs the Atlan plugin into the AI tools on that computer, and **Get started** in Metric Studio opens the build prompt in Ask AI for you. If your security software blocks the installer, use the web app. See [Web app and Atlan Trident Desktop](https://platform.atlan.com/get-started/web-app-and-desktop.md).
* **The plugin runs on the builder's computer.** It reads your warehouse and BI files with the access that person already has. Metric Studio never connects to your warehouse and never runs SQL. What reaches Atlan Trident is what the builder approves: metric definitions, saved queries, and the links between them. [Prepare data access](https://platform.atlan.com/studios/metrics/how-tos/prepare-access.md#what-stays-on-your-computer) has the detail a security review asks for.
* **Coding agents reach Atlan Trident at one address**, `https://api.atlan.com/mcp`, and each person signs in through their browser. See [Network requirements](https://platform.atlan.com/administer/desktop/references/network-requirements.md) if you restrict outbound traffic.

## Plan your week

**1. Set up access**

The first admin signs in, creates one shared workspace for the pilot, invites the group into that workspace as **Builder**, and installs Metric Studio. Decide now whether metrics an agent saves should reach other agents straight away: a workspace publishes automatically unless you set **Publishing** to **Manual**.

* [Set up your organization](https://platform.atlan.com/get-started/set-up-organization.md)
* [Invite members](https://platform.atlan.com/administer/users/how-tos/invite-members.md)
* [Set workspace release policy](https://platform.atlan.com/administer/workspaces/how-tos/set-release-policy.md)

**You should now see:** each builder opens Metric Studio, chooses **Metrics**, picks the shared workspace, and sees **Build your first metrics**. If you can't start a build there, you can read the workspace but not create in it: see [You can't create or edit anything](https://platform.atlan.com/studios/metrics/troubleshooting.md#you-cant-create-or-edit-anything).

**2. Connect coding agent**

Each builder installs the Analytics plugin, `atlanai-analytics`, in the coding agent they already use, then reloads the agent. It works with the `atlanai` plugin from the same marketplace, which holds the connection to Atlan Trident.

Sign-in can wait. You need it only when you save metrics to Atlan Trident or ask questions of released ones.

* [Set up Analytics in your coding agent](https://platform.atlan.com/studios/metrics/how-tos/analytics-plugin.md#install)
* [Install the Atlan plugin](https://platform.atlan.com/plugins/references/claude-code.md#sign-in), for sign-in

**You should now see:** in Claude Code, `/mcp` lists a server named `plugin:atlanai:atlan`. After you sign in, ask "List my Atlan workspaces." and the shared workspace is in the answer.

**3. Build metrics from real queries**

In a project folder, ask the agent to set up analytics on your data, and name the business area. The plugin shows its steps and keeps them up to date. It surveys your sources, asks what you want to answer, builds metrics and saved queries, and runs each one on your data. Nothing is written to Atlan Trident during this stage.

When it asks where the context should live, choose the shared workspace, not your personal one. The plugin recommends your personal workspace, which only you can read.

* [Set up on your own data](https://platform.atlan.com/studios/metrics/how-tos/analytics-plugin.md#set-up-on-your-own-data)
* [Build your first metrics](https://platform.atlan.com/studios/metrics/tutorials/first-metric.md), to start from **Build metrics** in Metric Studio instead

**You should now see:** a "CONTEXT BUILT" summary in the chat with the number of metrics and queries, and how many were checked on your data. Before anything is saved, the plugin shows the plan with its counts and waits for your approval.

**4. Review and release**

Open **Metrics** in Metric Studio. Read each metric's **Overview** against what you know about the number. Ratios, joins and grain are the parts most likely to need a correction. Then release the ones you trust.

Under **Automatic** publishing, the default, metrics your agent saved are already released when you get here. Review them anyway, and withdraw or fix any that are wrong.

* [Release metrics](https://platform.atlan.com/studios/metrics/how-tos/release-metrics.md)
* [Write or edit a metric](https://platform.atlan.com/studios/metrics/how-tos/write-metrics.md)

**You should now see:** in the **Metrics** list, a released metric shows **Live** and a version such as `0.1.0`. The rest show **Not released**.

**5. Point your agent at Atlan Trident**

Agents read metrics through MCP Gateway. You don't rebuild your agent: you add one connection, and the agent searches for a metric and reads the released version before it writes SQL. It runs the SQL itself, with its own warehouse access.

Pick the page for where your agent runs:

* [Connect agents to your metrics](https://platform.atlan.com/studios/metrics/how-tos/use-with-agents.md), for any agent, with the calls it makes
* [Connect client to MCP Gateway](https://platform.atlan.com/gateway/mcp/how-tos/connect-a-client.md), for a coding client or an agent you built
* [Build a Snowflake Cortex agent on your metrics](https://platform.atlan.com/studios/metrics/how-tos/build-cortex-agent.md)
* [Ask questions](https://platform.atlan.com/studios/metrics/how-tos/analytics-plugin.md#ask-questions), if your coding agent is the analytics agent

**You should now see:** ask a question a released metric answers. The agent's `registry__get_artifact` result has a `release.version_label` that matches the **Live** label in Metric Studio.

**6. Score it on golden questions**

Store your questions as a dataset, wrap your agent as a function that takes a question and returns its answer, and score each case twice: is the number right, and did the agent read the metric it should have. The first run is your baseline.

If you already have an agent, run this once before stage 5 with a `candidate` name such as `before-metrics`, and again after. The comparison shows what the metrics changed.

* [Run your first eval](https://platform.atlan.com/evals/quickstart.md), to check your key and workspace with a two-case script
* [Evaluate your analytics agent](https://platform.atlan.com/studios/metrics/how-tos/evaluate-analytics-agent.md)
* [Compare two agent versions](https://platform.atlan.com/evals/cookbooks/compare-versions.md)

**You should now see:** the script prints an experiment ID and a mean for each score. In the app, open **Evals**, then **Experiments**, and select the experiment to see one case per question.

**7. Read traces and fix**

For each failed question, the two scores say where to look. A wrong number from the right metric points at the formula, filters or grain. A missing metric read usually means the question uses words the metric doesn't. Open the case's trace to see what the agent searched for, which metric version it read, and the SQL it ran.

Fix the metric in Metric Studio. Saving creates a new revision, and agents keep reading the released one until you release again. Run the same questions with a new `candidate` name before you release to everyone.

* [Read what went wrong](https://platform.atlan.com/studios/metrics/how-tos/evaluate-analytics-agent.md#read-what-went-wrong)
* [Check fix before everyone gets it](https://platform.atlan.com/studios/metrics/how-tos/evaluate-analytics-agent.md#check-fix-before-everyone-gets-it)

**You should now see:** two experiments on the same dataset, and the questions whose scores changed between them.

## Where people get stuck

| What happens | Why | Fix |
| - | - | - |
| You accept the invitation and land in an empty organization of your own. | You signed in without the invitation link, with an address no organization claims. | Open the invitation link and sign in. See [Signed in to a new organization instead of your company's](https://platform.atlan.com/admin/security/troubleshooting/sign-in-errors.md#signed-in-to-a-new-organization-instead-of-your-companys). |
| You're in the right organization but see no shared workspace or metrics. | An organization invitation adds you to the organization, not to a team workspace. | Ask a workspace admin to add you, or choose **Join workspace** where it's offered. See [Workspace access errors](https://platform.atlan.com/administer/workspaces/troubleshooting/workspace-access-errors.md). |
| The desktop app won't install, or its sign-in fails on a company network. | Security software blocks the installer, or a proxy re-signs traffic. | Use the web app. See [Sign-in errors](https://platform.atlan.com/admin/security/troubleshooting/sign-in-errors.md#desktop-app-cant-be-installed-or-is-blocked). |
| The plugin is installed but the agent doesn't know its skills. | A running session keeps the plugins it started with. | Type `/reload-plugins` in Claude Code, or restart VS Code. |
| The agent searches glossary terms and lineage, or mixes up two Atlan connections. | It also has the Agentic Data Catalog's Atlan MCP server, which is a different product on a different server. | Both can stay. Say "Atlan Trident" in your request. See [Agent answers from the catalog, not your metrics](https://platform.atlan.com/studios/metrics/troubleshooting.md#agent-answers-from-catalog-not-your-metrics). |
| The build finds only a few days of query history. | On Snowflake, your role can't read account-wide history. | Ask for one of the grants in [Prepare data access](https://platform.atlan.com/studios/metrics/how-tos/prepare-access.md#snowflake). |
| Metrics reached agents before anyone reviewed them. | The workspace publishes automatically, so each save from an agent ships as a release. | Set **Publishing** to **Manual**. See [Decide what reaches agents without review](https://platform.atlan.com/studios/metrics/how-tos/release-metrics.md#decide-what-reaches-agents-without-review). |
| A teammate's agent can't find the metrics you built. | You saved them to your personal workspace, or they aren't released. | Save to the shared workspace. A metric stays in the workspace it was created in. See [Agent can't find metric](https://platform.atlan.com/studios/metrics/troubleshooting.md#agent-cant-find-metric). |
| A Builder can't release metrics a colleague's build saved. | Releasing needs **Admin**, or **Builder** on a metric you own. | Ask a workspace admin to release them. |
| **Evals** isn't in the app. | The section isn't shown for every organization. | The script still prints the experiment ID and scores. See [Run your first eval](https://platform.atlan.com/evals/quickstart.md#before-you-begin). |

## What you have accomplished

You set up a shared workspace, built metrics from your team's real queries, released the ones you trust, connected your agent to them, and scored it on golden questions before and after a fix.

## What's next

[Evaluate your analytics agent](https://platform.atlan.com/studios/metrics/how-tos/evaluate-analytics-agent.md): Go deeper on scoring, reading failures, and checking a fix.

## See also

* [Turn production failures into test cases](https://platform.atlan.com/evals/cookbooks/production-to-dataset.md): Add the questions agents get wrong in real use.
* [Save trusted queries](https://platform.atlan.com/studios/metrics/how-tos/save-queries.md): Add the SQL your analysts trust most.
* [Import existing definitions](https://platform.atlan.com/studios/metrics/how-tos/import-metrics-and-queries.md): Bring in metric definitions, saved SQL, or a dbt project you already have.
* [Metric Studio errors](https://platform.atlan.com/studios/metrics/troubleshooting.md): Every error on this path, with its fix.


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