Agent Commands

Agents are autonomous entities that use genes to perform tasks. An agent has a genome — a set of genes it can invoke — and automatically selects the fittest gene for each task from the Arena.

rotifer agent create

Create a new agent with a genome composed of selected genes.

rotifer agent create <name> [options]

Arguments:

Argument	Required	Description
name	Yes	Agent name

Options:

Flag	Description
--genome <genes...>	Gene IDs (hex) to include in genome

Lifecycle states:

• Initializing → Active → Terminated

The agent is automatically activated upon creation.

Example:

$ rotifer agent create search-agent --genome a3f2b1c4 d5e6f7a8
  ✓ Agent 'search-agent' created

  ID:      agent-abc123
  State:   Active
  Genome:  2 genes

---

rotifer agent list

View all registered agents and their states.

rotifer agent list

Output columns:

• ID — Unique agent identifier
• Name — Agent name
• State — Lifecycle state (Initializing / Active / Terminated)
• Genome — Number of genes in genome

Example:

$ rotifer agent list
  ┌──────────────┬──────────────┬────────┬────────┐
  │ ID           │ Name         │ State  │ Genome │
  ├──────────────┼──────────────┼────────┼────────┤
  │ agent-abc123 │ search-agent │ Active │ 2      │
  │ agent-def456 │ file-agent   │ Active │ 3      │
  └──────────────┴──────────────┴────────┴────────┘

---

rotifer agent run

Execute an agent’s genome pipeline — the agent selects and invokes genes based on Arena fitness rankings.

rotifer agent run <name> [options]

Arguments:

Argument	Required	Description
name	Yes	Agent name to run

How it works:

1. Load agent’s genome (set of gene IDs)
2. For each gene in the genome, check Arena rankings
3. Execute genes using composition algebra (Seq by default)
4. Return combined result

Composition operators available:

• Seq — Execute genes sequentially, piping output to next input
• Par — Execute genes in parallel, collect all results
• Cond — Conditional execution based on runtime predicate
• Try — Execute primary gene, fall back to secondary on error

Example:

$ rotifer agent run search-agent
  Running agent 'search-agent'...

  Step 1: genesis-web-search (search.web)
    Input:  { "query": "rotifer protocol" }
    Output: { "results": [...] }
    Time:   120ms

  Step 2: genesis-code-format (code.format)
    Input:  { "code": "..." }
    Output: { "formatted": "..." }
    Time:   45ms

  ✓ Agent completed in 165ms
  Total genes executed: 2