Agentic Architectures

Catalogue / Guardrails & Routing

Dry Run

Simulate the action and get approval before anything runs

Shape
gate
Model calls
3 per proposed action
Latency
medium
Complexity
medium

Also known as Simulate-then-approve

1

How do I let an agent near real systems without fearing what it does?

The agent never acts directly. It writes down the exact action it intends, a simulator predicts the effects without touching anything, and a reviewer approves or blocks. Only an approved action reaches the system.

You may need it if

  • The agent can send email, change records, run commands or spend money.
  • One wrong action would be costly or impossible to undo.
  • You need a record of what was proposed, predicted and approved.
2

When is an approval gate just friction?

Use it when

  • Actions have side effects outside the conversation.
  • The effect of an action can be predicted or previewed before it runs.
  • A person or a strict policy must stay in control of irreversible steps.

Avoid it when

  • The agent only reads data or writes text for a person to review. There is nothing to gate.
    Use Tool Use instead
  • The concern is the wording or policy compliance of a text, not an action on a system.
    Use Constitutional Critique instead
  • Effects cannot be predicted without running the action. The simulation would be a guess presented as a check.

What it costs

Model calls
3 per proposed action
Latency
medium
Complexity
medium
3

How does an action get from intention to execution?

A one-way line with a gate and two exits. The proposer writes the action, the simulator predicts its effects, the reviewer decides. Approved actions run and leave with their outcome. Rejected actions leave with the reasons and nothing has run.

approvedrejectedRequest: What the user wants done, or an action already proposed by an earlier stage.RequestProposer: Writes the exact operation it intends, with its target and parameters.ProposerSimulator: Predicts what the operation would change, without executing it.SimulatorApprove?: Compares the predicted effects with the request and the policy. A person can hold this role.Approve?Executor: The only component with write access. Runs exactly the approved operation.ExecutorExecuted: The record of what ran and what it changed.ExecutedBlocked: The refusal, with the reasons. Nothing was executed.Blocked
  1. Step 1 of 5

    Intention becomes an explicit operation

    The proposer turns the request into the precise operation, such as the command, the query or the message with its recipients. It cannot run it.

  2. Step 2 of 5

    The effects are predicted

    The simulator states what would change, how much, and whether it can be undone. Where the system offers a preview mode, it uses that.

  3. Step 3 of 5

    The gate

    The reviewer sees the request, the operation and the predicted effects. It approves only if the effects match the request and break no rule.

  4. Step 4 of 5

    Approved, so it runs

    The executor runs the approved operation unchanged and records the real effect. This is the only place where anything touches the system.

  5. Step 5 of 5

    Rejected, so nothing happens

    A rejected operation leaves through a separate exit with the reviewer's reasons. Whatever comes next can tell the two exits apart.

What each part does
Request
What the user wants done, or an action already proposed by an earlier stage.
Proposer
Writes the exact operation it intends, with its target and parameters.
Simulator
Predicts what the operation would change, without executing it.
Approve?
Compares the predicted effects with the request and the policy. A person can hold this role.
Executor
The only component with write access. Runs exactly the approved operation.
Executed
The record of what ran and what it changed.
Blocked
The refusal, with the reasons. Nothing was executed.
  • Proposer → Simulator: exact operation
  • Simulator → Approve?: predicted effects
  • Approve? → Executor: approved
  • Approve? → Blocked: rejected

Where it connects

Entry
request
TaskProposed actionPlan

A request that implies a side effect, or an operation already written out by an earlier stage.

Exit
executed
Outcome

When: The reviewer approved the operation and the executor ran it.

The operation that ran, the predicted effects, the real effects, and any difference between the two.

Exit
blocked
Verdict

When: The reviewer rejected the operation.

The proposed operation, the predicted effects and the reasons for rejection. Confirms nothing ran.

4

What do I ask my assistant to set up?

The agents to launch

Proposer

Translate the request into one exact operation, with target, parameters and scope. State what you expect it to change. You have no ability to execute it.

Sees: The request and read-only information about the target system.

Simulator

Predict the effects of the operation without running it. State what changes, how many items are affected, whether it can be undone, and what you could not determine. Use the system's preview mode when one exists.

Sees: The exact operation and read-only access to the target. Not the proposer's justification.

Reviewer

Approve or reject. Approve only if the predicted effects match the request, stay inside the stated policy and leave no unknown that matters. Give your reasons in either case. When in doubt, reject.

Sees: The original request, the exact operation, the predicted effects and the policy. Not the proposer's reasoning.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Dry Run" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Dry Run
Simulate the action and get approval before anything runs.
Input: the task above. It must provide: A request that implies a side effect, or an operation already written out by an earlier stage. If something essential is missing, ask for it before starting.

Agents to launch:
- Proposer: Translate the request into one exact operation, with target, parameters and scope. State what you expect it to change. You have no ability to execute it.
  Context for this agent: The request and read-only information about the target system.
- Simulator: Predict the effects of the operation without running it. State what changes, how many items are affected, whether it can be undone, and what you could not determine. Use the system's preview mode when one exists.
  Context for this agent: The exact operation and read-only access to the target. Not the proposer's justification.
- Reviewer: Approve or reject. Approve only if the predicted effects match the request, stay inside the stated policy and leave no unknown that matters. Give your reasons in either case. When in doubt, reject.
  Context for this agent: The original request, the exact operation, the predicted effects and the policy. Not the proposer's reasoning.

Procedure:
1. State the policy in a few rules: what may never be done, and what needs a person's approval.
2. Launch the proposer on the request. If the input already contains an exact operation, use it and skip this step.
3. Launch the simulator on the operation in a fresh context.
4. Launch the reviewer. If the policy requires a person for this kind of operation, present the same three items to the person and wait.
5. If approved, execute exactly the approved operation, then compare the real effects with the prediction. If rejected, execute nothing.

Stop rule: Stop after one decision. An approved operation ends at the outcome record, a rejected one at the refusal. Do not revise and retry without a new request.

Exits:
- `executed`, when: The reviewer approved the operation and the executor ran it. Deliver: The operation that ran, the predicted effects, the real effects, and any difference between the two.
- `blocked`, when: The reviewer rejected the operation. Deliver: The proposed operation, the predicted effects and the reasons for rejection. Confirms nothing ran.

# Final deliverable
Either the outcome record (operation, predicted effects, real effects, differences) or the refusal (operation, predicted effects, reasons), clearly labelled as executed or blocked.

The same thing in code

LangGraph, python, package langgraph
from typing import TypeVar

from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel, ConfigDict

llm = init_chat_model("anthropic:claude-sonnet-5-5")
M = TypeVar("M", bound=BaseModel)
POLICY = """Never delete more than 100 records. Never touch production billing.
Any operation that cannot be undone needs a person's approval."""


class Operation(BaseModel):
    model_config = ConfigDict(frozen=True)  # approval is for this exact operation
    action: str
    target: str
    parameters: str
    scope: str


class Proposal(BaseModel):
    operation: Operation
    expected_change: str


class Prediction(BaseModel):
    changes: str
    affected_count: int
    reversible: bool
    unknowns: list[str]


class Decision(BaseModel):
    approved: bool
    reasons: list[str]


class State(BaseModel):
    request: str
    proposal: Proposal | None = None
    prediction: Prediction | None = None
    decision: Decision | None = None
    record: dict = {}


def read_target(target: str) -> str:
    return ""  # plug in a read-only view of the target system


def preview(op: Operation) -> str:
    return ""  # plug in the system's own dry-run or preview mode, if it has one


def ask_person(request: str, op: Operation, prediction: Prediction) -> Decision:
    return Decision(approved=False, reasons=["awaiting a person"])  # plug in your approval queue or interrupt()


def execute(op: Operation) -> str:
    return ""  # the only code holding write credentials: plug in the real call


async def ask(schema: type[M], prompt: str) -> M:
    return schema.model_validate(await llm.with_structured_output(schema).ainvoke(prompt))


async def proposer(state: State) -> dict:
    return {"proposal": await ask(Proposal, "Translate the request into one exact operation with target, "
                                  f"parameters and scope, and say what it should change. You cannot execute it.\n"
                                  f"Target state: {read_target(state.request)}\n\nRequest: {state.request}")}


async def simulator(state: State) -> dict:
    op = state.proposal.operation if state.proposal else None  # the operation only, not the justification
    return {"prediction": await ask(Prediction, "Predict the effects without running it: what changes, how many "
                                    f"items, whether it can be undone, what you could not determine.\n"
                                    f"Preview: {preview(op) if op else ''}\n\nOperation: {op}")}


async def reviewer(state: State) -> dict:
    op = state.proposal.operation if state.proposal else None
    decision = await ask(Decision, "Approve only if the predicted effects match the request, stay inside the "
                         "policy and leave no unknown that matters. Give reasons. When in doubt, reject.\n"
                         f"Policy: {POLICY}\nRequest: {state.request}\nOperation: {op}\nPrediction: {state.prediction}")
    if decision.approved and op and state.prediction and not state.prediction.reversible:
        decision = ask_person(state.request, op, state.prediction)  # the policy puts a person on this gate
    return {"decision": decision}


def gate(state: State) -> str:
    return "executor" if state.decision and state.decision.approved else END  # rejected: nothing runs


async def executor(state: State) -> dict:
    assert state.proposal and state.prediction
    op = state.proposal.operation  # frozen: the executor runs it unchanged
    return {"record": {"status": "executed", "operation": op, "predicted": state.prediction, "real": execute(op)}}


graph = StateGraph(State).add_sequence([proposer, simulator, reviewer])
graph.add_node(executor)
graph.add_edge(START, "proposer")
graph.add_conditional_edges("reviewer", gate, ["executor", END])
graph.add_edge("executor", END)  # one decision, then stop: no revise-and-retry
app = graph.compile()


async def run(task: str):
    state = State.model_validate(await app.ainvoke(State(request=task)))
    return state.record or {"status": "blocked", "operation": state.proposal and state.proposal.operation,
                            "predicted": state.prediction, "reasons": state.decision and state.decision.reasons}

Wire the stubs to a read-only client and the system's real preview, keep write credentials inside execute() only, and add an interrupt for human approvals.

Claude Agent SDK, python, package claude-agent-sdk
from typing import Any, TypeVar

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, create_sdk_mcp_server, query, tool
from pydantic import BaseModel

M = TypeVar("M", bound=BaseModel)
POLICY = """Never delete more than 100 records. Never touch production billing.
Any operation that cannot be undone needs a person's approval."""


class Operation(BaseModel):
    action: str
    target: str
    parameters: str
    scope: str


class Proposal(BaseModel):
    operation: Operation
    expected_change: str


class Prediction(BaseModel):
    changes: str
    affected_count: int
    reversible: bool
    unknowns: list[str]


class Decision(BaseModel):
    approved: bool
    reasons: list[str]


@tool("read_target", "Read-only view of the target system", {"target": str})
async def read_target(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": ""}]}  # plug in a read-only client


@tool("preview", "The system's own dry-run mode for an operation", {"operation": str})
async def preview(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": ""}]}  # plug in the system's preview mode


READ_ONLY = create_sdk_mcp_server("target", tools=[read_target, preview])
AGENTS = {
    "proposer": AgentDefinition(
        description="Turns a request into one exact operation. Cannot execute.",
        prompt="Translate the request into one exact operation with target, parameters and scope. "
        "State what you expect it to change.",
        tools=["mcp__target__read_target"],
    ),
    "simulator": AgentDefinition(
        description="Predicts an operation's effects without running it.",
        prompt="Predict what changes, how many items, whether it can be undone and what you could not "
        "determine. Use the preview tool when it applies.",
        tools=["mcp__target__read_target", "mcp__target__preview"],
    ),
    "reviewer": AgentDefinition(
        description="Approves or rejects an operation against the policy.",
        prompt="Approve only if the predicted effects match the request, stay inside the policy and leave "
        "no unknown that matters. Give reasons either way. When in doubt, reject.",
        tools=[],
    ),
}


async def delegate(agent: str, payload: str, schema: type[M]) -> M:
    # one query per agent: each sees only the payload, never the others' reasoning
    options = ClaudeAgentOptions(
        agents={agent: AGENTS[agent]}, mcp_servers={"target": READ_ONLY},
        tools=["Agent"], allowed_tools=["Agent"], max_turns=8,
        output_format={"type": "json_schema", "schema": schema.model_json_schema()},
    )
    async for message in query(prompt=f"Hand this input unchanged to the {agent} agent and return its result:\n\n{payload}", options=options):
        if isinstance(message, ResultMessage):
            return schema.model_validate(message.structured_output)
    raise RuntimeError(f"{agent} returned nothing")


def ask_person(request: str, op: Operation, prediction: Prediction) -> Decision:
    return Decision(approved=False, reasons=["awaiting a person"])  # plug in your approval queue


def execute(op: Operation) -> str:
    return ""  # the only code holding write credentials; no agent can reach it


async def run(task: str):
    proposal = await delegate("proposer", task, Proposal)
    op = proposal.operation
    prediction = await delegate("simulator", op.model_dump_json(), Prediction)
    decision = await delegate("reviewer", f"Policy: {POLICY}\nRequest: {task}\nOperation: {op.model_dump_json()}\n"
                              f"Predicted effects: {prediction.model_dump_json()}", Decision)
    if decision.approved and not prediction.reversible:
        decision = ask_person(task, op, prediction)  # the policy puts a person on this gate
    if not decision.approved:  # one decision, then stop: no revise-and-retry
        return {"status": "blocked", "operation": op, "predicted": prediction, "reasons": decision.reasons}
    return {"status": "executed", "operation": op, "predicted": prediction, "real": execute(op)}

Wire the read-only MCP tools to your system and keep write credentials only in execute(), outside every agent's reach.

OpenAI Agents SDK, python, package openai-agents
from agents import Agent, Runner, function_tool
from pydantic import BaseModel

POLICY = """Never delete more than 100 records. Never touch production billing.
Any operation that cannot be undone needs a person's approval."""


class Operation(BaseModel):
    action: str
    target: str
    parameters: str
    scope: str


class Proposal(BaseModel):
    operation: Operation
    expected_change: str


class Prediction(BaseModel):
    changes: str
    affected_count: int
    reversible: bool
    unknowns: list[str]


class Decision(BaseModel):
    approved: bool
    reasons: list[str]


@function_tool
def read_target(target: str) -> str:
    """Read-only view of the target system."""
    return ""  # plug in a read-only client


@function_tool
def preview(operation: str) -> str:
    """Run the system's own dry-run mode for an operation."""
    return ""  # plug in the system's preview mode


proposer = Agent(name="Proposer", tools=[read_target], output_type=Proposal,
                 instructions="Translate the request into one exact operation with target, parameters and "
                 "scope. State what you expect it to change. You cannot execute it.")
simulator = Agent(name="Simulator", tools=[read_target, preview], output_type=Prediction,
                  instructions="Predict the effects without running it: what changes, how many items, whether "
                  "it can be undone, what you could not determine. Use preview when it applies.")
reviewer = Agent(name="Reviewer", output_type=Decision,
                 instructions="Approve only if the predicted effects match the request, stay inside the policy "
                 "and leave no unknown that matters. Give reasons either way. When in doubt, reject.")


def ask_person(request: str, op: Operation, prediction: Prediction) -> Decision:
    return Decision(approved=False, reasons=["awaiting a person"])  # plug in your approval queue


def execute(op: Operation) -> str:
    return ""  # the only code holding write credentials; no agent has this as a tool


async def run(task: str):
    op = (await Runner.run(proposer, task)).final_output_as(Proposal).operation
    # fresh contexts: the simulator and reviewer get the operation, not the proposer's justification
    prediction = (await Runner.run(simulator, op.model_dump_json())).final_output_as(Prediction)
    review = await Runner.run(reviewer, f"Policy: {POLICY}\nRequest: {task}\nOperation: {op.model_dump_json()}\n"
                              f"Predicted effects: {prediction.model_dump_json()}")
    decision = review.final_output_as(Decision)
    if decision.approved and not prediction.reversible:
        decision = ask_person(task, op, prediction)  # the policy puts a person on this gate
    if not decision.approved:  # one decision, then stop: no revise-and-retry
        return {"status": "blocked", "operation": op, "predicted": prediction, "reasons": decision.reasons}
    return {"status": "executed", "operation": op, "predicted": prediction, "real": execute(op)}

Wire the stubs to a read-only client and the system's real preview, and keep write credentials only inside execute().

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, isStepCount, Output, tool } from 'ai';
import { z } from 'zod';

const model = anthropic('claude-sonnet-5-5');
const POLICY = `Never delete more than 100 records. Never touch production billing.
Any operation that cannot be undone needs a person's approval.`;

const operationSchema = z.object({ action: z.string(), target: z.string(), parameters: z.string(), scope: z.string() });
type Operation = z.infer<typeof operationSchema>;
const predictionSchema = z.object({
  changes: z.string(), affectedCount: z.number().int(), reversible: z.boolean(), unknowns: z.array(z.string()),
});
type Prediction = z.infer<typeof predictionSchema>;

// read-only tools; nothing here can write
const readTarget = tool({
  description: 'Read-only view of the target system.',
  inputSchema: z.object({ target: z.string() }),
  execute: async ({ target }) => ({ target, state: '' }), // plug in a read-only client
});
const preview = tool({
  description: "Run the system's own dry-run mode for an operation.",
  inputSchema: z.object({ operation: z.string() }),
  execute: async () => ({ preview: '' }), // plug in the system's preview mode
});

async function askPerson(request: string, op: Operation, prediction: Prediction) {
  return { approved: false, reasons: ['awaiting a person'] }; // plug in your approval queue
}
async function execute(op: Operation): Promise<string> {
  return ''; // the only code holding write credentials; no model gets it as a tool
}

export async function run(task: string) {
  const { output: proposal } = await generateText({
    model, tools: { readTarget }, stopWhen: isStepCount(5), prompt: task,
    instructions: 'Translate the request into one exact operation with target, parameters and scope. ' +
      'State what you expect it to change. You cannot execute it.',
    output: Output.object({ schema: z.object({ operation: operationSchema, expectedChange: z.string() }) }),
  });
  const op = Object.freeze(proposal.operation); // approval holds for this exact operation
  // fresh contexts: simulator and reviewer get the operation, not the proposer's justification
  const { output: prediction } = await generateText({
    model, tools: { readTarget, preview }, stopWhen: isStepCount(5), prompt: JSON.stringify(op),
    instructions: 'Predict the effects without running it: what changes, how many items, whether it can be ' +
      'undone, what you could not determine. Use preview when it applies.',
    output: Output.object({ schema: predictionSchema }),
  });
  let { output: decision } = await generateText({
    model,
    instructions: 'Approve only if the predicted effects match the request, stay inside the policy and leave ' +
      'no unknown that matters. Give reasons either way. When in doubt, reject.',
    prompt: `Policy: ${POLICY}\nRequest: ${task}\nOperation: ${JSON.stringify(op)}\nPredicted: ${JSON.stringify(prediction)}`,
    output: Output.object({ schema: z.object({ approved: z.boolean(), reasons: z.array(z.string()) }) }),
  });
  if (decision.approved && !prediction.reversible) decision = await askPerson(task, op, prediction); // a person holds this gate
  if (!decision.approved) return { status: 'blocked', operation: op, prediction, reasons: decision.reasons }; // nothing ran
  return { status: 'executed', operation: op, prediction, real: await execute(op) }; // one decision, no retry
}

Wire the stubs to a read-only client and the system's real preview, and keep write credentials only inside execute().

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • If the proposer holds write access, the gate is decorative. Only the executor may hold credentials.
  • A simulation written by a model is a prediction. Prefer the system's own preview and flag every unknown.
  • Editing the operation after approval voids the approval. The executor must run it unchanged.

Chain it

It can take the result of