Skip to main content
The State interface represents a state in the workflow’s state machine. It defines the behavior, transitions, and actions associated with a particular state in the workflow. The State interface in Solmyr’s workflow system is based on XState’s state node configuration. It provides a streamlined subset of XState’s features, optimized for AI-driven workflows. Developers familiar with XState will find many similarities, though some advanced XState features may not be directly exposed in our API.

​
Structure

export interface State {
    description: string;
    on?: Record<string, Transition>;
    always?: Array<Transition>;
    invoke?: {
        src: "callTool";
        input: {
            name: string;
        };
        onDone: Transition;
        onError: Transition;
    };
    states?: Record<string, State>;
    meta?: {
        ai: boolean;
    };
    initial?: string;
}

​
Properties

​
description
string
required
Provides guidance for the AI on how to handle this state. This description is used by the AI to understand the context and make decisions.
​
on
Record<string, Transition>
Defines transitions to other states based on events. Keys are event types, values are Transition objects.
​
always
Array<Transition>
Defines immediate transitions that are checked as soon as the state is entered. Useful for conditional branching without waiting for an event.
​
invoke
object
Defines an action to be executed when entering this state. Typically used to invoke tools or perform side effects.
  • src: Always “callTool” for invoking a tool.
  • input.name: The name of the tool to be called.
  • onDone: Transition to be taken when the tool execution completes successfully.
  • onError: Transition to be taken if the tool execution fails.
​
states
Record<string, State>
Defines nested states for hierarchical state machines. Follows the same structure as the top-level states property.
​
meta
object
Controls AI interaction within this state.
  • ai: If true, the workflow will pause here and allow the AI to respond or decide on the next event. If false or not present, the state machine will proceed without AI intervention.
​
initial
string
Indicates the initial state for nested state machines. Only applicable if the states property is present.

​
Usage Example

const checkoutState: State = {
    description: "Process the user's checkout request",
    on: {
        "userConfirm": {
            target: "processing",
            description: "User confirmed the order"
        },
        "userCancel": {
            target: "cancelled",
            description: "User cancelled the order"
        }
    },
    invoke: {
        src: "callTool",
        input: {
            name: "validateCart"
        },
        onDone: {
            target: "confirmOrder",
            description: "Cart validation successful"
        },
        onError: {
            target: "error",
            description: "Cart validation failed"
        }
    },
    meta: {
        ai: true
    }
};
This example shows a checkout state that waits for user confirmation, invokes a cart validation tool, and allows AI intervention for handling the checkout process.