Workflow Definition (JSON Schema)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/workflow/schema/workflowSchema.ts
• packages/shared/src/contracts/workflow.ts
• apps/web/src/lib/workflow_setup_examples/advanced-examples/meta-workflow.json
• apps/web/src/features/react-flow-visualization/store/app-store.ts
• packages/core/src/workflow/Workflow.ts
• packages/core/src/utils/validation/README.md
• packages/core/src/workflow/actions/generate/formalizeWorkflow.ts

A workflow in the lucky framework is defined by a JSON object that conforms to the WorkflowConfig schema. This configuration acts as the blueprint for a Directed Acyclic Graph (DAG) where each node represents an AI agent with specific instructions, tools, and connections. This JSON-based definition is fundamental to the system, as it allows workflows to be programmatically generated, manipulated, visualized, validated, and evolved.

The entire system, from the core execution engine to the web-based visual editor, relies on this schema. The Workflow class consumes this configuration to instantiate and run the agent network, while the UI uses it to render the graph and allow for visual editing. The evolutionary capabilities of the project operate directly on these JSON structures, treating them as genomes for optimization.

Sources: packages/core/README.md, packages/core/src/workflow/Workflow.ts:18-21, apps/web/src/features/react-flow-visualization/store/app-store.ts:60-67

Core Schema Structure

The root of the workflow definition is the WorkflowConfig object. It contains the list of all nodes, the ID of the entry node, and optional configurations for memory and UI layout.

The relationship between the main configuration and its nodes is illustrated below.

This diagram shows that a WorkflowConfig contains multiple WorkflowNodeConfig objects.

Sources: packages/shared/src/contracts/workflow.ts:4-36, packages/core/src/workflow/schema/workflowSchema.ts:10-53

WorkflowConfig Properties

The top-level properties of the workflow JSON object are defined as follows:

Property	Type	Description
entryNodeId	string	The nodeId of the first node to be executed in the workflow.
nodes	WorkflowNodeConfig[]	An array of node objects that constitute the graph.
memory	object	Optional workflow-level persistent memory, a key-value store.
ui	object	Optional UI-specific configuration, primarily for storing layout information for the visual editor.
inputSchema	object	An optional JSON schema defining the expected structure of the workflow's input.
outputSchema	object	An optional JSON schema defining the expected structure of the workflow's final output.

Sources: packages/shared/src/contracts/workflow.ts:29-36, apps/web/src/features/react-flow-visualization/store/app-store.ts:684-695, packages/shared/src/contracts/invoke.examples.ts:251-294

WorkflowNodeConfig Properties

Each object in the nodes array defines an agent in the workflow. These are the core components of the graph.

Property	Type	Description
nodeId	string	A unique identifier for the node within the workflow.
description	string	A human-readable description of the node's purpose.
systemPrompt	string	The instructions given to the AI model for this node's execution.
modelName	string	The identifier for the AI model to be used (e.g., gpt-4o-mini, or an abstract tier like medium).
codeTools	string[]	An array of names of available internal TypeScript tools.
mcpTools	string[]	An array of names of available external tools via the Model Context Protocol (MCP).
handOffs	string[]	An array of nodeIds to which this node can pass control. Use "end" to terminate a path.
memory	object	Optional node-specific persistent memory, a key-value store.

Sources: packages/shared/src/contracts/workflow.ts:4-27, packages/core/src/utils/validation/README.md:104-115

UI Configuration

The optional ui object is used by the web interface to store visual layout information, ensuring that the graph's appearance is preserved between sessions.

The ui.layout.nodes is an array of objects, each containing:

Property	Type	Description
nodeId	string	The ID of the node being positioned.
x	number	The x-coordinate of the node on the canvas.
y	number	The y-coordinate of the node on the canvas.

This data is generated when a workflow is exported from the visual editor.

Sources: apps/web/src/features/react-flow-visualization/store/app-store.ts:684-695

Schema Validation and Handling

The system uses Zod schemas for robust, end-to-end type safety and runtime validation.

Zod Schema Definitions

The core schemas are defined in workflowSchema.ts.

• WorkflowNodeConfigSchema: Validates individual node objects.
• WorkflowConfigSchema: Validates the entire workflow configuration, ensuring structural integrity.
• WorkflowConfigSchemaEasy: A more lenient schema used during AI-driven generation, which allows for abstract model names (e.g., "low", "medium", "high") before they are resolved to specific model identifiers.

Sources: packages/core/src/workflow/schema/workflowSchema.ts:10-85

Model Name Resolution

During workflow generation or formalization, an abstract model tier like "medium" can be used. The system includes logic to resolve these abstract tiers into concrete model names based on user preferences or system defaults.

• handleWorkflowCompletionTierStrategy: Resolves model tiers (low, medium, high) to specific models.
• handleWorkflowCompletionUserModelsStrategy: Resolves model tiers based on a user-provided list of available models.

This process is part of the formalizeWorkflow action, which takes a natural language prompt and generates a valid WorkflowConfig.

Sources: packages/core/src/workflow/schema/workflowSchema.ts:87-133, packages/core/src/workflow/actions/generate/formalizeWorkflow.ts:110-116

Workflow as a Graph (DAG)

The nodes and handOffs properties define the structure of the Directed Acyclic Graph (DAG).

Entry and Exit Points

• Entry: The entryNodeId property in WorkflowConfig specifies the starting point of the graph.
• Exit: A node execution path is terminated when it hands off to the special target "end". A workflow can have multiple terminal nodes.

Sources: packages/shared/src/contracts/workflow.ts:18,30, packages/core/src/utils/validation/README.md:154-178

Branching and Merging

The graph structure supports complex flows:

• Branching (One-to-Many): A node can list multiple nodeIds in its handOffs array, creating parallel execution paths.
• Merging (Many-to-One): Multiple nodes can specify the same nodeId in their handOffs, converging different paths into a single node.

The diagram below illustrates a workflow with both branching and merging.

This diagram shows Node A branching to B and C, which then merge back into D.

Sources: packages/core/src/prompts/workflowAnalysisPrompts.ts:3-7

Example: meta-workflow.json

This example demonstrates a sequential pipeline for analyzing and improving another workflow.

JSON Configuration

{
  "entryNodeId": "analysis-node",
  "nodes": [
    {
      "nodeId": "analysis-node",
      "description": "Analyze the workflow execution data and identify key areas for review",
      "modelName": "openrouter#google/gemini-2.5-flash-lite",
      "systemPrompt": "You are an expert workflow analyst...",
      "handOffs": ["evaluation-node"],
      "memory": {}
    },
    {
      "nodeId": "evaluation-node",
      "description": "Evaluate the workflow performance against best practices...",
      "modelName": "openrouter#google/gemini-2.5-flash-lite",
      "systemPrompt": "You are a workflow performance evaluator...",
      "handOffs": ["recommendation-node"],
      "memory": {}
    },
    {
      "nodeId": "recommendation-node",
      "description": "Generate specific, actionable recommendations for workflow improvement",
      "modelName": "openrouter#google/gemini-2.5-flash-lite",
      "systemPrompt": "You are a workflow optimization consultant...",
      "handOffs": ["synthesis-node"],
      "memory": {}
    },
    {
      "nodeId": "synthesis-node",
      "description": "Create actionable improvement feedback without summarizing past analysis",
      "modelName": "openrouter#google/gemini-2.5-flash-lite",
      "systemPrompt": "You are a workflow improvement advisor...",
      "handOffs": ["end"],
      "memory": {}
    }
  ]
}

Sources: apps/web/src/lib/workflow_setup_examples/advanced-examples/meta-workflow.json

Visualized Flow

The configuration above creates a simple, four-step sequential workflow.

This diagram visualizes the linear flow of the meta-workflow, where the output of one node becomes the input for the next, culminating in a final result before ending.

Sources: apps/web/src/lib/workflow_setup_examples/advanced-examples/meta-workflow.json

Conclusion

The JSON-based WorkflowConfig is the cornerstone of the lucky project's architecture. It provides a flexible, machine-readable, and evolvable format for defining complex multi-agent systems. By standardizing the workflow definition in a declarative JSON structure, the framework enables powerful features like autonomous optimization, runtime validation, and intuitive visualization, abstracting away the complexities of agent coordination and allowing developers to focus on high-level logic.

Sources: packages/core/README.md, README.md:23-25