Core Components

This section establishes the technical foundation to building automations with Loopstack you understanding how AI workflows are executed.

Overview

Loopstack automations are build using two essential concepts:

1. TypeScript - NestJS services for defining workflow capabilities, tools, and document classes
2. YAML Configs - Configuration files to define specific workflow behaviour and UI settings.

TypeScript Services

There are different services, each with specific functionality

1. Workspaces - Organizational containers that group related automations and data
2. Workflows - State machines that define business processes, call tools and create documents
3. Tools - Functional units that perform specific tasks
4. Documents - Structured data objects that store and display information

YAML Configurations

1. workflows - defining the flow / behaviour of the workflow or agent
2. documents - defining UI specific configuration for displaying documents in the studio frontend

Workspaces

Workspaces contain workflows that can be directly executed and serve as the top-level organizational unit.

Purpose: Provide organizational structure for your automations.

• Create logical groupings of related automations
• Control access and permissions at a high level

@Workspace({
  config: {
    title: 'Examples Workspace'
  },
})
export class ExampleWorkspace  {
  @InjectWorkflow() chatWorkflow: ChatWorkflow;
  @InjectWorkflow() meetingNotes: MeetingNotesWorkflow;
}

Workflows

Workflows are automation entities that can be executed. They use tools to perform custom operations. Workflows control the flow of a business process and manage its state.

Purpose: Define specific business processes as state machines with transitions between states.

• Model processes with states (places) and transitions
• Execute tools to perform actions
• Handle errors and alternative paths
• Manage the flow of data through the process
• Maintain a custom state
• Define Input that can be accessed by the workflow
• Define Output the workflow returns after successful execution

@Workflow({
  configFile: './config.yaml',
})
export class ClassificationWorkflow {
 
  @Input({
    schema: z.object({
      message: z.string(),
    })
  })
  args: { message: string }
 
  @InjectDocument() classificationDocument: ClassificationDocument;
  @InjectTool() aiGenerateDocument: AiGenerateDocument;
  @InjectTool() notifyTool: NotifyTool;
 
}

transitions:
  - id: step1
    from: start
    to: message_classified
    call:
      - tool: AiGenerateDocument
        args:
          response:
            document: classificationDocument
          prompt: |
            Classify the following message:
            {{ args.message }}
        assign:
          classification: ${{ response.data.content }}
 
      - id: notify
        from: message_classified
        to: end
        call:
          - tool: notifyTool
            args:
              message: ${{ args.message }}
              priority: ${{ state.classification.priority }}

Execution Process:

1. Workflow always starts in start state
2. Finds transition with matching from state
3. Executes specified tools with provided arguments
4. Exports results to variables if specified
5. Moves to to state
6. Repeats until reaching terminal end state

Tools

Tools are called by workflow transitions of from other tools. They execute custom business logic, create or modify documents or interact with outside systems.

Purpose: Perform specific actions or operations within workflows.

• Execute defined operations (API calls, data processing, etc.)
• Accept input arguments
• Create documents displayed in the Loopstack Studio
• Call other tools

@Tool()
export class NotifyTool implements ToolInterface {
  @Input()
    args: {
    message: string;
    priority: 'urgent' | 'high' | 'medium' | 'low'
  }
 
  execute(): Promise<ToolResult> {
 
    // ... custom implementation to send message to a recipient
 
    return {
      data: `Message sent (priority: ${this.args.priority})`,
    };
  }
}

Documents

Documents are created and used by workflows and tools. They can store data persistently and provide configuration for interactive forms for user input in the Loopstack Studio.

Purpose: Store, display, and collect data throughout the automation process.

• Define data schemas for validation
• Provide UI components for user interaction
• Store information between workflow steps
• Serve as inputs and outputs for tools

@Document()
export class ClassificationDocument {
 
  @Input({
    schema: z.object({
      priority: z.enum(['urgent', 'high', 'medium', 'low']),
    })
  })
  content: {
    priority: 'urgent' | 'high' | 'medium' | 'low'
  }
 
}

ui:
  form:
    properties:
      priority:
        title: Priority
        widget: select
  buttons:
    - transition: confirm
      label: "Update Priority"

How Components Work Together

Let’s examine how these components interact in a typical automation:

1. A workspace provides organizational structure
2. The workflows gets executed by a user or internal process
3. Each workflow consists of transitions between states
4. Transitions call tools to perform actions
5. Tools create or modify documents to store and display data

Example Flow

State Persistence

Workflow state is automatically persisted, enabling:

• Execution resume after interruptions
• Human in the loop interaction
• Audit trails of workflow progress
• Historical execution analysis

All other Blocks are not persistent and will be re-executed on every automation run.