Agent mode | AX Documentation

agent_mode is a top-level model variable. Accepts a single value or list of build / plan. It is cross-multiplied with the other axes just like agents and models to define the variants tested.

build (default) runs the agent normally: it executes tools, can read and write, and mutates the workspace.
plan puts the agent in its native read-only / planning mode. This plans, and mutates nothing in the sandbox. The abstract plan value resolves to that agent's planning mode (claude / cursor resolve to plan, codex to read-only). If the selected mode isn't available the variant fails loudly rather than silently running in build.

# Sweep both modes over one agent/model/prompt → 2 variants.
agents: [claude]
models: [claude-opus-4-8]
agent_mode: [build, plan]

agent_mode is optional; defaulting to build mode. When you declare the axis, the mode is emitted into the variant id. This applies to plan and build options. So a [build, plan] sweep produces …::build::my-prompt and …::plan::my-prompt. When the axis is absent nothing is emitted, so experiments that don't use agent_mode keep their original ids (for example claude::anthropic-claude-opus-4-8::my-prompt). Note that authoring agent_mode: build explicitly therefore yields a different id than omitting the axis.

A plan variant produces no file changes. Every test in the flat tests list runs for every variant regardless of mode; the harness does not scope tests by agent_mode. A build-oriented workspace check will fail the plan variant unless you guard it (e.g. [ ! -f out.json ] || <verify out.json>). For a [build, plan] sweep, score the plan variant with trace-based checks over $AX_TRACE_PATH. See examples/experiments/plan-mode-comparison.yaml.

Search documentation