1How does an agent choose well when it can only try once?
Some decisions cannot be tested for real: a price change, a reply to an angry key account, a migration date. The agent lists a few candidate actions, imagines what happens after each one, scores the imagined outcomes against fixed criteria and commits to the winner, naming the trade-off it accepts.
You may need it if
- The agent faces a choice between a few actions, and trying the wrong one is costly or visible to customers.
- You can describe what a good outcome looks like before seeing the options.
- Decisions are questioned afterwards and you need to show why one option beat the others.
2When is imagining the outcome a waste of time?
Use it when
- There are two to five real options and you can only pick one: discount, extend the trial, or let the account go.
- The consequences follow from knowledge the model has, such as how customers, teams or markets usually react.
- The decision is worth a few minutes of model time and a written justification.
Avoid it when
- The action is cheap and reversible. Trying it and watching the result beats imagining it.
Use ReAct instead - The system itself can preview the effect, such as a billing preview or a database dry run. Use the real preview, not an imagined one.
Use Dry Run instead - Success needs a long sequence of moves, each depending on what the last one revealed.
Use Language Agent Tree Search instead - The outcome depends on facts the model does not have, such as this quarter's churn data. The simulation would be confident fiction.
What it costs
- Model calls
- 1 + N simulations + 1 scoring (N = 3 to 5)
- Latency
- medium
- Complexity
- medium
3How does a decision move from options to a commitment?
A short line with a fan-out. Candidate actions are listed, each one is simulated in its own context, a judge scores the imagined outcomes against fixed criteria and a rule picks the winner. If no option clears the hard limits, one new set of options is tried.
- Step 1 of 5
Options on the table
The option writer lists distinct actions, for example a 20% discount, a free onboarding package, or no concession. If the input already holds options, it only restates them precisely.
- Step 2 of 5
Each future is imagined apart
Each option goes to its own simulator. It describes what follows over a set horizon, such as the customer's reply, the cost and the precedent created. No simulator sees the other options.
- Step 3 of 5
One scale for all
The judge scores every imagined outcome on the same weighted criteria, written before the run. Any outcome that breaks a hard limit is eliminated, whatever its score.
- Step 4 of 5
Commit or try again once
A rule takes the best surviving option. If none survives, the option writer gets one chance to propose a new set, with the reasons the first set failed.
- Step 5 of 5
The decision and its price
The winner leaves as a proposed action, not yet executed, with the trade-off it accepts, such as lower margin in exchange for keeping the account.
What each part does
- Situation
- The goal and the current facts, or a set of options already drawn up by an earlier stage.
- Option writer
- Lists three to five genuinely different actions, each stated precisely enough to simulate.
- Simulators
- One per option. Imagines what happens next, step by step, including side effects and reactions.
- Judge
- Scores every imagined outcome on the same weighted criteria and checks the hard limits.
- Clear winner?
- Picks the top score among options that pass every hard limit, and counts the retries.
- Decision
- The chosen action with its simulated outcome, its scores and the trade-off accepted.
- Option writer → Simulators: one option each
- Simulators → Judge: imagined outcomes
- Judge → Clear winner?: scores and limit checks
- Clear winner? → Option writer: none passes, 1 retry left
- Clear winner? → Decision: winner found or retry spent
Where it connects
A decision to make, with the current facts, or a list of candidate actions to compare. Criteria and hard limits are optional, the stage writes them when absent.
When: An option passes every hard limit with the top score, or the single retry is spent.
The chosen action, not yet executed, its simulated outcome, the score of every option, the trade-off accepted, and a flag if no option passed all limits.
4What do I ask my assistant to set up?
The agents to launch
Option writer
List three to five actions that could reach the goal. Make them different in kind, not in degree. State each one precisely enough to simulate: who does what, when, at what cost. Do not say which one you prefer.
Sees: The goal, the current facts and, on a retry, why the previous options failed. Not the criteria weights.
Simulator, one per option
Assume this action is taken today. Describe what happens over the stated horizon: immediate effects, reactions of the people involved, costs, and what becomes harder afterwards. Mark every assumption you make. Do not judge whether it is a good idea.
Sees: The current facts and one option. Not the other options, not the criteria.
Judge
Score every simulated outcome from 1 to 10 on each weighted criterion. Eliminate any outcome that breaks a hard limit, and say which one. Flag outcomes that rest on a doubtful assumption. Then name the trade-off each surviving option asks you to accept.
Sees: The criteria, weights, hard limits and all simulated outcomes. Not the option writer's notes.
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 "Mental Simulation" 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] # Mental Simulation Imagine each option's outcome, score it, then commit to one. Input: the task above. It must provide: A decision to make, with the current facts, or a list of candidate actions to compare. Criteria and hard limits are optional, the stage writes them when absent. If something essential is missing, ask for it before starting. Agents to launch: - Option writer: List three to five actions that could reach the goal. Make them different in kind, not in degree. State each one precisely enough to simulate: who does what, when, at what cost. Do not say which one you prefer. Context for this agent: The goal, the current facts and, on a retry, why the previous options failed. Not the criteria weights. - Simulator (one per option): Assume this action is taken today. Describe what happens over the stated horizon: immediate effects, reactions of the people involved, costs, and what becomes harder afterwards. Mark every assumption you make. Do not judge whether it is a good idea. Context for this agent: The current facts and one option. Not the other options, not the criteria. - Judge: Score every simulated outcome from 1 to 10 on each weighted criterion. Eliminate any outcome that breaks a hard limit, and say which one. Flag outcomes that rest on a doubtful assumption. Then name the trade-off each surviving option asks you to accept. Context for this agent: The criteria, weights, hard limits and all simulated outcomes. Not the option writer's notes. Procedure: 1. Write the decision criteria before any option exists: three to five criteria with weights, and one or two hard limits that eliminate an option outright. 2. Launch the option writer. If the input already contains options, use them and only make each one precise. 3. Launch one simulator per option, each in a fresh context, with the same time horizon. 4. Launch the judge on all simulated outcomes at once. 5. Pick the surviving option with the highest weighted score. If none survives and no retry was used, send the reasons to the option writer and repeat from the simulator step. 6. Write the decision with the trade-off it accepts. Do not execute the action. Stop rule: Stop when one option passes every hard limit with the top weighted score, or after one retry. If nothing passes then, return the least bad option, clearly flagged. Exit: - `decision`, when: An option passes every hard limit with the top score, or the single retry is spent. Deliver: The chosen action, not yet executed, its simulated outcome, the score of every option, the trade-off accepted, and a flag if no option passed all limits. # Final deliverable The chosen action, its simulated outcome, a table of every option with its scores, the trade-off accepted, and the assumptions the decision depends on.
The same thing in code
import operator
from typing import Annotated, TypedDict, cast
from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from langgraph.types import Send
from pydantic import BaseModel
llm = init_chat_model("anthropic:claude-sonnet-5-5")
# fixed before any option exists, so they cannot be bent to fit a favourite
CRITERIA = {"cost": 0.3, "customer impact": 0.4, "reversibility": 0.3}
HARD_LIMITS = ["exceeds the approved budget", "breaks a legal or contractual obligation"]
HORIZON, MAX_RETRIES = "the next 90 days", 1
class Options(BaseModel):
options: list[str] # three to five, different in kind: who does what, when, at what cost
class Assessment(BaseModel):
option: int # index of the option
scores: list[int] # 1 to 10, one per criterion, in the order given
broken_limit: str # empty when every hard limit holds
doubtful_assumption: str
trade_off: str
class Judgement(BaseModel):
assessments: list[Assessment]
class Input(TypedDict):
situation: str
class State(Input):
options: list[str]
outcomes: Annotated[list[tuple[int, int, str]], operator.add] # (attempt, option, outcome)
table: list[tuple[float, Assessment]]
attempt: int
feedback: str
class SimTask(TypedDict):
facts: str
option: str
index: int
attempt: int
async def option_writer(state: State) -> dict:
retry = f"\nThe previous options failed because: {state['feedback']}" if state.get("feedback") else ""
out = cast(Options, await llm.with_structured_output(Options).ainvoke(
"List three to five actions that could reach the goal, different in kind, each precise enough "
f"to simulate. Do not say which you prefer.\n{state['situation']}{retry}"))
return {"options": out.options, "attempt": state.get("attempt", -1) + 1}
def fan_out(state: State) -> list[Send]:
# one simulator per option, each in its own context
return [Send("simulator", {"facts": state["situation"], "option": o, "index": i,
"attempt": state["attempt"]})
for i, o in enumerate(state["options"])]
async def simulator(state: SimTask) -> dict:
# sees the facts and one option: not the other options, not the criteria
story = await llm.ainvoke(
f"Assume this action is taken today. Describe what happens over {HORIZON}: effects, reactions, "
"costs, what becomes harder. Mark every assumption. Do not judge it.\n"
f"Facts: {state['facts']}\nAction: {state['option']}")
return {"outcomes": [(state["attempt"], state["index"], story.text)]}
async def judge(state: State) -> dict:
outcomes = "\n\n".join(f"Option {i}: {state['options'][i]}\n{text}"
for a, i, text in sorted(state["outcomes"]) if a == state["attempt"])
verdict = cast(Judgement, await llm.with_structured_output(Judgement).ainvoke(
f"Score every outcome 1 to 10 on each criterion: {list(CRITERIA)}. Name any hard limit broken: "
f"{HARD_LIMITS}. Flag doubtful assumptions and the trade-off of each.\n\n{outcomes}"))
weights = list(CRITERIA.values())
table = [(sum(w * s for w, s in zip(weights, a.scores)), a) for a in verdict.assessments]
broken = "; ".join(f"option {a.option}: {a.broken_limit}" for _, a in table if a.broken_limit)
return {"table": sorted(table, key=lambda r: r[0], reverse=True), "feedback": broken}
def gate(state: State) -> str:
# the gate: a surviving option wins; otherwise one retry, then stop
survivors = [a for _, a in state["table"] if not a.broken_limit]
return END if survivors or state["attempt"] >= MAX_RETRIES else "option_writer"
graph = StateGraph(State, input_schema=Input)
graph.add_node("option_writer", option_writer)
graph.add_node("simulator", simulator)
graph.add_node("judge", judge)
graph.add_edge(START, "option_writer")
graph.add_conditional_edges("option_writer", fan_out)
graph.add_edge("simulator", "judge")
graph.add_conditional_edges("judge", gate)
app = graph.compile()
async def run(task: str):
final = await app.ainvoke({"situation": task})
survivors = [(s, a) for s, a in final["table"] if not a.broken_limit]
score, choice = (survivors or final["table"])[0]
# a decision, not an action: nothing is executed here
return {"decision": final["options"][choice.option], "score": score, "trade_off": choice.trade_off,
"flagged_least_bad": not survivors, "table": final["table"]}
Set your own criteria, weights and hard limits before the first run, and give the simulators real data where it exists.
import asyncio
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel
# fixed before any option exists, so they cannot be bent to fit a favourite
CRITERIA = {"cost": 0.3, "customer impact": 0.4, "reversibility": 0.3}
HARD_LIMITS = ["exceeds the approved budget", "breaks a legal or contractual obligation"]
HORIZON, MAX_RETRIES = "the next 90 days", 1
class Options(BaseModel):
options: list[str]
class Assessment(BaseModel):
option: int
scores: list[int] # 1 to 10, one per criterion, in the order given
broken_limit: str # empty when every hard limit holds
doubtful_assumption: str
trade_off: str
class Judgement(BaseModel):
assessments: list[Assessment]
AGENTS = {
"option-writer": AgentDefinition(
description="Lists distinct candidate actions for a goal.",
prompt="List three to five actions that could reach the goal, different in kind, each stated "
"precisely enough to simulate: who does what, when, at what cost. Do not say which you prefer.",
tools=[]),
"simulator": AgentDefinition(
description="Imagines the consequences of one action.",
prompt=f"Assume the action is taken today. Describe what happens over {HORIZON}: immediate "
"effects, reactions, costs, what becomes harder. Mark every assumption. Do not judge it.",
tools=[]),
"judge": AgentDefinition(
description="Scores simulated outcomes on fixed criteria and hard limits.",
prompt="Score every outcome from 1 to 10 on each weighted criterion. Eliminate any outcome that "
"breaks a hard limit and say which. Flag doubtful assumptions. Name each trade-off.",
tools=[]),
}
async def delegate(agent: str, brief: str, schema: type[BaseModel] | None = None) -> ResultMessage:
# one query per call: a new session, so no simulator sees another's story
options = ClaudeAgentOptions(
agents=AGENTS, allowed_tools=["Agent"],
output_format={"type": "json_schema", "schema": schema.model_json_schema()} if schema else None)
async for message in query(prompt=f"Delegate this to the {agent} agent.\n\n{brief}", options=options):
if isinstance(message, ResultMessage):
return message
raise RuntimeError(f"{agent} returned no result")
async def run(task: str):
feedback = ""
for attempt in range(1 + MAX_RETRIES): # the gate: one retry at most
retry = f"\nThe previous options failed because: {feedback}" if feedback else ""
listed = await delegate("option-writer", f"{task}{retry}", Options)
options = Options.model_validate(listed.structured_output).options
stories = await asyncio.gather(*(
delegate("simulator", f"Facts: {task}\nAction: {o}") for o in options))
outcomes = "\n\n".join(f"Option {i}: {o}\n{s.result}"
for i, (o, s) in enumerate(zip(options, stories)))
judged = await delegate(
"judge", f"Criteria in order: {list(CRITERIA)}\nHard limits: {HARD_LIMITS}\n\n{outcomes}",
Judgement)
rows = Judgement.model_validate(judged.structured_output).assessments
table = sorted(((sum(w * s for w, s in zip(CRITERIA.values(), a.scores)), a) for a in rows),
key=lambda r: r[0], reverse=True)
survivors = [r for r in table if not r[1].broken_limit]
if survivors or attempt == MAX_RETRIES:
score, choice = (survivors or table)[0]
# a decision, not an action: nothing is executed here
return {"decision": options[choice.option], "score": score, "trade_off": choice.trade_off,
"flagged_least_bad": not survivors, "table": table}
feedback = "; ".join(f"option {a.option}: {a.broken_limit}" for _, a in table)
Set your own criteria, weights and hard limits before the first run, and give the simulators real data where it exists.
import asyncio
from agents import Agent, Runner
from pydantic import BaseModel
# fixed before any option exists, so they cannot be bent to fit a favourite
CRITERIA = {"cost": 0.3, "customer impact": 0.4, "reversibility": 0.3}
HARD_LIMITS = ["exceeds the approved budget", "breaks a legal or contractual obligation"]
HORIZON, MAX_RETRIES = "the next 90 days", 1
class Options(BaseModel):
options: list[str]
class Assessment(BaseModel):
option: int
scores: list[int] # 1 to 10, one per criterion, in the order given
broken_limit: str # empty when every hard limit holds
doubtful_assumption: str
trade_off: str
class Judgement(BaseModel):
assessments: list[Assessment]
option_writer = Agent(
name="Option writer",
instructions="List three to five actions that could reach the goal, different in kind, each "
"stated precisely enough to simulate: who does what, when, at what cost. No preference.",
output_type=Options,
)
simulator = Agent(
name="Simulator",
instructions=f"Assume the action is taken today. Describe what happens over {HORIZON}: immediate "
"effects, reactions, costs, what becomes harder. Mark every assumption. Do not judge it.",
)
judge = Agent(
name="Judge",
instructions=f"Score every outcome from 1 to 10 on each criterion, in this order: {list(CRITERIA)}. "
f"Eliminate any outcome that breaks a hard limit: {HARD_LIMITS}, and say which. Flag doubtful "
"assumptions and name the trade-off of each option.",
output_type=Judgement,
)
async def run(task: str):
feedback = ""
for attempt in range(1 + MAX_RETRIES): # the gate: one retry at most
retry = f"\nThe previous options failed because: {feedback}" if feedback else ""
options = (await Runner.run(option_writer, f"{task}{retry}")).final_output_as(Options).options
# one run per option: a simulator sees the facts and its option, nothing else
stories = await asyncio.gather(*(
Runner.run(simulator, f"Facts: {task}\nAction: {o}") for o in options))
outcomes = "\n\n".join(f"Option {i}: {o}\n{s.final_output}"
for i, (o, s) in enumerate(zip(options, stories)))
rows = (await Runner.run(judge, outcomes)).final_output_as(Judgement).assessments
table = sorted(((sum(w * s for w, s in zip(CRITERIA.values(), a.scores)), a) for a in rows),
key=lambda r: r[0], reverse=True)
survivors = [r for r in table if not r[1].broken_limit]
if survivors or attempt == MAX_RETRIES:
score, choice = (survivors or table)[0]
# a decision, not an action: nothing is executed here
return {"decision": options[choice.option], "score": score, "trade_off": choice.trade_off,
"flagged_least_bad": not survivors, "table": table}
feedback = "; ".join(f"option {a.option}: {a.broken_limit}" for _, a in table)
Set your own criteria, weights and hard limits before the first run, and give the simulators real data where it exists.
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, Output } from 'ai';
import { z } from 'zod';
const model = anthropic('claude-sonnet-5-5');
// fixed before any option exists, so they cannot be bent to fit a favourite
const CRITERIA = { cost: 0.3, 'customer impact': 0.4, reversibility: 0.3 };
const HARD_LIMITS = ['exceeds the approved budget', 'breaks a legal or contractual obligation'];
const HORIZON = 'the next 90 days';
const MAX_RETRIES = 1;
const judgementSchema = z.object({
assessments: z.array(z.object({
option: z.number().int(),
scores: z.array(z.number().int().min(1).max(10)).describe('one per criterion, in the order given'),
brokenLimit: z.string().describe('empty when every hard limit holds'),
doubtfulAssumption: z.string(),
tradeOff: z.string(),
})),
});
export async function run(task: string) {
let feedback = '';
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) { // the gate: one retry at most
const { output: { options } } = await generateText({
model,
instructions:
'List three to five actions that could reach the goal, different in kind, each precise enough ' +
'to simulate: who does what, when, at what cost. Do not say which one you prefer.',
prompt: feedback ? `${task}\nThe previous options failed because: ${feedback}` : task,
output: Output.object({ schema: z.object({ options: z.array(z.string()) }) }),
});
// one call per option: a simulator sees the facts and its option, nothing else
const stories = await Promise.all(options.map(async (option) => (await generateText({
model,
instructions:
`Assume the action is taken today. Describe what happens over ${HORIZON}: effects, ` +
'reactions, costs, what becomes harder. Mark every assumption. Do not judge it.',
prompt: `Facts: ${task}\nAction: ${option}`,
})).text));
const { output: judgement } = await generateText({
model,
instructions:
`Score every outcome 1 to 10 on each criterion, in this order: ${Object.keys(CRITERIA).join(', ')}. ` +
`Name any hard limit broken: ${HARD_LIMITS.join('; ')}. Flag doubtful assumptions and each trade-off.`,
prompt: options.map((o, i) => `Option ${i}: ${o}\n${stories[i]}`).join('\n\n'),
output: Output.object({ schema: judgementSchema }),
});
const weights = Object.values(CRITERIA);
const table = judgement.assessments
.map((a) => ({ ...a, weighted: a.scores.reduce((sum, s, i) => sum + s * (weights[i] ?? 0), 0) }))
.sort((a, b) => b.weighted - a.weighted);
const survivors = table.filter((a) => !a.brokenLimit);
if (survivors.length > 0 || attempt === MAX_RETRIES) {
const choice = survivors[0] ?? table[0];
// a decision, not an action: nothing is executed here
return { decision: options[choice.option], score: choice.weighted, tradeOff: choice.tradeOff,
flaggedLeastBad: survivors.length === 0, table };
}
feedback = table.map((a) => `option ${a.option}: ${a.brokenLimit}`).join('; ');
}
}
Set your own criteria, weights and hard limits before the first run, and give the simulators real data where it exists.
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
- Criteria written after the simulations get bent to fit the favourite. Fix them first.
- Simulators that see each other's outputs drift toward the same story. Keep their contexts apart.
- An imagined outcome is not evidence. Where real data exists, give it to the simulators and say which facts were assumed.
Chain it
Its result can feed
- Dry Run conditional
Condition: Only when the chosen action is a concrete operation with a side effect on a real system and the no-option-passed flag is not set.
- Debate conditional
Condition: Only when A's decision is emitted as an answer, meaning a chosen option with the scores of the alternatives, rather than as a bare action to carry out.
- Constitutional Critique conditional
Condition: Only when the chosen action is itself a text, such as a drafted reply or announcement, emitted as an answer the constitution's rules can apply to.
- Human Approval Gate conditional
Condition: The link applies only when A's payload is an executable action, such as a price change, a reply to send or a migration to schedule, rather than a plain answer or recommendation.
- Textual Backpropagation conditional
Condition: The decision is an answer to improve, rather than an action to execute.