Simulation

When to useCopy Anchor Link

• The question is how something changes over time: savings growth, a loan payoff, a support backlog, stock levels.
• The user wants to try what-ifs, such as a bigger deposit, more staff or an extra payment.

When not to useCopy Anchor Link

• The answer is a single number. Use a Calculator.
• The figures already exist as data. Show them in a Chart instead of simulating them.
• You're unsure how the system behaves from one step to the next. Explain the method in text.

How the model runsCopy Anchor Link

The agent declares inputs (each one gets a slider), state (values carried from step to step) and one step formula per state that gives its next value:

{
  "inputs": [{ "id": "deposit", "label": "Monthly deposit", "min": 0, "max": 2000, "step": 50, "default": 500, "unit": "currency" }],
  "state": [{ "id": "balance", "label": "Balance", "initial": "initial" }],
  "step": [{ "id": "balance", "formula": "balance * (1 + rate / 100 / 12) + deposit" }],
  "steps": 120,
  "stepUnit": "month"
}

Formulas use the same safe language as the Calculator: operators + - * / % ^ and comparisons, plus min, max, round, floor, ceil, abs, sqrt, pow, clamp and if. There's no eval, so a model can't run code through a formula. The schema rejects formulas that don't parse or that use names the model doesn't declare. Runs are capped at 1,000 steps.

If a step produces a value that isn't a finite number (for example, a division by zero), the run stops there and the component says "The model produced an invalid value at month 34" instead of drawing a wrong line.

InteractionCopy Anchor Link

• Answer first: the first milestone (or where the run ends, for stopWhen) is shown large above the chart, e.g. "Backlog cleared: Day 6". Without milestones or stopWhen, the first plotted value at the cursor is the headline. Further milestones are listed under it.
• Inputs: below the chart, each with a slider, a number field and a reset button. Every change re-runs the model straight away.
• Baseline: once the user changes an input, the run with the default inputs stays on the chart as a dashed line, and the answer shows the baseline's value on one quiet line, e.g. "Baseline: not reached". At the last step, the values under the chart show their change against it. Set baseline: false to turn it off.
• Scrubber: Play moves a cursor across the run, and the step slider inspects any step. The values under the chart follow the cursor. With reduced motion, Play jumps to the last step.
• Milestones: the first step each one holds is marked on the chart and stated above it.
• description is read to screen readers only. Put assumptions the user must see in the reply.

How the agent should use itCopy Anchor Link

• Start from what the user said. Every input defaults to their numbers, and the default run is the baseline.
• Give each state exactly one step formula, and use only declared IDs and t.
• Use stopWhen for runs that end, like a paid-off loan, and milestones for moments worth marking.
• Plot one to three series that share a unit.
• Present results as estimates from the stated assumptions, not advice.
• Set apply: false when the simulation is the whole answer. Otherwise the "Use these numbers" button (or your applyLabel) sends the chosen inputs back.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/simulation.json

This adds the component, its schema and simulation-engine.ts, which holds the formula language and the model runner.

UsageCopy Anchor Link

import { tool } from "ai"
import { simulationTool } from "@/components/genui/simulation.schema"

const tools = {
  [simulationTool.name]: tool({
    description: simulationTool.description,
    inputSchema: simulationTool.inputSchema,
  }),
}

import { Simulation } from "@/components/genui/simulation"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-run_simulation") return null

  return (
    <Simulation
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "run_simulation",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

With apply: false, the simulation is the whole answer, so give the tool an execute that returns immediately. Otherwise the agent receives the inputs and the final value of every state and output:

{
  action: "apply",
  inputs: { agents: 8, incoming: 180 },
  summary: { backlog: 0, queueDays: 0 },
}

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "run_simulation", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

When a conversation is reloaded, pass the stored result back as result. The component restores the inputs that were sent, read-only, and never calls onResult again. The chart and scrubber stay usable. With the AI SDK, that's the tool call's output:

<Simulation
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

Input

State and Output

Host props: status (streaming, ready, applied), onResult, result and className.

SourceCopy Anchor Link