Examples

Alpha: @statelyai/agent 2.0 is in alpha. APIs can change between releases; pin an exact version. Feedback: github.com/statelyai/agent.

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.
• go-fish: hidden-information play with a checking-win → agent → human loop; the model chooses requests while the machine owns and enforces the rules.
• 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.
• described-workflow: a plain XState machine with zero invokes (prompts live in state descriptions and meta) run as an agent via runAgent's getRequests option, with the message log aggregated onto snapshot.messages.

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.