AgentScript State Examples

Simple State

AgentScript

function orderStateMachine(order: Order): Order
  goal: "Manages state transitions for an order from pending to delivery"
  machine:
    state: pending -> confirmed on confirmOrder
    state: confirmed -> shipped on shipOrder
    state: shipped -> delivered on deliverOrder

  errors:
    InvalidTransition: "Cannot transition from the current state"

  tests:
    success:
      { status: "pending" } -> { status: "confirmed" } after confirmOrder
      { status: "confirmed" } -> { status: "shipped" }  after shipOrder
    smoke:
      // Attempting to confirm when already shipped
      { status: "shipped" } -> error: InvalidTransition

  return:
    match (order.status) {
      case "pending" -> confirmOrder(order)
      case "confirmed" -> shipOrder(order)
      case "shipped" -> deliverOrder(order)
      default -> throw InvalidTransition
    }

TypeScript (XState)

import { createMachine, interpret, assign } from 'xstate';

interface Order {
  status: 'pending' | 'confirmed' | 'shipped' | 'delivered';
}

// We create a machine describing order transitions
const orderMachine = createMachine<Order>({
  id: 'order',
  initial: 'pending',
  context: {
    status: 'pending',
  },
  states: {
    pending: {
      on: {
        CONFIRM_ORDER: {
          target: 'confirmed',
          actions: assign({
            status: (_context) => 'confirmed',
          }),
        },
      },
    },
    confirmed: {
      on: {
        SHIP_ORDER: {
          target: 'shipped',
          actions: assign({
            status: (_context) => 'shipped',
          }),
        },
      },
    },
    shipped: {
      on: {
        DELIVER_ORDER: {
          target: 'delivered',
          actions: assign({
            status: (_context) => 'delivered',
          }),
        },
      },
    },
    delivered: {
      type: 'final',
    },
  },
});

// Example usage
const service = interpret(orderMachine).onTransition((state) => {
  console.log(`Order is now in the "${state.value}" state`);
});

service.start();                 // Starts at "pending"
service.send('CONFIRM_ORDER');   // Moves to "confirmed"
service.send('SHIP_ORDER');      // Moves to "shipped"
service.send('DELIVER_ORDER');   // Moves to "delivered"

TypeScript (Plain)

interface Order {
  status: 'pending' | 'confirmed' | 'shipped' | 'delivered';
}

function confirmOrder(order: Order): Order {
  if (order.status !== 'pending') {
    throw new Error('InvalidTransition: Cannot confirm unless pending.');
  }
  return { ...order, status: 'confirmed' };
}

function shipOrder(order: Order): Order {
  if (order.status !== 'confirmed') {
    throw new Error('InvalidTransition: Cannot ship unless confirmed.');
  }
  return { ...order, status: 'shipped' };
}

function deliverOrder(order: Order): Order {
  if (order.status !== 'shipped') {
    throw new Error('InvalidTransition: Cannot deliver unless shipped.');
  }
  return { ...order, status: 'delivered' };
}

export function orderStateMachine(order: Order, action: 'confirm' | 'ship' | 'deliver'): Order {
  switch (action) {
    case 'confirm':
      return confirmOrder(order);
    case 'ship':
      return shipOrder(order);
    case 'deliver':
      return deliverOrder(order);
    default:
      throw new Error('InvalidTransition: Unrecognized action.');
  }
}

// Usage Example
let myOrder: Order = { status: 'pending' };
myOrder = orderStateMachine(myOrder, 'confirm');  // -> { status: 'confirmed' }
myOrder = orderStateMachine(myOrder, 'ship');     // -> { status: 'shipped' }
myOrder = orderStateMachine(myOrder, 'deliver');  // -> { status: 'delivered' }