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

akos 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

akos agent list

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

akos agent list --json

Generating an agent from a description

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

akos 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:

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

Output as JSON instead of YAML:

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

akos 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):

akos 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

akos 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:

akos agent compare evaluations.json

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

akos 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:

akos agent compare evaluations.json --json

Viewing the agent changelog

akos agent changelog --agent-id summarizer

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

On this page