> ## 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.

# How agent versions work

> Each change to an agent's definition saves a new version, with the exact skill versions it uses pinned, so you can see what changed and when.

An agent version is a saved copy of the agent's definition: its instructions, model, framework, tools, and the exact skill versions it uses. Every change to the definition saves a new version, so the version a trace or experiment cites still says exactly what the agent was at the time.

## What is versioned

| Part of the agent | Change saves a new version? |
| - | - |
| Instructions, model, framework, and provider | Yes |
| Tools and step limit | Yes |
| Skills manifest (the pinned skill versions) | Yes |
| Public URL and redirect URIs | Yes |
| Display name and description | No. They change in place. |
| Machine name and workspace | Can't change after registration. |

Versions are numbered from 1. Each earlier version stays readable after a newer one is saved, and a released version never changes; a change always produces a new one.

## The skills manifest

The skills manifest lists each skill the agent uses, pinned to one skill version. It works like a lockfile: when a skill releases a new version, the agent keeps the version it pinned until someone changes the manifest, which saves a new agent version.

```json theme={null}
{
  "skills": [
    { "skill_id": "skill_01example", "version_ordinal": 4 },
    { "skill_id": "skill_02example" }
  ]
}
```

Rules:

* **Leave out `version_ordinal` to pin the current release.** The skill must have a release; otherwise name a version.
* **Each skill appears once,** and a version can pin at most 64 skills.
* **Atlan records the skill's content digest** for each pin, copied from the pinned version. You don't send it.
* **An archived skill can't be added.** A pin you already have is kept.
* **`[]` pins no skills.** It also removes the agent's derived "uses skill" relationships. **`null`** stops managing skills through the manifest and leaves existing relationships alone.

The manifest drives the agent's **Relationships**: each pinned skill appears as a skill the agent uses, and the skill's profile lists the agent among what uses it.

## How a version is created

| You use | What it does | When to use it |
| - | - | - |
| **Edit agent** in the app | Saves a new version when you change the framework, model, or instructions. | Day-to-day changes. See [Edit an agent](/registry/agents/how-tos/edit-agent). |
| `PATCH /agent/v1/agents/{agent_id}` | Saves a new version when any definition field changes. A change to only the display name or description edits in place. | Scripts and CI that update the definition. |
| `POST /agent/v1/agents/{agent_id}/versions` | Always saves a new version, from only the fields you send. Every other field carries over. Adds a `version_label`, a version `description`, and an `auto_release` choice. | You want to label a version or hold it unreleased. |

Rules for `POST …/versions`:

* **`version_label`** is a human label, such as `v1.2.0`. `latest` is reserved.
* **`auto_release`**: leave it out to follow the workspace's release policy, or send `false` to keep the version unreleased. `true` under a manual policy is refused with `422`.
* **Concurrent edits are refused.** If someone else saved a version after you read the agent, the request fails with `412`. Read the agent again and retry.
* **An archived agent can't take a new version.** The request fails with `409`.

A new version is released under the workspace's release policy, like a skill version. Under automatic publishing it is released once its required checks pass; under manual publishing it waits for someone to release it. See [Set workspace release policy](/administer/workspaces/how-tos/set-release-policy).

## Read versions

**In the app:** Open the agent's profile, select **Settings**, and find **Releases**: "The versions of this agent and the channels each one ships on."

* **Current release** shows the version clients get and the publishing policy.
* **Unreleased changes** appears when a newer version isn't released yet. People with permission see **Prepare release**.
* **Release history** lists releases newest first. Withdrawn releases stay on the record.

Versions are labeled **Revision 1**, **Revision 2**, and so on.

**With the API:** `GET /agent/v1/agents/{agent_id}/versions` lists versions newest first, as summaries without definition fields. `GET /agent/v1/agents/{agent_id}/versions/{version_ordinal}` returns exactly what one version said.

## When a manifest is refused

A manifest that breaks one of the rules above is refused with `400`, and no version is saved. Check that each skill exists and isn't archived, appears once, and has a release or a named `version_ordinal`, and that the manifest has 64 skills or fewer.

## Related

* [Edit an agent](/registry/agents/how-tos/edit-agent): Change an agent from its profile.
* [Register agents through API](/cookbooks/how-tos/agents): Create agents and publish versions from code.
* [How skill versions and releases work](/registry/skills/concepts/versions): The skill versions an agent pins.


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