kindgi agents

`kindgi agents`

Synopsis

kindgi agents <command>

Signature

Manage agent registrations and which version runs where.

Commands

Command	Description
`kindgi agents list`	List registered agents (the latest version of each).
`kindgi agents get`	Fetch a registered agent: its latest version, or the version given.
`kindgi agents publish`	Register an agent definition.
`kindgi agents derive`	Publish a new agent version from a pinned one with some prompt or settings pins swapped (no code change).
`kindgi agents unregister`	Unregister a specific agent version: runs stop using it.
`kindgi agents versions`	List the registered versions of an agent.
`kindgi agents live`	Show the version a run of this agent would use for a project and segment path, and why: a live version (with its scope) or the latest.
`kindgi agents live-versions`	List every scope with a live version of this agent pinned.
`kindgi agents promote`	Make a version live for a scope: its runs that don't name a version use it, from the next run.
`kindgi agents gate-policy`	Show the gate policy a promotion of this agent for a scope is checked against (the most specific scope with one), or null.
`kindgi agents rollback`	Put a scope back on its previous live version, or on the version given.
`kindgi agents unpin`	Remove a scope's own live version: its runs use the next scope up (or the latest when nothing is pinned).
`kindgi agents promotions`	The history of what was made live, rolled back or unpinned.

See also

`kindgi agents list`

Synopsis

kindgi agents list [--name=<prefix>] [--include-retired] [--limit=<n>] [--cursor=<c>]

Signature

List registered agents (the latest version of each).

Options

Option	Default	Description
`--cursor <value>`	none	Resume after this cursor, from the previous page's `nextCursor`.
`--include-retired`	off	Include retired agents (every version unregistered), each as its highest version with `unregisteredAt`.
`--limit <value>`	`25` (at most `100`)	The most to return (default 25, at most 100).
`--name <value>`	none	Only agents whose id starts with this.

Every command also takes the global flags.

Examples

List the registered agents.

kindgi agents list

List agents whose id starts with a prefix, including retired ones.

kindgi agents list --name=acme-ops. --include-retired

See also

`kindgi agents get`

Synopsis

kindgi agents get <agent-id> [<version>]

Signature

Fetch a registered agent: its latest version, or the version given.

Options

Every command also takes the global flags.

Examples

Show an agent's latest version.

kindgi agents get acme-ops.reply-drafter

Show one specific version.

kindgi agents get acme-ops.reply-drafter 1.2.0

See also

`kindgi agents publish`

Synopsis

kindgi agents publish --spec=<json-or-@file> [--project=<project-id>]

Signature

Options

Option	Default	Description
`--project <value>`	the tenant's Default project	The project to register the agent in, by id (default: the tenant's Default project).
`--spec <value>`	required	The agent definition as JSON, or `@<file>` to read it from a file. Required.

Every command also takes the global flags.

Examples

kindgi agents publish --spec=@agent.json

kindgi agents publish --spec=@agent.json --project=<project-id>

See also

`kindgi agents derive`

Synopsis

kindgi agents derive <agent-id> --from=<semver> [--prompt=<block-id>=<version>]... [--setting=<block-id>=<version>]... [--label=<text>] [--project=<project-id>]

Signature

Publish a new agent version from a pinned one with some prompt or settings pins swapped (no code change).

Options

Option	Default	Description
`--from <value>`	required	The agent version to derive from; it must be pinned. Required.
`--label <value>`	none	A short label for the new version.
`--project <value>`	none	The agent's project, by id; only needed when the runtime doesn't record it on the version.
`--prompt <value>`	none (at least one `--prompt` or `--setting` is required)	Pin a prompt block the version already uses to this version (`<block-id>=<version>`). Repeat for several. Repeatable.
`--setting <value>`	none (at least one `--prompt` or `--setting` is required)	Pin a settings block the version already uses to this version (`<block-id>=<version>`). Repeat for several. Repeatable.

Every command also takes the global flags.

Examples

From Change a prompt or a setting without a deploy:

pnpm exec kindgi agents derive acme-ops.reply-drafter --from=1.0.0 --setting=acme.reply-style=1.1.0 --label="Refund limit 100"

See also

`kindgi agents unregister`

Synopsis

kindgi agents unregister <agent-id> <version>

Signature

Unregister a specific agent version: runs stop using it.

Options

Every command also takes the global flags.

Examples

Unregister one version of an agent, so runs stop using it.

kindgi agents unregister acme-ops.reply-drafter 1.2.0

See also

`kindgi agents versions`

Synopsis

kindgi agents versions <agent-id> [--include-unregistered] [--limit=<n>] [--cursor=<c>]

Signature

List the registered versions of an agent.

Options

Option	Default	Description
`--cursor <value>`	none	Resume after this cursor, from the previous page's `nextCursor`.
`--include-unregistered`	off	Include unregistered versions (each with `unregisteredAt`), a retired agent's too.
`--limit <value>`	`25` (at most `100`)	The most to return (default 25, at most 100).

Every command also takes the global flags.

Examples

List an agent's registered versions.

kindgi agents versions acme-ops.reply-drafter

Include unregistered versions too.

kindgi agents versions acme-ops.reply-drafter --include-unregistered

See also

`kindgi agents live`

Synopsis

kindgi agents live <agent-id> [--project=<project-id> [--segment=<key:value>]…]

Signature

Show the version a run of this agent would use for a project and segment path, and why: a live version (with its scope) or the latest.

Options

Option	Default	Description
`--project <value>`	none	The run's project, by id.
`--segment <value>`	none	One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.

Every command also takes the global flags.

Examples

From Release an agent version:

pnpm exec kindgi agents live acme.order-desk --project=<project-id> --segment=company:acme

See also

`kindgi agents live-versions`

Synopsis

kindgi agents live-versions <agent-id>

Signature

List every scope with a live version of this agent pinned.

Options

Every command also takes the global flags.

Examples

List every scope with a live version of the agent.

kindgi agents live-versions acme.order-desk

See also

`kindgi agents promote`

Synopsis

kindgi agents promote <agent-id> <version> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) [--eval-run=<eval-run-id>] [--reason=<text>] [--check]

Signature

Make a version live for a scope: its runs that don't name a version use it, from the next run. Open conversations keep their version. With a gate policy for the scope, the comparison named by --eval-run is checked first: the answer's status is promoted, or pending-approval (a reviewer approves it); a refusal lists every check. --check asks what would happen, changing nothing.

Options

Option	Default	Description
`--check`	off	What the gate would say: would-promote, needs-approval or gate-failed. Changes nothing.
`--eval-run <value>`	none	The comparison eval run the gate checks, kept on the record.
`--idempotency-key <value>`	none	A retry with the same key returns the first call's result.
`--org <value>`	required: one of `--tenant`, `--org`, `--project`	An org, by id.
`--project <value>`	required: one of `--tenant`, `--org`, `--project`	A project, by id; with `--segment`, a segment in it.
`--reason <value>`	none	Why, kept on the record.
`--segment <value>`	none	One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.
`--tenant`	required: one of `--tenant`, `--org`, `--project`	The whole tenant.

Every command also takes the global flags.

Examples

From Live versions reference:

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

From Release an agent version:

pnpm exec kindgi agents promote acme.order-desk 1.0.0 --tenant --reason="1.0.0 is the version we checked"

See also

`kindgi agents gate-policy`

Synopsis

kindgi agents gate-policy <agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…)

Signature

Show the gate policy a promotion of this agent for a scope is checked against (the most specific scope with one), or null.

Options

Option	Default	Description
`--org <value>`	required: one of `--tenant`, `--org`, `--project`	An org, by id.
`--project <value>`	required: one of `--tenant`, `--org`, `--project`	A project, by id; with `--segment`, a segment in it.
`--segment <value>`	none	One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.
`--tenant`	required: one of `--tenant`, `--org`, `--project`	The whole tenant.

Every command also takes the global flags.

Examples

Show the gate policy for the whole tenant.

kindgi agents gate-policy acme.order-desk --tenant

Show the policy for a segment of a project.

kindgi agents gate-policy acme.order-desk --project=<project-id> --segment=company:acme

See also

`kindgi agents rollback`

Synopsis

kindgi agents rollback <agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) [--to=<semver>] [--reason=<text>]

Signature

Put a scope back on its previous live version, or on the version given.

Options

Option	Default	Description
`--idempotency-key <value>`	none	A retry with the same key returns the first call's result.
`--org <value>`	required: one of `--tenant`, `--org`, `--project`	An org, by id.
`--project <value>`	required: one of `--tenant`, `--org`, `--project`	A project, by id; with `--segment`, a segment in it.
`--reason <value>`	none	Why, kept on the record.
`--segment <value>`	none	One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.
`--tenant`	required: one of `--tenant`, `--org`, `--project`	The whole tenant.
`--to <value>`	the previous live version	An earlier version to go back to (default: the previous one).

Every command also takes the global flags.

Examples

From Release an agent version:

pnpm exec kindgi agents rollback acme.order-desk --tenant --reason="1.2.0 answers worse"

See also

`kindgi agents unpin`

Synopsis

kindgi agents unpin <agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) [--reason=<text>]

Signature

Remove a scope's own live version: its runs use the next scope up (or the latest when nothing is pinned).

Options

Option	Default	Description
`--idempotency-key <value>`	none	A retry with the same key returns the first call's result.
`--org <value>`	required: one of `--tenant`, `--org`, `--project`	An org, by id.
`--project <value>`	required: one of `--tenant`, `--org`, `--project`	A project, by id; with `--segment`, a segment in it.
`--reason <value>`	none	Why, kept on the record.
`--segment <value>`	none	One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.
`--tenant`	required: one of `--tenant`, `--org`, `--project`	The whole tenant.

Every command also takes the global flags.

Examples

From Release an agent version:

pnpm exec kindgi agents unpin acme.order-desk --tenant --reason="Back to the latest"

See also

`kindgi agents promotions`

Synopsis

kindgi agents promotions <command>

Signature

The history of what was made live, rolled back or unpinned.

Commands

Command	Description
`kindgi agents promotions list`	List an agent's promotions, rollbacks and unpins, newest first; name a scope for only its history.
`kindgi agents promotions get`	Fetch one promotion of an agent.

See also

`kindgi agents promotions list`

Synopsis

kindgi agents promotions list <agent-id> [(--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…)] [--limit=<n>] [--cursor=<c>]

Signature

List an agent's promotions, rollbacks and unpins, newest first; name a scope for only its history.

Options

Option	Default	Description
`--cursor <value>`	none	Resume after this cursor, from the previous page's `nextCursor`.
`--limit <value>`	`25` (at most `100`)	The most to return (default 25, at most 100).
`--org <value>`	none (no scope given: the history of every scope)	An org, by id.
`--project <value>`	none (no scope given: the history of every scope)	A project, by id; with `--segment`, a segment in it.
`--segment <value>`	none	One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.
`--tenant`	none (no scope given: the history of every scope)	The whole tenant.

Every command also takes the global flags.

Examples

From Live versions reference:

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

See also

`kindgi agents promotions get`

Synopsis

kindgi agents promotions get <agent-id> <promotion-id>

Signature

Fetch one promotion of an agent.

Options

Every command also takes the global flags.

Examples

Show one promotion of an agent.

kindgi agents promotions get acme.order-desk <promotion-id>

See also