Agents

An Axocoatl agent is a ractor actor: an isolated unit of computation with its own mailbox, lifecycle, memory, and token budget. Each agent runs in its own task. Crashes get supervised restarts. State survives the process through periodic checkpoints.

Anatomy of an agent

Every agent has six knobs you control in YAML:

- id: coder
  name: "Coder"
  provider: ollama
  model: qwen2.5-coder:14b
  system_prompt: |
    You are a senior software engineer working in a directory session.
    Write to disk with the write_file tool; never paste code as chat.
  depends_on: [planner]
  token_budget:
    per_execution: 8000
    per_call:      4000
    overflow_policy: warn

• id — the agent’s name in the lattice. Other agents depends_on this id.
• provider + model — which LLM backs this agent. Each agent can use a different one. Local for cheap tasks, frontier for hard ones, same workflow.
• system_prompt — the agent’s role and operating instructions.
• depends_on — which agents must complete before this one activates. Drives the DAG.
• token_budget — enforced before every LLM call. The agent can’t spend more than per_call in any single call or more than per_execution across one full activation. overflow_policy: warn logs
  • emits an event; block refuses the call.

Lifecycle

1. Spawn — on daemon boot, every agent in the config gets a ractor::Actor spawned under the daemon’s supervisor.
2. Idle — the actor sits in its mailbox loop, waiting for messages.
3. Activate — the lattice routes work to it via an Execute message when its dependencies fire.
4. Stream — the LLM call streams tokens (when supported by the provider). The dashboard’s Studio rail reflects them live.
5. Checkpoint — periodically the actor writes its message history and memory state to disk so a crash + restart can resume from where it left off.
6. Complete — publishes TaskCompleted to the lattice with the output. Other agents activate.

Supervision

If an agent panics or its LLM provider returns an unrecoverable error, the supervisor restarts it from its last checkpoint. The agent’s mailbox is preserved across the restart — pending work continues. The dashboard shows the restart in the agent’s status line and emits a RestartedAgent event so other parts of the system can react.

Providers

Provider trait lets every agent pick its backend independently:

• ollama — local Ollama daemon (default).
• openai — OpenAI chat completions.
• anthropic — Anthropic messages API.
• mistral — Mistral chat.
• gemini — Google Gemini.

Keys live in .env. The dashboard’s onboarding wizard fills the right keys for you.

Restart, manually

If you change an agent’s config (system prompt, model, budget) and want the running actor to pick it up without restarting the whole daemon:

axocoatl agents restart coder

The supervisor stops the actor, re-reads its config, and respawns it. Memory survives.