Live versions reference

View as Markdown

This page lists everything about live agent versions: how a run gets its version, what conversations and flows keep, what requests to make a version live, rollbacks and unpins refuse, the go-live history, every pin that covers a project, release gate policies, and what the console shows. On the CLI, making a version live is kindgi agents promote. To release a version, follow Release an agent version.

How a run gets its version

A run's agent.via says how it got its version:

`via`	The version is
`live`	the live version of the scope in `liveScope`
`latest`	the latest, because nothing is live for this run
`explicit`	the one the run named, with `--agent-version` or `agentVersion`
`flow-pin`	the one its flow version holds, as Flows keep their versions describes
`conversation`	the one its conversation started with, as Conversations keep their version describes

The most specific live version wins: a segment path in a project, then the project, the project's org, the tenant, and then the latest version. Without --project, a run is in its agent's own project, which is Default for what kindgi deploy registers.

A version only goes live when you make it live: publishing a newer version doesn't change what a scope with a live version runs.

Conversations keep their version

A follow-up turn in a conversation keeps the version the conversation started with, even after another version goes live, so the conversation stays consistent. Here a conversation started on 1.2.0. Then 1.0.0 went live for the tenant, and the conversation's next turn still ran 1.2.0:

  "agent": {
    "id": "acme.order-desk",
    "version": "1.2.0",
    "conversationId": "9fce3360-5426-4578-b387-361afa9f2156",
    "via": "conversation"
  },

Excerpt

A new conversation gets the live version.

Flows keep their versions

A published flow version holds the agent versions it was published with. Each agent step runs the version its node names, config.version. Otherwise it runs the one a run in the flow's project would get when the flow version is published: the live version, from the project, then the org, then the tenant, or the latest when none is live. Its turns say "via": "flow-pin", and making another version live doesn't change them.

Here acme.order-flow 1.0.0 was published while 1.3.0 was live. After the tenant went back to 1.0.0, its step still ran 1.3.0:

  "agent": {
    "id": "acme.order-desk",
    "version": "1.3.0",
    "conversationId": "5547f2a1-88b2-4b34-8d63-294f21fa5642",
    "via": "flow-pin"
  },

Excerpt

To run a new agent version in a flow, publish a new version of the flow.

Its tool steps are held the same way: each runs the tool version the flow version locked when it was published, which is the tool's pinned version for the flow's project when a pin covers it, else the tool's newest.

Rollbacks and unpins

A rollback puts a scope back on the version that was live there before, or on --to=<version>, at once. No release gate policy checks it. On a self-hosted runtime with one pack service, that version runs only while your pack still has the tool versions it locked (A self-hosted runtime runs what your pack has).
An unpin removes a scope's own live version. Its runs then use a wider scope's live version, or the latest version when none is live.

What each refuses:

a version that isn't registered: Version 9.9.9 is not registered (or was unregistered);
a rollback where nothing was live before: The scope had no live version before this one: unpin it to fall back to the scope above;
an unpin where the scope has no live version of its own: The scope has no live version of its own;
an unpin of a scope with a release gate policy, since such a scope keeps its own live version: segment company:acme in project <project-id> has a gate policy for acme.order-desk, and a gated scope keeps its own live version: unregister the gate policy first, or roll back instead.

To retire a version that's live somewhere, roll back, unpin or make another version live in each of those scopes first. Until then, kindgi agents unregister refuses it with 409 agent-version-live.

Go-live history

Every request to make a version live, rollback and unpin is kept, with who asked and why, newest first:

pnpm exec kindgi agents promotions list acme.order-desk --table

--table prints a table. STATUS says how each ended, done for a rollback or an unpin:

ID                                    ACTION    STATUS    SCOPE                                                      FROM   TO     BY                                         AT
────────────────────────────────────  ────────  ────────  ─────────────────────────────────────────────────────────  ─────  ─────  ─────────────────────────────────────────  ────────────────────────
d6db591b-8afc-4413-81c8-a794d9f848a5  unpin     done      tenant                                                     1.0.0  -      user 5c0a7e11-0000-4000-8000-0000000000aa  2026-10-06T18:48:59.665Z
7da674c5-c835-42c0-8cde-59571afd0915  rollback  done      tenant                                                     1.2.0  1.0.0  user 5c0a7e11-0000-4000-8000-0000000000aa  2026-10-06T18:48:47.871Z
70ea0024-ec7e-4122-abc4-04df1eb7b9eb  promote   promoted  tenant                                                     1.0.0  1.2.0  user 5c0a7e11-0000-4000-8000-0000000000aa  2026-10-06T18:48:43.578Z
912e10e7-18fb-4228-92b9-33b3f2a4d45b  promote   promoted  project 367e1657-8067-4a1d-8ec4-bfa3c5fc5865 company=acme  -      1.1.0  user 5c0a7e11-0000-4000-8000-0000000000aa  2026-10-06T18:48:23.207Z
ea4e7c15-7990-41b6-b153-0847a83f2e9d  promote   promoted  tenant                                                     -      1.0.0  user 5c0a7e11-0000-4000-8000-0000000000aa  2026-10-06T18:46:15.125Z

--tenant, --org, --project and --segment narrow it to one scope's history.
A request's status is promoted, pending-approval, refused, superseded, rejected or expired. A waiting request is superseded when something changed before it was approved: what serves the scope isn't what the release gate policy measured against (another request went live first, for example), the scope's release gate policy isn't the one it passed (a new version, another policy, or none now), the version is no longer registered, or making it live would move a narrower scope that has a release gate policy of its own and follows this one.
--eval-run=<eval-run-id> on promote keeps the run on the test cases behind the decision on its record.

Every pin that covers a project

GET /v1/projects/<project-id>/pinned-versions lists every agent's pins that cover a project: the tenant's, the project's org's, the project's own and its segments'. They're ordered by agent, then by scope, and each one is as an agent's own list of live versions shows it:

{
  "data": [
    {
      "agentId": "acme.order-desk",
      "scope": { "kind": "tenant" },
      "version": "1.0.0",
      "promotionId": "5b1d0c4e-2f7a-4c8e-9d36-0a8e4f1b7c21",
      "setAt": "2026-10-06T18:46:15.125Z"
    },
    {
      "agentId": "acme.order-desk",
      "scope": {
        "kind": "segment",
        "projectId": "367e1657-8067-4a1d-8ec4-bfa3c5fc5865",
        "path": [{ "key": "company", "value": "acme" }]
      },
      "version": "1.1.0",
      "promotionId": "a3f6e2d9-7c14-4b5a-8e0f-6d2c9b1a4e73",
      "setAt": "2026-10-06T18:48:23.207Z"
    }
  ],
  "hasMore": false
}

A run in the project takes the most specific of them that covers it, as How a run gets its version says.

Reading it takes read on the project. It lists only the pins of agents and versions you can read, as an agent's own list does, so a page can hold fewer pins than limit, or none, and still have more: page on nextCursor, not on the count. limit is 25 by default and at most 100, and cursor=<nextCursor> gets the next page. In the TypeScript client it's projects.pinnedVersions.list, and in the Python client projects.pinned_versions.list. A runtime that can't list them answers 501 pinned-versions-not-supported.

Release gate policies

A release gate policy's parts, and what each asks of a request to make a version live:

Part	A request must show
`comparison.maxAgeHours`	a run of the version on the test cases, finished at most this many hours ago
`evidence.minCases`	each figure resting on at least this many corrected cases, for the version and for the live one
`metrics`	each named figure at least `minCandidate`, and lower than the live version's by at most `maxDrop`. The figures are `weightedYesShare`, `judgedCoverage`, or `weightedPrecisionAtK` with its `k`
`replay`	at most this many diverged cases, errors, refused tool calls and stopped cases: `maxDiverged`, `maxErrors`, `maxRefusedWrites`, `maxStopped`. `maxRefusedWrites` counts refused reads too, despite its name. Those left out are 0. A version with other settings runs read-only tools live, which counts as diverged, so `maxDiverged: 0` refuses it
`approvals`	then a reviewer with this role approves it, `senior` if left out. It's someone other than whoever asked, unless `separateApprover: false` lets the one who asked approve it
`onlyRestrictedClasses: true`	a run on the test cases that counted only experts' corrections

A request must name its run on the test cases when the policy has comparison, evidence, metrics, replay or onlyRestrictedClasses. The run must be of the version you make live, with the same pins, and its recorded runs must be from the version live for the scope now.
With onlyRestrictedClasses, a run on the test cases that counted everyone's judgments is refused with The policy counts only experts' judgments; the test run counted everyone's. Re-run it with `classWeights: 'restricted-only'`.. So only restricted judge classes can release a version.
To change a release gate policy, publish a new version of it. kindgi gate-policies unregister acme.order-desk-release <version> goes back to the one before.
kindgi agents gate-policy acme.order-desk --tenant shows the policy that applies to a scope.
With authorization on, publishing a release gate policy takes admin on the tenant. Reading one takes read on its scope: its project, a segment's too, its org, or the tenant for a tenant-wide one. A policy you can't read is left out of lists, and answers 404 gate-policy-not-found, as if it weren't there.

A scope with a release gate policy needs a live version of its own

Otherwise, the next published version, or making a version live for a wider scope, would reach its runs without its release gate policy. A policy for a scope without one is refused:

The tenant has no live version of acme.order-desk of its own, so publishing a version would make it live here ungated: pin a version for this scope first (1.2.0 serves it now)

A scope whose runs get their version from a wider scope's pin, such as a segment that runs its project's version, is refused the same way, naming that pin:

Segment company:globex has no live version of acme.order-desk of its own, so a promotion for project <project-id> would change it without this gate: pin a version for this scope first (1.0.0 serves it now)

Pin it in place: make the version it serves now live there. That changes nothing for its runs, so it needs no run on the test cases and no approval, even when a release gate policy already applies:

pnpm exec kindgi agents promote acme.order-desk 1.0.0 --project=<project-id> --segment=company:globex --reason="Pin globex before its gate"

<project-id> is the segment's project.
--segment=company:globex is the segment, key:value. A deeper segment repeats --segment, coarse to fine.
--reason says why, and is kept with the request.

Under a release gate policy, the request's one check says why it went through, and its reason starts with pin-in-place: acme.order-desk 1.0.0 already serves this scope (from a pin above it), so pinning it here changes nothing for runs: the gate's checks and approval don't apply. --check answers would-promote with that same check.

A scope with a release gate policy that still follows a wider scope's pin, such as one set up by an older runtime, refuses making a version live, a rollback or an unpin in that wider scope with 409 gate-policy-descendant-unpinned, naming the scope and its version:

Promoting acme.order-desk for project <project-id> would also change segment company:acme, which a gate policy applies to and which has no live version of its own, without its gate. Pin it at its current version first: segment company:acme at 1.0.0

Pin that scope in place, and make the version live again.

In the console

An agent's page tags the version a run in this project gets Pinned or Latest, and its Versions and rollbacks button opens the agent's Pinned versions page.
Pinned versions says which version a run in this project gets, such as "Runs here use 1.0.0", and why: "It's pinned for every project (the tenant-wide default)." It has Check a segment path, a key and a value, to see what a run on a path would get. It lists every pin that reaches this project with its part, each with Roll back and Unpin: "Runs here take it", or "Runs on this path take it" for a segment. Then it has the Pin history, with who and why.
Pin a version picks the version and where it's pinned: this project, every project in its org when it's in one, every project, or a segment path in this project. It says what will happen before you pin it, such as "Runs in this project (Support) will use 1.3.0."
A run's page says why it ran its version, such as "Pinned for company = acme in this project (Default)".
Release gate policies, on the Pinned versions page, has each policy in sentences, with its versions, New version and Add a release gate policy. The sentences read like "Share marked right: at least 60%, and no more than 2 points below the pinned version" and "Then a senior reviewer approves it, someone other than whoever asked".
Add a release gate policy has Count only experts: "The run must count only experts' corrections (start it with "Count only experts"), so a correction anyone may give can't change what the release gate policy decides."
Pin a version has Run on the test cases (optional), a finished run of the version on the test cases. One that counted only restricted classes says "restricted classes only". It runs the release gate policy's check before anything is recorded: "The release gate policy passes (release gate policy acme.order-desk-release 1.0.0) Then a senior reviewer approves it, someone other than you, and it's pinned.", with each check. Its button follows: Ask to pin 1.3.0, or "The release gate policy refuses it".
A request waiting for approval shows on Pinned versions, with Open the approval. Its approval page shows the request to pin it, who asked and why, the run on the test cases and the policy, and each check. Once approved, it says "Pinned 1.3.0, replacing 1.0.0".