Skip to content
Color theme

Advanced Workflows Examples

Advanced workflow pattern examples for the Loopstack automation framework.

Deep-dive examples for framework patterns authors reach for less often but want available when they need them. Pick the example that matches your problem.

Use in Your App

Copy this directory into your app, then install what it imports:

Terminal window
npm install @loopstack/claude @loopstack/common @loopstack/core @loopstack/llm-provider

Register the module:

import { Module } from '@nestjs/common';
import { LoopstackModule } from '@loopstack/loopstack-module';
import { AdvancedWorkflowsExamplesModule } from './advanced-workflows/advanced-workflows-examples.module';
@Module({
imports: [LoopstackModule.forRoot(), AdvancedWorkflowsExamplesModule],
})
export class AppModule {}

Required app-module configuration

Examples that exercise LLM tools (LlmGenerateTextTool, LlmGenerateObjectTool — used by Sub-Workflow, Fan-Out, Sequence, Batch Processing, Custom Tool, Server Tool, Module Config) call into @loopstack/llm-provider. That module is @Global and must be configured once in your root module to set the default model:

import { Module } from '@nestjs/common';
import { LlmProviderModule } from '@loopstack/llm-provider';
import { LoopstackModule } from '@loopstack/loopstack-module';
import { AdvancedWorkflowsExamplesModule } from './advanced-workflows/advanced-workflows-examples.module';
@Module({
imports: [
LoopstackModule.forRoot(),
LlmProviderModule.forRoot({ model: 'claude-sonnet-4-6' }),
AdvancedWorkflowsExamplesModule,
],
})
export class AppModule {}

AdvancedWorkflowsExamplesModule already re-imports ClaudeModule to register the Claude provider; LlmProviderModule.forRoot(...) sets the default model the tools dispatch to. Pure pattern demos that don’t call an LLM (Workflow State, Dynamic Routing, UI Documents) work without it.

Set ANTHROPIC_API_KEY in the environment for the LLM examples.

Examples

Example Studio title Description
Workflow State Advanced - Workflow State Example Persist typed state across transitions via assignState()
Workflow Result Advanced - Workflow Result Example Publish a result for callers via assignResult(), kept apart from private state
Dynamic Routing Advanced - Dynamic Routing Example Conditional routing with @Guard decorators and transition priorities
Sub-Workflow Advanced - Sub-Workflow Example Launch a child workflow via .run() and resume on callback
Fan-Out Advanced - Fan-Out Example Parallel sub-workflows with single aggregated callback (FanOutWorkflow)
Sequence Advanced - Sequence Example Sequential sub-workflows with single aggregated callback (SequenceWorkflow)
Batch Processing Advanced - Batch Processing Example Chunked processing of a list in fixed-size batches
Custom Tool Advanced - Custom Tool Example Authoring custom tools — stateless + stateful, @Tool(), Zod schemas, NestJS injection
Server Tool Advanced - Server Tool Example Authoring a server tool — a tool the LLM provider runs, via ServerTool
Tool Documents Advanced - Tool Documents Example A tool that declares a document on its result envelope instead of saving it
Module Config Advanced - Module Config (Default/French/Nested) forRoot / forFeature patterns for configurable modules
UI Documents Advanced - UI Documents Example Smoke test for built-in document types (Message, Error, Markdown, Plain)

Workflow State

WorkflowStateWorkflow — the minimal state pattern: assignState() in one transition, read the typed state parameter in the next, and format it with a private helper method. State is private to the workflow, so the run publishes no result.

Files

  • workflow-state-example.workflow.ts

Workflow Result

WorkflowResultWorkflow — the workflow’s published result. The first transition keeps a name in state and publishes a greeting with assignResult(). The second reads the name from state and adds a second field with another assignResult(), which merges into the first. The run’s result is { greeting, shout } — what WorkflowRunner callers, parent callbacks (input.data) and the API receive — while the name stays in private state.

Files

  • workflow-result-example.workflow.ts

Dynamic Routing

Demonstrates @Guard-based conditional routing — multiple transitions out of one state, evaluated in priority order, the first one whose guard returns true wins.

Files

  • dynamic-routing-example.workflow.ts

Sub-Workflow

Five workflow files demonstrating sub-workflow composition:

  • sub-workflow-parent.workflow.ts — basic parent that launches a child via .run()
  • sub-workflow-sub.workflow.ts — the child workflow
  • sub-workflow-failing-sub.workflow.ts — a child that fails unless started with fail: false (used by error-handling)
  • sub-workflow-error-handling.workflow.ts — parent reads the child’s outcome via input.hasError / input.status / input.errorMessage; pass fail: false to see the success branch
  • sub-workflow-show-modes.workflow.ts — every show mode (inline, link, hidden) in one flow

For parallel and sequential composition see Fan-Out and Sequence.

Fan-Out

Launches multiple sub-workflows in parallel via FanOutWorkflow from @loopstack/core. The parent receives a single callback once all children complete.

Files

  • fan-out-example.workflow.ts

Sequence

Runs multiple sub-workflows one at a time via SequenceWorkflow from @loopstack/core. The parent receives a single aggregated callback after the last child completes.

Files

  • sequence-example.workflow.ts

Batch Processing

Processes a list of items in fixed-size batches. Items within a batch run concurrently (Promise.all), batches run sequentially via a state-machine loop. Distinct from FanOutWorkflow which runs all sub-workflows simultaneously.

Useful for rate-limited APIs, memory-bounded processing, or quota-constrained operations.

Files

  • batch-processing-example.workflow.ts

Custom Tool

Demonstrates authoring custom tools by extending BaseTool:

  • MathSumTool — stateless, computes a + b
  • CounterTool — stateful, persists across checkpoints
  • MathService — supporting NestJS service injected into a tool

Files

  • custom-tool-example.workflow.ts
  • custom-tool-example.ui.yaml
  • tools/math-sum.tool.ts (stateless)
  • tools/counter.tool.ts (stateful)
  • services/math.service.ts

Server Tool

Demonstrates authoring a server tool by extending ServerTool — a tool the LLM provider runs itself, not your app:

  • CodeExecutionTool (example_code_execution) — has no handle() and no call(). It only implements toServerToolConfig(), which returns the provider-native tool spec (here Anthropic’s code_execution).
  • The workflow lists the tool by name in the tools config of an llm_generate_text call. It never calls the tool itself: Claude runs the code in Anthropic’s sandbox, inside that same call.
  • The reply carries Claude’s use of the tool as a server_tool_use block and its output as a server_tool_result block. The workflow reads the code and its stdout from these blocks, and Studio shows them as one tool call with its result.

A server tool runs only on the provider whose native spec it returns — this one on Claude. Other providers reject a call that lists it. The spec fakes only the Anthropic client, so toServerToolConfig() and the Claude provider run in the test.

Files

  • server-tool-example.workflow.ts
  • tools/code-execution.tool.ts

Tool Documents

Demonstrates a tool that produces a document without writing it:

  • ReceiptTool (create_receipt) — totals a list of items and returns the total as data. It returns the receipt in documents on its result envelope: the document name, the content, and the same options as documentStore.save(). It gets the name with resolveDocumentName(ReceiptDocument), so the name always matches the registered class.
  • ReceiptDocument (receipt) — a registered @Document that Studio renders as Markdown. A declared document must be a registered @Document. Otherwise the tool call fails with Unknown document.
  • The workflow only calls the tool and publishes the total. It saves no document itself: the tool pipeline saves the declared receipt after the call.

The pipeline saves declared documents after any interceptor or replay. So a replayed call saves the documents of its recorded envelope, as a live call would. The spec shows both: a live run saves the receipt the tool built, and a replayed run saves the receipt from the recording.

Files

  • tool-documents-example.workflow.ts
  • tools/receipt.tool.ts
  • documents/receipt-document.ts

Module Config

Three scenarios for configurable modules, each a workflow that calls GreeterTool and saves the greeting it gets back:

  1. Default Greeting (default_greeting) — no forFeature override; uses the app’s forRoot({ language: 'en' }) → Hello, World! [language=en]
  2. French Greeting (french_greeting) — a forFeature({ language: 'fr' }) override in its own module → Bonjour, Monde! [language=fr]
  3. Nested Greeting (nested_greeting) — config passed through a wrapper module (GreeterAgentModule.forFeature) → Hola, Mundo! [language=es]

All three run side by side in one app, each with its own resolved config. Each consumer module provides its own workflow, so the workflows get the GreeterTool of that module’s scope. The @StudioApp workflows list names them, so they can be started from Studio, the API and the CLI. They are not listed again in the module’s providers, because a second instance there would resolve the global config.

Files

  • greeter/ — configurable module (forRoot, forFeature, constants, tool) and the GreeterAgentModule wrapper
  • consumers/ — three module + workflow pairs, one per scenario

UI Documents

A small workflow that saves one of each built-in document type so you can verify Studio renders them correctly.

Files

  • ui-documents-example.workflow.ts

About

Author: Jakob Klippel

License: MIT