event-steps

Event Steps Guide

Event Steps are used to handle asynchronous events. These steps cannot be invoked by a client or user. In order to ultimately trigger an Event Step, you need to connect it to an API Step or a CRON Step.

Examples of event steps are:

• LLM Calls
• Processing big files, like images, videos, audio, etc.
• Sending emails

Other applicable examples are tasks that are likely to fail, examples:

• Webhook call to external systems

Creating Event Steps

Steps need to be created in the steps folder, it can be in subfolders.

• Steps in TS and JS should end with .step.ts and .step.js respectively.
• Steps in Python should end with _step.py.

Definition

Defining an Event Step is done by two elements. Configuration and Handler.

Schema Definition

• TypeScript/JavaScript: Motia uses Zod schemas for automatic validation of input data
• Python: Motia uses JSON Schema format. You can optionally use Pydantic models to generate JSON Schemas and handle manual validation in your handlers

Configuration

TypeScript/JavaScript: You need to export a config constant via export const config that is a EventConfig type.

Python: You need to define a config dictionary with the same properties as the TypeScript EventConfig.

export type ZodInput = ZodObject<any> | ZodArray<any>
export type StepSchemaInput = ZodInput | JsonSchema

export type Emit = string | { 
  /**
   * The topic name to emit to.
   */
  topic: string;

  /**
   * Optional label for the emission, could be used for documentation or UI.
   */
  label?: string;

  /**
   * This is purely for documentation purposes, 
   * it doesn't affect the execution of the step.
   * 
   * In Workbench, it will render differently based on this value.
   */
  conditional?: boolean;
}

export type EventConfig = {
  /**
   * Should always be event
   */
  type: 'event'

  /**
   * A unique name for this event step, used internally and for linking handlers.
   */
  name: string

  /**
   * Optional human-readable description.
   */
  description?: string

  /**
   * An array of topic names this step listens to.
   */
  subscribes: string[]

  /**
   * An array of topics this step can emit events to.
   */
  emits: Emit[]

  /**
   * Optional: Topics that are virtually emitted, perhaps for documentation or lineage, but not strictly required for execution.
   */
  virtualEmits?: Emit[]

  /**
   * Optional: Virtually subscribed topics for documentation/lineage purposes.
   */
  virtualSubscribes?: string[]

  /**
   * Schema for input data. Accepts either:
   * - Zod schema (ZodObject or ZodArray)
   * - JSON Schema object
   * 
   * This is used by Motia to create the correct types for whoever emits the event 
   * to this step.
   * 
   * Avoid adding too much data to the input schema, only add the data that 
   * is necessary for the Event Step to process. If the data is too big it's 
   * recommended to store it in the state and fetch it from the state on the 
   * Event Step handler.
   */
  input?: StepSchemaInput

  /**
   * Optional: An array of flow names this step belongs to.
   */
  flows?: string[]

  /**
   * Files to include in the step bundle.
   * Needs to be relative to the step file.
   */
  includeFiles?: string[]

  /**
   * Optional: Infrastructure configuration for handler and queue settings.
   */
  infrastructure?: Partial<InfrastructureConfig>
}