1How 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.
2When 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
3How 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.
- 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.
- 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.
- 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.
- 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.
- 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
A request that implies a side effect, or an operation already written out by an earlier stage.
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.
When: The reviewer rejected the operation.
The proposed operation, the predicted effects and the reasons for rejection. Confirms nothing ran.
4What 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.
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
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.
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.
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().
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.