Skip to main content
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

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

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.

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