DOCSEARCHbyAlgolia
Submit Docs

XState Documentation

website·Indexed 29 days ago

https://stately-docs.vercel.app/

Documentation for XState v5 and the Stately editor, covering state machine modeling, the Actor model, and state machine logic. Includes guides on actions, context, event emitters, delayed and eventless transitions, and using the Stately editor for designing, simulating, and embedding machines.

Tokens
269.6K
Snippets
1.3K
Records
1.8K
Agent score
75%

What's inside XState

  1. Overview of Promise actor capabilities

    Promise actors represent an asynchronous task that resolves with an output or rejects with an error.

    Capabilities:

    • Send events: Can send events to other actors (e.g., those provided in input).
    • Input: Can receive input configuration upon creation.
    • Output: Produces an output value upon successful resolution.

    Limitations:

    • Cannot receive events.
    • Cannot spawn new actors.

  2. Overview of Stately Agent architecture

    Stately Agent extends XState to provide typed model requests, decisions, and host executors. It separates concerns into three layers:

    • XState: Manages states, events, actors, snapshots, persistence, inspection, timers, parallelism, and durable execution.
    • Stately Agent: Manages model request logic, decision constraints, executor binding, interactions, streaming, evaluation helpers, and agent-specific linting.
    • Host Framework: Manages storage, retries, queues, interruption recovery, and provider SDK behavior.

    The core library has no runtime dependency on the AI SDK.

  3. Overview of @statelyai/agent preset machines

    The @statelyai/agent/machines package provides factories for common agent shapes. These factories are compositions over setupAgent(...).createMachine(...) and produce standard XState machines. They separate the machine logic from the executors; the host must pass executors to runAgent at runtime. All presets are designed to be readable and can be copied into a project for custom modification (ejection).
    import { tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { runAgent } from "@statelyai/agent";
import { createToolLoopMachine } from "@statelyai/agent/machines";
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";

const models = { quick: openai("gpt-5.4-mini") };

const calculate = tool({
  description: "Evaluate an arithmetic expression.",
  inputSchema: z.object({ expression: z.string() }),
  execute: async ({ expression }) => Number(expression),
});

const machine = createToolLoopMachine({
  model: "quick",
  instructions: "Answer using the tools.",
  tools: { calculate },
  maxSteps: 5,
});

const result = await runAgent(machine, {
  input: { prompt: "What is 42 times 17?" },
  executors: createAiSdkExecutors({ models }),
});

  4. Overview of @statelyai/graph layout engines

    @statelyai/graph does not implement its own layout algorithms. Instead, it provides thin adapters over external engines. These adapters take a plain-JSON Graph as input and return a positioned VisualGraph. Depending on the engine, the return type may be a VisualGraph, a Promise<VisualGraph> (async), or a Generator (iterative).

  5. Overview of Agent Machines

    An agent machine is a typed XState state machine that defines an agent's capabilities, including states, legal transitions, model calls, and events. Crucially, the agent machine does not call models directly; instead, the host executes model calls on its behalf.

    Authoring an agent machine follows three steps:

    1. Declare a models registry and schema fields for context, input, output, and events.
    2. Pass these to setupAgent along with requests and actor sources.
    3. Build the machine using agentSetup.createMachine.

  6. Overview of XState Callback Actors

    Callback actors are actors whose logic is defined by a function. They are primarily used for integrating with external APIs or event listeners. They can receive events from other actors and send events back to their parent actor.

    Capabilities:

    • Receive events: Can listen for events using the receive(event => {...}) function.
    • Send events: Can send events to the parent via sendBack(event) or to other referenced actors.
    • Input: Supports receiving an input object during creation.
    • Limitations: Callback actors cannot spawn new actors and do not produce a final output value; they remain active until stopped or an error occurs.

  7. Overview of @statelyai/agent for AI agents

    @statelyai/agent allows developers to author AI agents as typed XState state machines. In this architecture, the state machine defines the legal transitions and logic (what work is allowed), while the host environment handles the execution of model calls using a chosen provider or SDK. Note that Version 2.0 is currently in alpha; because APIs may change between releases, it is recommended to pin the package to an exact version.

  8. Overview of Stately Studio

    Stately Studio is a suite of tools for building application logic using XState. It provides a visual editor for modeling state machines and statecharts without writing code, developer tools for XState, and integration options via a VS Code extension or by exporting code from the Studio into a codebase.

  9. Overview of Stately Studio Team Roles

    Stately Studio uses four roles to manage permissions within a team. Roles are assigned by Owners or Admins during the invitation process.

    CapabilityOwnerAdminEditorViewer
    View team projects and machines✅✅✅✅
    View other team members✅✅✅✅
    Export team machines✅✅✅✅
    Fork team projects and machines✅✅✅🚫
    Edit existing team projects✅✅✅🚫
    Create team projects✅✅✅🚫
    Lock team machines✅✅✅🚫
    Reassign Admin, Editor, and Viewer roles✅✅🚫🚫
    Invite new team members✅✅🚫🚫
    Change project visibility✅✅🚫🚫
    Edit the team name✅✅🚫🚫
    Delete the team✅🚫🚫🚫

  11. Overview of Stately Studio REST API

    The Stately Studio REST API allows developers to automate workflows and integrate state machines into external projects. Key capabilities include exporting machines into various formats (TypeScript, JavaScript, JSON, etc.), fetching machine and project information, and retrieving specific versions of a machine. Note that API access is a premium feature available on Pro, Team, and Enterprise plans.

  12. Organize and add new XState documentation pages

    Documentation should be located adjacent to the package or concept it describes. XState guides and reference pages belong in the root docs/ directory, while framework-specific or package-specific pages should be placed in that specific package's docs/ directory. Every new page must be registered in the nearest meta.json file to be included in the site structure.