Examples

Running the examples

The examples live in the repo under examples/, one flat directory per example with an index.ts entrypoint. Clone the repo, install dependencies, and run any example directly with tsx:

OPENAI_API_KEY=... npx tsx examples/<name>/index.ts

Every example is dual-mode: run it directly with a real model as above, while its tests use injected mocks. Most examples that call a real model expect a provider key in the environment, for example OPENAI_API_KEY. Each file notes what it needs at the top.

Start here

These five cover the core ideas: text requests, decisions, messages, and JSON authoring.

• twenty-questions: a decision loop where the model picks one legal event (ASK or GUESS) each turn, with guard-enforced legality, machine-held score, play-again reset, and machine-owned user prompts.
• joke: a minimal streaming text workflow.
• email-drafter: reusable text logic, parts-based messages, and schema-typed state and transition meta.
• game-agent: allowedEvents narrowed as a function of input, gating moves by HP.
• json-agent: a full workflow (decision, text request, idle human step) authored as a real .json file and run with runAgent. See Machines as data.

Human in the loop and persistence

These show the idle-first pause for human input and resuming a run by snapshot. See Human in the loop.

• human-in-the-loop: a machine that settles idle to wait for a human, then resumes with the human's event, persisting a snapshot between iterations and resuming in a later process.
• long-running-onboarding: a multi-day onboarding coordinator with durable typed state, two idle dormancy gates, delegated IT provisioning, and JSON snapshot resume.
• file-snapshot-store: a file-backed snapshot store for durable threads across processes.

Host adapters and the step path

These implement the executor contract against different SDKs and runtimes, and use the lower-level step path for durable checkpointing. See Hosts and Steps.

• ai-sdk-host: running with Vercel AI SDK host actors.
• ai-sdk-game-host: a Vercel AI SDK step runner that checkpoints every model call.
• openai-sdk-host: the same executor contract against the raw openai package (Chat Completions), no Vercel AI SDK in between.
• anthropic-sdk-host: the same contract against the raw @anthropic-ai/sdk package (Messages API).
• cloudflare-workers-ai-host: a step runner against Cloudflare Workers AI's binding.
• cloudflare-agent-host: a Cloudflare Agents host persisting snapshots in Durable Object state.

Sub-agents and composition

These compose agent machines as sub-agents or child actors. See Multi-agent.

• subflows: a nested child machine keeping its own executor binding.
• ai-sdk-sub-agents: Vercel AI SDK ToolLoopAgent workers exposed as host-owned tools.
• debate-sub-agents: a facilitator scheduling two event-based debater sub-agents.
• long-running-onboarding: a coordinator invoking typed IT provisioning between two event-driven waits.
• supervisor: a routing request whose structured output hands off to a format-specific worker.
• swarm-handoff: a persistent multi-agent network handing off between typed child actors across turns.

Multi-step agent patterns

Common agent workflows expressed as explicit XState machines.

• react-agent: ReAct as an explicit loop — one reason-or-act request per iteration (discriminated union: call a tool or answer), typed tool actors execute, a step-budget guard breaks the loop with a best-effort answer.
• tool-calling: the model selects a tool (structured output), typed tool actors execute, progress reported via transitions.
• rag: retrieve (typed plain actor over a sample corpus) then a grounded answer, with conversational memory in context.
• plan-and-execute: a planner request produces structured output, execution states iterate the plan (keeps the ReWOO evidence-map idea).
• sql-agent: query generation, DB execution, and answer synthesis as separate typed states.
• triage: structured-output support ticket triage.
• parallel-streams: fan-out over parallel worker streams relayed through a side channel.
• sse-transport: relaying provider stream chunks over an SSE transport.

AI SDK pattern set

The Vercel AI SDK agent patterns, each rebuilt as an explicit XState machine.

• ai-sdk-marketing-chain: a sequential chain.
• ai-sdk-routing: routing.
• ai-sdk-parallel-review: parallel review.
• ai-sdk-orchestrator-worker: an orchestrator-worker fan-out.
• ai-sdk-evaluator-optimizer: an evaluator-optimizer loop.

Note: The full example index, including framework-comparison notes, lives in examples/README.md.