Agents

The AKOS CLI gives you full lifecycle control over agents in your workspace: register them in the registry, move them through lifecycle states with audit trails, generate drafts from plain English descriptions, and compare evaluation results across variants.

Registering an agent

agentskit-os agent register \
  --id summarizer \
  --owner alice@example.com \
  --purpose "Summarizes incoming emails and posts to Slack"

Required flags:

Flag	Description
`--id <slug>`	Agent identifier (lowercase, hyphen-separated)
`--owner <id>`	Responsible owner — email address or handle
`--purpose <text>`	Short description of what the agent does

Optional flags:

Flag	Description
`--state <s>`	Initial lifecycle state (default: `draft`)
`--risk <t>`	Risk tier (default: `low`)
`--workspace-root <path>`	Override workspace runtime root

Lifecycle states: draft, review, approved, staged, production, deprecated, retired

Risk tiers: low, medium, high, critical

Listing registered agents

agentskit-os agent list

Outputs each agent's ID, lifecycle state, risk tier, and owner. Add --json for machine-readable output.

agentskit-os agent list --json

Generating an agent from a description

To generate a starter agent configuration from a plain-English description:

agentskit-os agent from-nl "Summarize Slack DMs daily and post a digest"

The command infers the agent's intent (verb, cadence, confidence) and outputs a YAML draft ready to paste into your workspace config.

Save directly to a file:

agentskit-os agent from-nl "Monitor GitHub issues and triage by label" \
  --out agents/issue-triage.yaml

Output as JSON instead of YAML:

agentskit-os agent from-nl "Send weekly report to Notion" --format json

Promoting an agent through the lifecycle

agent promote validates a lifecycle transition against the AKOS governance graph and emits an audit event. It does not modify the registry by default (dry-run mode).

agentskit-os agent promote \
  --agent-id summarizer \
  --from draft \
  --to review \
  --actor alice@example.com

To commit the transition to the registry (update state and append the audit event):

agentskit-os agent promote \
  --agent-id summarizer \
  --from review \
  --to approved \
  --actor alice@example.com \
  --check code_review \
  --check security_scan \
  --commit

Promote options

Flag	Description
`--from <state>`	Current lifecycle state (required)
`--to <state>`	Target lifecycle state (required)
`--agent-id <slug>`	Agent identifier (default: `unknown`)
`--actor <id>`	Principal authorizing the transition
`--risk <tier>`	Risk tier (default: `low`)
`--check <name>`	Satisfied governance gate (repeatable)
`--reason <text>`	Free-form reason recorded in the audit event
`--json`	Emit the audit event as JSON
`--commit`	Persist the transition to the registry

If a transition is blocked by unsatisfied gates, the CLI prints which checks are missing and exits non-zero.

Viewing agent version history

agentskit-os agent version --agent-id summarizer

Prints the audit trail of lifecycle transitions for an agent. Add --json for structured output.

Comparing agent variants

Use agent compare to rank multiple agent variants by pass rate, cost, and latency from a saved evaluation run.

First, prepare a JSON file containing evaluation results for each variant:

[
  { "id": "variant-a", "passRate": 0.92, "meanCostUsd": 0.004, "meanLatencyMs": 820 },
  { "id": "variant-b", "passRate": 0.88, "meanCostUsd": 0.002, "meanLatencyMs": 510 }
]

Then run the comparison:

agentskit-os agent compare evaluations.json

The CLI prints a ranked table and the overall winner. Adjust scoring weights to match your priorities:

agentskit-os agent compare evaluations.json \
  --pass 0.7 \
  --cost 0.1 \
  --latency 0.2

Default weights: pass rate 0.6, cost 0.2, latency 0.2. Weights do not need to sum to 1.

Output as JSON:

agentskit-os agent compare evaluations.json --json

Viewing the agent changelog

agentskit-os agent changelog --agent-id summarizer

Prints the recorded change events for an agent. Add --json for structured output.

On this page