docs

Planned Execution

In planned mode, the agent generates a structured JSON plan first, then executes each step in order with optional per-step verification.

Configure planned mode

agentfile.yaml
agents:
  my-agent:
    execution:
      mode: planned
      verify_steps: true            # verify each step result
      max_steps: 15                 # max plan steps
      on_step_failure: continue     # abort | continue | retry_once

      verifier:
        provider: anthropic
        model: claude-haiku-4-5-20251001    # use a cheaper model for verification
        max_tokens: 256

How it works

  1. Planning phase: LLM receives the task and generates a JSON plan (no tools available); plan structure is validated — missing or malformed fields fall back to direct mode automatically
  2. Execution phase: Each plan step is executed in order
  3. Verification (optional): After each step, the verifier LLM checks the result against the expected outcome
  4. On failure: Apply on_step_failure policy — abort, continue, or retry once

Failure policies

PolicyBehavior
abortStop the run immediately and report the failure
continueLog the failure and proceed to the next step
retry_onceRetry the failed step once before applying continue
When to use planned mode
Planned mode works best for tasks with clear, sequential steps — code migrations, data pipelines, multi-step research. For open-ended conversation, use direct mode.
On this page