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 <agent-name> [options]

Arguments:

Argument	Required	Description
name	Yes	Agent name

Options:

Flag	Description
-g, --genes <genes...>	Gene names to include in genome
--composition <type>	Composition type: Seq (default), Par, Cond, Try, TryPool
--par-merge <strategy>	Merge strategy for Par branches: first (default), concat, merge
--domain <domain>	Auto-select top genes from this domain
--top <n>	Number of top genes to auto-select (default: 2)
--strategy <strategy>	Gene selection strategy (default: greedy)

Lifecycle states:

• Initializing → Active → Terminated

The agent is automatically activated upon creation.

Examples:

# Sequential pipeline (default)
$ rotifer agent create search-agent --genes web-search code-format
  ✓ Agent 'search-agent' created
  Genome:  web-search → code-format (Seq)

# Parallel execution with merge
$ rotifer agent create multi-search --genes web-search doc-search --composition Par --par-merge concat
  Genome:  web-search ∥ doc-search (Par)

# Conditional branching
$ rotifer agent create smart-agent --genes fast-search deep-search --composition Cond
  Genome:  fast-search / deep-search (Cond)

---

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 <agent-name> [options]

Arguments:

Argument	Required	Description
name	Yes	Agent name to run

Options:

Flag	Description
--input <json>	Input JSON for the pipeline (default: {"name":"world"})
--verbose	Show intermediate input/output for each step
--no-sandbox	Force Node.js execution (skip WASM sandbox)

How it works:

1. Load agent’s genome and composition configuration
2. For each gene, prefer WASM sandbox execution if compiled (gene.ir.wasm exists)
3. Execute genes using composition algebra (Seq by default, or as configured)
4. Return combined result with execution metrics (fuel, duration)

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
• TryPool — Try multiple genes in pool, return first success

Example:

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

  [1/2] genesis-web-search completed via WASM sandbox (23ms, fuel: 42000)
    Input:  { "query": "rotifer protocol" }
    Output: { "results": [...] }

  [2/2] genesis-code-format completed via WASM sandbox (12ms, fuel: 18500)
    Input:  { "code": "..." }
    Output: { "formatted": "..." }

  ✓ Pipeline execution complete
  Genes Executed: 2
  Duration: 35ms