Skip to content

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.

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

Terminal window
rotifer agent create <agent-name> [options]

Arguments:

ArgumentRequiredDescription
nameYesAgent name

Options:

FlagDescription
-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)
--memory-quota <size>The agent’s memory quota: a number with KB, MB or GB, e.g. 50MB (default: 10MB). See Memory API.

Lifecycle states:

  • Initializing → Active → Terminated

The agent is automatically activated upon creation.

Examples:

Terminal window
# 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)
# With a larger memory quota
$ rotifer agent create my-agent --genes hello-world --memory-quota=50MB
✓ Agent 'my-agent' created
Memory quota: 50 MB

View all registered agents and their states.

Terminal window
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:

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

Look at and clean up what an agent has stored in its memory. Both commands act as the agent’s deployer, so the entries’ access policies do not limit them. See Memory API for what the entries are.

Terminal window
rotifer agent memory list <agent-name> [options]
rotifer agent memory delete <agent-name> (--key <key> | --category <category>)

list options:

FlagDescription
-c, --category <category>Only entries of this category: PREFERENCE, PATTERN, CONTEXT or CACHE

list shows each entry’s key, category, size, the gene that created it and when it was last updated, then how much of the agent’s quota is used. It never prints values.

delete options (give exactly one):

FlagDescription
-k, --key <key>Delete the entry with this key
-c, --category <category>Delete every entry of this category

delete prints how many entries it removed. Deleting a key that does not exist fails with MEMORY_NOT_FOUND. PREFERENCE entries are never cleared to make room, so this is how you free a full memory. Every deletion is recorded in the audit log.

Examples:

Terminal window
$ rotifer agent memory list my-agent --category PREFERENCE
$ rotifer agent memory delete my-agent --category CACHE
✓ Deleted 3 entries from my-agent's memory

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

Terminal window
rotifer agent run <agent-name> [options]

Arguments:

ArgumentRequiredDescription
nameYesAgent name to run

Options:

FlagDescription
--input <json>Input JSON for the pipeline (default: {"name":"world"})
--verboseShow intermediate input/output for each step
--no-sandboxForce Node.js execution (skip WASM sandbox)
--trust-unsignedAllow Node.js execution for Cloud-installed or ClawHub-wrapped genes
--allow-credentials <list>Let external genes use these credentials from your environment, each only at its host: KEY@api.example.com,KEY2@other.example.com. Without it, an external gene that runs in the sandbox and declares a credential makes the command ask once at a terminal (default no), or exit 1 with credentials_not_granted elsewhere. This only covers sandboxed genes: a gene you let run on Node.js with --trust-unsigned is not asked about and can read every environment variable you have

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). A gene installed from Cloud or wrapped from ClawHub that is not compiled is refused on the Node.js path unless you pass --trust-unsigned — the same rule as rotifer run. The L0 gate still applies either way
  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:

Terminal window
$ 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