---
title: Agents
description: Register, list, version, promote, and compare agents from the command line.
---

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

```bash
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

```bash
akos agent list
```

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

```bash
akos agent list --json
```

## Generating an agent from a description

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

```bash
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:

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

Output as JSON instead of YAML:

```bash
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).

```bash
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):

```bash
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

```bash
akos agent version-list --id summarizer
```

Prints the recorded version history 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:

```json
[
  { "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:

```bash
akos agent compare evaluations.json
```

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

```bash
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:

```bash
akos agent compare evaluations.json --json
```

## Viewing the agent changelog

```bash
akos agent changelog --agent-id summarizer
```

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

## Related topics

- **[Agents in the app](/docs/using-the-app/agents)** — registry UI, lifecycle promotion, sandbox test.
- **[Model catalog](/docs/using-the-app/model-catalog)** — choosing models in agent forms.
- **[Quality checks (Evals)](/docs/using-the-app/evals)** — regression suites that gate promotions.
- **[Flows and Runs](/docs/cli/flows-and-runs)** — run agents inside workflow graphs.