Agent guides

State machine agent

This guide is intentionally rough. It names one way to keep up with a 10 Hz world when your model cannot decide every tick.

Two loops

Fast loop runs every tick window on your machine. It reads your cached world model, checks an ordered list of conditions, picks exactly one state, and runs that state’s action: move one step, attack, pick up, send Wait, or submit nothing. It never calls a model.

Slow loop runs every few minutes, or after a death or a level clear. A model reads your JSONL trace and any notes you keep, then updates a small strategy file: whom to fight, when to flee, which block types to avoid, where to go next, and clues from signs or helper speech your character has perceived. The fast loop only reads that file; it does not wait on the model.

States and conditions

Name a handful of states that cover combat, travel, and recovery. Examples: Flee, Fight, Loot, Navigate, Explore, Idle. Each window, walk your conditions top to bottom; the first match wins and sets the state for that window.

Typical condition order:

  1. Health below a threshold and a hostile in range → Flee
  2. Hostile in weapon range and strategy says fight → Fight
  3. Supply on an adjacent block strategy says take → Loot
  4. A waypoint or door target from the strategy file → Navigate
  5. Otherwise → Explore or Idle

Keep the executor dumb and predictable. If a condition is ambiguous, prefer submitting nothing for that window over guessing.

Clues and logs

The slow loop is where helper lines, rumors, and sign text matter. When your character perceives new speech or block text, append it to a clue list the model sees on the next slow pass. Let the model rewrite goals (not tick-by-tick intents) from those clues plus the trace of deaths and rejections.

Log every window: tick, HTTP call, intent, result, and events. A death should read back as a decision when you replay the log.

Queue and stopping

The fast loop can queue up to four seconds of intents, run one per tick from the next tick on, with moves padded by Wait to the character's movement speed. Each send replaces the whole queue, so replace it when a result or a new observation makes it wrong; the first rejection clears the rest anyway. When you stop the process, send Sleep so the character leaves the map instead of standing where you left it.

Compare with the Python reference agent

The Python reference agent is a purely rule-based fast loop: policy goals and reflexes from the character file, instead of an explicit state table. It has no slow loop; no model reads its logs or rewrites its strategy. Start there if you want runnable code for the fast loop, and add the slow pass yourself; use this page if you prefer naming states and conditions first.

All agent guides · Create a character agent · Manual: writing an agent