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:
npm install @loopstack/claude @loopstack/common @loopstack/core @loopstack/llm-providerRegister 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 workflowsub-workflow-failing-sub.workflow.ts— a child that fails unless started withfail: false(used by error-handling)sub-workflow-error-handling.workflow.ts— parent reads the child’s outcome viainput.hasError/input.status/input.errorMessage; passfail: falseto see the success branchsub-workflow-show-modes.workflow.ts— everyshowmode (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, computesa + bCounterTool— stateful, persists across checkpointsMathService— supporting NestJS service injected into a tool
Files
custom-tool-example.workflow.tscustom-tool-example.ui.yamltools/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 nohandle()and nocall(). It only implementstoServerToolConfig(), which returns the provider-native tool spec (here Anthropic’scode_execution).- The workflow lists the tool by name in the
toolsconfig of anllm_generate_textcall. 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_useblock and its output as aserver_tool_resultblock. 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.tstools/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 asdata. It returns the receipt indocumentson its result envelope: the document name, the content, and the same options asdocumentStore.save(). It gets the name withresolveDocumentName(ReceiptDocument), so the name always matches the registered class.ReceiptDocument(receipt) — a registered@Documentthat Studio renders as Markdown. A declared document must be a registered@Document. Otherwise the tool call fails withUnknown 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.tstools/receipt.tool.tsdocuments/receipt-document.ts
Module Config
Three scenarios for configurable modules, each a workflow that calls GreeterTool and saves the greeting it gets back:
- Default Greeting (
default_greeting) — noforFeatureoverride; uses the app’sforRoot({ language: 'en' })→Hello, World! [language=en] - French Greeting (
french_greeting) — aforFeature({ language: 'fr' })override in its own module →Bonjour, Monde! [language=fr] - 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 theGreeterAgentModulewrapperconsumers/— 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