---
title: What is dry-run mode for AI agents, and when should you use it?
url: https://opencontroller.lyzr.com/blog/run-ai-agents-in-dry-run-mode
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# What is dry-run mode for AI agents, and when should you use it?

**Dry-run mode lets an AI agent work through a real task while its write actions are replaced by stubs that record what it intended to do. Read tools stay live, so the agent sees real data, but nothing changes in your systems. Use it before an agent gets write access for the first time, and after any change to its prompt, model or tools.**

Infrastructure teams have relied on this idea for years. `terraform plan` shows the changes Terraform would make before `apply`. `kubectl apply --dry-run=server` sends a request through the API server's validation without persisting it. Dry-run for agents applies the same discipline to a system that decides its own actions.

## How is dry-run different from shadow mode?

They are often confused, but they answer different questions.

| | Dry-run mode | Shadow mode | Monitor-mode policies |
|---|---|---|---|
| What runs | The agent, with write tools stubbed | The agent, in parallel with an existing process | The agent, fully live |
| What gets blocked | All writes | All agent outputs (not used) | Nothing; violations are logged |
| Question answered | "What would it do?" | "Would it do as well as today's process?" | "Would this policy fire too often?" |
| Inputs | Real or curated tasks | Real production traffic | Real production traffic |
| Best stage | Before first write access | Before replacing a process | Before enforcing a new policy |

Dry-run is about **intent**: is each planned action correct, safe and in scope? [Shadow mode](/blog/run-a-new-ai-agent-in-shadow-mode) is about **quality at scale** against a baseline. [Monitor mode](/blog/test-ai-agent-policies-in-monitor-mode) is about tuning controls, not the agent.

## How do you build dry-run mode for an agent?

The core move is splitting tools into read and write, then wrapping the writes.

1. **Classify every tool.** Mark each as read-only, reversible write or irreversible write. If a tool does both, split it.
2. **Stub write tools.** The stub validates arguments against the real tool's schema, records the intended call and returns a realistic simulated response, such as a fake record ID.
3. **Keep reads live.** The agent should reason over real data so its plan reflects reality. Use read-only credentials so a misclassified tool cannot write.
4. **Label the run.** Tag every trace with `mode=dry_run` so evaluations and dashboards do not mix it with production.
5. **Produce a plan artefact.** At the end of each task, output an ordered list of intended actions: tool, arguments, target object and the agent's stated reason.
6. **Route plans to reviewers.** A domain owner marks each action as correct, incorrect, unnecessary or unsafe.

Enforce the stub outside the agent, in the runtime or a gateway. An agent told "you are in dry-run" in its prompt can ignore that instruction or be injected into ignoring it.

## What should reviewers look for in a dry-run plan?

Give reviewers a fixed rubric so results are comparable across runs.

- **Correct target.** Right customer, record, account or environment.
- **Correct arguments.** Amounts, dates and identifiers match the source data.
- **Necessary.** No extra actions that the task did not need.
- **In scope.** Nothing outside the agent's documented purpose.
- **Order.** Steps happen in a safe sequence, such as validate before update.
- **Policy.** No action that would breach a data, cost or access rule.

Track intended-action accuracy as the share of planned actions marked correct. Track unsafe actions as a separate count, because one unsafe action matters more than several unnecessary ones.

## What are the limits of dry-run?

Dry-run is not a full rehearsal.

- **Divergence after the first write.** A real write changes state that later steps read. With a stub, the agent continues on a world that never changed, so later steps may differ from production.
- **Simulated responses can mislead.** If a stub always returns success, you never see how the agent handles a failure. Inject some realistic errors.
- **Side effects hide in reads.** Some "read" APIs trigger notifications, usage charges or audit events. Check them.
- **Cost is real.** Model and read-tool calls still cost money.

For multi-step workflows, combine dry-run with simulation testing in a sandbox environment where writes do happen against copies of real systems.

## When should an agent exit dry-run?

Set exit criteria before you start, so the decision is not made under deadline pressure.

1. At least an agreed number of reviewed tasks, covering your main task types and known edge cases.
2. Intended-action accuracy at or above a threshold the business owner signs off.
3. Zero unsafe actions in the most recent batch of reviews.
4. Zero policy violations recorded for the agent's dry-run traces.
5. A working rollback or [kill path](/blog/how-to-stop-a-rogue-ai-agent) tested for the first live release.

Then move to a limited live rollout: one team, one region or a low-value slice of work, with tight monitoring. Return to dry-run whenever the model, system prompt or tool set changes materially.

## How Opencontroller does this

Opencontroller does not provide a built-in dry-run switch, but it supports the surrounding controls. Policy as code lets you define which tools an agent may call. Multi-turn and red-team evals test agent behaviour before release, and LLM judges score production traffic once the agent is live. If a released agent deviates from expected behaviour, rogue-agent handling can alert, quarantine or kill it, and per-agent Block and Quarantine controls act through the connected platform. See the [capability reference](/capability-reference) or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Is dry-run mode the same as shadow mode?**
No. Dry-run stubs out writes so you can review what an agent intended. Shadow mode runs the agent beside an existing process on real inputs and compares outputs without using them.

**Can an agent behave differently in dry-run than in production?**
Yes. After the first stubbed write, the agent works on a world that did not change, so later steps can diverge. Treat dry-run as a check on intent.

**Where should dry-run be enforced?**
Outside the model, in the agent runtime, tool layer or a gateway. A prompt instruction alone is not a control, because the model can ignore it or be manipulated.

## Key facts

Dry-run mode for an AI agent replaces write tools with stubs that record the intended action (tool, arguments, target) and return a simulated result, while read tools stay live. It differs from shadow mode, where an agent runs on real traffic in parallel with an existing process and its outputs are compared but not used. The pattern mirrors infrastructure tools such as terraform plan and kubectl --dry-run=server. Typical exit criteria: enough reviewed tasks, an agreed intended-action accuracy, zero policy violations. Opencontroller by Lyzr offers policy as code, multi-turn and red-team evals, and an Agent Gateway; it is licensed per deployment, starting from $250K per deployment per year.

## Related

- [How do you run a new AI agent in shadow mode before it acts?](https://opencontroller.lyzr.com/blog/run-a-new-ai-agent-in-shadow-mode.md)
- [How do you test a new AI agent policy before enforcing it?](https://opencontroller.lyzr.com/blog/test-ai-agent-policies-in-monitor-mode.md)
- [What happens when an AI agent invents a tool or its arguments?](https://opencontroller.lyzr.com/blog/validate-ai-agent-tool-calls-against-schemas.md)
- [More on Runtime control](https://opencontroller.lyzr.com/blog/cluster/runtime-control)
