Agentic Architectures

Catalogue / Sampling & Search

Mental Simulation

Imagine each option's outcome, score it, then commit to one

Shape
simulation
Model calls
1 + N simulations + 1 scoring (N = 3 to 5)
Latency
medium
Complexity
medium

Also known as Simulate-before-acting, Look-ahead

1

How 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.
2

When 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
3

How 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.

none passes, 1retry leftwinner found orretry spentSituation: The goal and the current facts, or a set of options already drawn up by an earlier stage.SituationOption writer: Lists three to five genuinely different actions, each stated precisely enough to simulate.Option writerSimulators: One per option. Imagines what happens next, step by step, including side effects and reactions.SimulatorsJudge: Scores every imagined outcome on the same weighted criteria and checks the hard limits.JudgeClear winner?: Picks the top score among options that pass every hard limit, and counts the retries.Clear winner?Decision: The chosen action with its simulated outcome, its scores and the trade-off accepted.Decision
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

Entry
situation
TaskOptions

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.

Exit
decision
Proposed actionAnswer

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.

4

What 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.

Framework-agnostic prompt
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

LangGraph, python, package langgraph
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.

Claude Agent SDK, python, package claude-agent-sdk
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.

OpenAI Agents SDK, python, package openai-agents
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.

Vercel AI SDK, typescript, package ai
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