---
title: Creating Workflows
description: How to define workflow state machines using BaseWorkflow, @Workflow() decorator, @Transition() decorator, state typing, wait transitions, and guards. Covers the run trace — the per-run event journal (transitions, tool calls, documents, run.settled) with opt-in persistence via --trace. Includes full chat workflow example.
---

# Creating Workflows

A workflow is a state machine defined as a TypeScript class. Define transitions between named states, add guards for conditional routing, and use wait transitions to pause for user input or external events.

> **Before you build much:** read [Best Practices](../best-practices.md) — when to choose scripted vs agentic flows, where logic belongs, the difference between state, result, and documents, and the conventions that keep workflows clean.

## Chat Example

A simple chat workflow: wait for a user message, call LLM, display the response, and loop back.

```typescript
import { z } from 'zod';
import { BaseWorkflow, Transition, type TransitionInput, Workflow } from '@loopstack/common';
import { LlmGenerateTextTool, LlmMessageDocument } from '@loopstack/llm-provider';

@Workflow({
  widget: './chat.ui.yaml', // UI config
})
export class ChatWorkflow extends BaseWorkflow {
  constructor(private readonly llmGenerateText: LlmGenerateTextTool) {
    super();
  }

  // 1. Entry point
  @Transition({ to: 'waiting_for_user' })
  setup(state: Record<string, unknown>) {}

  // 2. Wait for user message
  @Transition({
    from: 'waiting_for_user',
    to: 'ready',
    wait: true,
    schema: z.string(),
  })
  async userMessage(state: Record<string, unknown>, input: TransitionInput<string>) {
    await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data });
  }

  // 3. Call LLM and loop back
  @Transition({
    from: 'ready',
    to: 'waiting_for_user',
  })
  async llmTurn(state: Record<string, unknown>) {
    await this.llmGenerateText.call({}, { config: { provider: 'claude', model: 'claude-sonnet-4-6' } });
  }
}
```

That's a complete workflow. The state flow is:

```
start → waiting_for_user → [user sends message] → ready → llmTurn → waiting_for_user (loop)
```

## The `@Workflow` Decorator

```typescript
@Workflow({
  widget: './chat.ui.yaml',
})
```

All options are optional.

| Option         | Type                       | Default                                                 | Description                                                                                                                    |
| -------------- | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `name`         | `string`                   | class name with `Workflow` suffix stripped, snake_cased | Explicit snake_case identifier. E.g. `ChatWorkflow` → `chat`, `AgentExampleWorkflow` → `agent_example`.                        |
| `title`        | `string`                   | —                                                       | Human-readable display title shown in Studio UI.                                                                               |
| `description`  | `string`                   | —                                                       | Human-readable description shown in Studio UI.                                                                                 |
| `widget`       | `WidgetRef \| WidgetRef[]` | —                                                       | Path(s) to YAML file(s) — or inline widget object(s) — defining the Studio UI surface for this workflow.                       |
| `schema`       | `z.ZodType`                | —                                                       | Zod schema validating workflow input arguments. Surfaces as `ctx.args` in transitions.                                         |
| `configSchema` | `z.ZodType`                | —                                                       | Zod schema validating workflow config (provided via `options.config` at start time / sub-workflow `run()`).                    |
| `stateSchema`  | `z.ZodType`                | —                                                       | Zod schema validating the resulting state after every transition (see [Validating State](#validating-state-with-stateschema)). |

```typescript
@Workflow({
  widget: './prompt.ui.yaml',
  schema: z.object({
    subject: z.string().default('coffee'),
  }),
})
```

## `BaseWorkflow`

All workflows extend `BaseWorkflow`, which provides:

| Property / Method    | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `this.documentStore` | Save and query documents via `this.documentStore.save(DocClass, content, options?)` |
| `this.render`        | Render Handlebars templates via `this.render(templatePath, data?)`                  |

Context is passed as a parameter to transition methods via `ctx: RunContext<TArgs>`. The generic parameter types `ctx.args` — prefer it over casting:

| Context Property            | Description                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `ctx.userId`                | User ID                                                                                    |
| `ctx.workspaceId`           | Workspace ID                                                                               |
| `ctx.workflowId`            | Current workflow run ID                                                                    |
| `ctx.args`                  | Validated input arguments (typed via `RunContext<TArgs>`)                                  |
| `ctx.execution?.place`      | Current state name. Present in workflow transitions, absent when `ctx` is passed to tools. |
| `ctx.execution?.retryCount` | Retry attempt counter for the current transition (0 on first run).                         |

```typescript
@Transition({ to: 'ready', schema: z.object({ subject: z.string() }) })
setup(state: MyState, ctx: RunContext<{ subject: string }>) {
  this.assignState({ subject: ctx.args.subject });
}
```

## Transition Types

### Initial Transition — Entry Point

Runs once when the workflow starts. Uses `@Transition` with no `from` (defaults to `'start'`):

```typescript
@Transition({ to: 'ready' })
setup(state: MyState, ctx: RunContext<{ subject: string }>) {
  this.assignState({ subject: ctx.args.subject });
}
```

The `state` parameter starts as an empty object `{}` — the initial transition is the place to populate it.

### Standard Transition — State Change

Moves between states. Fires automatically unless `wait: true` is set.

```typescript
@Transition({ from: 'ready', to: 'processed' })
async doWork(state: MyState) {
  const result = await this.myTool.call({ query: 'hello' });
  this.assignState({ data: result.data });
}
```

A method can listen on **multiple source states**:

```typescript
@Transition({ from: 'ready', to: 'prompt_executed' })
@Transition({ from: 'tools_done', to: 'prompt_executed' })
async llmTurn(state: MyState) { ... }
```

### Wait Transition — Pause for Input

Add `wait: true` to pause the workflow until externally triggered — by user input, a button click, or a sub-workflow callback. Use `schema` to validate and type the incoming `data`; the transition method receives a `TransitionInput<TData>` envelope with `data` plus failure info (`hasError`, `errorMessage`, `status`).

```typescript
@Transition({
  from: 'waiting_for_user',
  to: 'ready',
  wait: true,
  schema: z.object({ message: z.string() }),
})
async userMessage(state: MyState, input: TransitionInput<{ message: string }>) {
  await this.documentStore.save(LlmMessageDocument, {
    role: 'user',
    text: input.data.message,
  });
}
```

For approval gates, confirmation dialogs, and other interactive pauses built on top of `wait: true`, see [Human-in-the-Loop](../patterns/human-in-the-loop.md).

### Final Transition — Completion

Uses `@Transition` with `to: 'end'`. The workflow's output is published via `this.assignResult(...)` or `this.setResult(...)` — that value is what parent workflow callbacks and `WorkflowRunner` callers receive.

```typescript
@Transition({ from: 'done', to: 'end' })
finish(state: MyState) {
  this.setResult({ concept: state.confirmedConcept! });
}
```

## Guarding Transitions

When multiple transitions share the same `from` state, attach `@Guard('methodName')` to pick which one fires:

- Higher `priority` is checked first. Transitions without `priority` are evaluated last, in declaration order.
- A guard is a boolean method on the workflow that receives the current `state` and returns `true` to allow the transition.
- A transition without a guard always passes — use it as the fallback.

```typescript
@Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 })
@Guard('hasToolCalls')
async executeToolCalls(state: MyState) {
  const result = await this.llmDelegateToolCalls.call({
    message: state.llmResult!.message,
    tools: TOOLS, // the tool names given to llmGenerateText
    callback: { transition: 'toolResultReceived' },
  });
  this.assignState({ delegateResult: result.data });
}

@Transition({ from: 'prompt_executed', to: 'end' })
respond(_state: MyState) {}

hasToolCalls(state: MyState): boolean {
  return state.llmResult?.message.stopReason === 'tool_use';
}
```

From `prompt_executed`, `executeToolCalls` fires whenever the LLM requested tools; otherwise `respond` (unguarded) ends the workflow.

## State

Transitions return nothing — mutate state via `this.assignState(...)`. Use `async` when the body awaits. State is read from the `state` parameter and written through setters on `BaseWorkflow`:

| Setter                       | Effect                                                                                                    |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `this.assignState(partial)`  | Shallow-merge `partial` into the current state. The most common form.                                     |
| `this.setState(full)`        | Replace the state object outright.                                                                        |
| `this.assignResult(partial)` | Shallow-merge `partial` into the workflow's published `result` (visible to callers and parent callbacks). |
| `this.setResult(full)`       | Replace the workflow's published `result` outright.                                                       |

```typescript
interface MyState {
  counter: number;
  llmResult?: LlmGenerateTextResult;
}

export class MyWorkflow extends BaseWorkflow {
  @Transition({ from: 'ready', to: 'processed' })
  process(state: MyState) {
    this.assignState({ counter: (state.counter ?? 0) + 1 });
  }
}
```

Values persist even when the workflow pauses and resumes. Returning a value from a transition is a runtime error — every write must go through the setters.

### Validating State with `stateSchema`

Add a Zod schema via `@Workflow({ stateSchema })` to enforce the state shape at runtime. The processor validates the resulting state after every transition (before persistence). If validation fails the transition errors out — bugs that corrupt state are caught at the point they occur instead of leaking into later transitions or checkpoints.

```typescript
const MyStateSchema = z.object({
  counter: z.number().int().nonnegative(),
  llmResult: z.unknown().optional(),
});

@Workflow({
  stateSchema: MyStateSchema,
})
export class MyWorkflow extends BaseWorkflow {
  @Transition({ from: 'ready', to: 'processed' })
  process(state: z.infer<typeof MyStateSchema>) {
    this.assignState({ counter: (state.counter ?? 0) + 1 });
  }
}
```

Use this when the state shape is critical and you want fail-fast diagnostics. Skip it for prototyping or when the state is loose by design.

## Injecting Tools

Tools are injected via standard NestJS constructor injection:

```typescript
constructor(
  private readonly llmGenerateText: LlmGenerateTextTool,
) { super(); }

@Transition({ from: 'ready', to: 'done' })
async process(state: MyState) {
  const result = await this.llmGenerateText.call(
    { prompt: 'Write a haiku' },
    { config: { provider: 'claude', model: 'claude-sonnet-4-6' } },
  );
  this.assignState({ llmResult: result.data });
}
```

Any provider can be injected the same way. For time-dependent logic, inject the framework clock (`@Inject(CLOCK) private readonly clock: Clock`) instead of calling `Date.now()` or `setTimeout` directly — under a test clock the workflow stays deterministic.

## Documents

Use `this.documentStore.save()` to create or update documents. Reference document classes directly — no injection needed.

```typescript
// Create a document
await this.documentStore.save(LlmMessageDocument, {
  role: 'user',
  text: 'Hello!',
});

// Update an existing document by key, in place
await this.documentStore.save(
  LlmMessageDocument,
  { role: 'assistant', text: 'Updated response' },
  { key: 'response-1', position: 'keep' },
);

// Hidden context (not shown in UI — LLM still sees it as conversation history)
await this.documentStore.save(LlmContextDocument, { role: 'user', text: 'System prompt' });
```

## Templates

`render` is available directly on `BaseWorkflow` (like `documentStore`). Use `this.render()` to render Handlebars template files:

```typescript
const rendered = this.render(join(__dirname, 'templates', 'prompt.md'), {
  subject: args.subject,
});
```

## Places (States)

Places are implicit — defined by `from`/`to` values in your decorators. Two special places:

- **`start`** — Implicit initial place (the initial transition moves from here when `from` is omitted)
- **`end`** — When reached, the workflow completes

All other place names are arbitrary strings you choose.

## The Run Trace

Every run produces a **trace**: an ordered, append-only journal of everything the run did. The engine never reads it — it exists for you: debugging a failed run, asserting on behavior in tests, deriving replay fixtures, and auditing what an automation actually executed.

| Event                                            | Emitted when                               | Carries                                                                        |
| ------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------ |
| `transition.started`                             | A transition begins                        | transition id, `from`/`to`, the wait payload                                   |
| `transition.completed`                           | It succeeds                                | duration, a per-key **state diff**, whether the result was touched             |
| `transition.failed`                              | It throws or a sub-workflow callback fails | error, retry count, whether a retry is scheduled                               |
| `tool.called` / `tool.completed` / `tool.failed` | Each tool call                             | tool name, per-transition order, validated args, the result envelope, duration |
| `document.emitted`                               | A document is saved                        | document name/key, the invalidated predecessor key                             |
| `child.queued` / `child.settled`                 | A sub-workflow launches / finishes         | child workflow id, name, status                                                |
| `run.settled`                                    | Every park and terminal settle             | status, place — parks include the transitions the run is waiting on            |

Events are ordered by a per-run monotonic `seq` (continuous across pause/resume) and carry a wall-clock `ts`. Failing tool calls and failing transitions are first-class events — a trace always shows _where_ a run died, with the exact call and error.

**In memory, the trace is always on.** A run's processing result carries it (`meta.trace`), stateless runs carry it across park/resume, and workflow tests assert on it via [`run.trace` and `run.toolCalls`](/docs/build/testing).

**Persistence is opt-in per run.** Start a run with `loopstack run <workflow> --trace` (or `trace: true` on the start payload) and its whole run tree — sub-workflows inherit the flag — persists its events as queryable rows. Read them back with `loopstack runs <id> --record <file>` (derives a [replay fixture](/docs/build/testing)), `GET /workflows/:id/tool-calls`, or `client.workflows.toolCalls(id)`. To record every run, e.g. on a dev backend, enable it globally with the [`trace` option / `LOOPSTACK_TRACE=true`](/docs/reference/configuration#trace).

## YAML Configuration

YAML files define **UI layout only** — no transitions, conditions, or tool calls. They configure what widgets appear in the Studio interface.

```yaml
title: 'My Workflow'
description: 'What this workflow does'

ui:
  widgets:
    - widget: form
      enabledWhen: [waiting]
      options:
        properties:
          name:
            title: Name
        actions:
          - type: button
            transition: userResponse
            label: Submit
    - widget: prompt-input
      enabledWhen: [waiting_for_user]
      options:
        transition: userMessage
```

The `transition` values must match **method names** of `wait: true` transitions.

### `enabledWhen`

Controls when a widget is interactive based on the current workflow place. Outside the listed places the widget stays on screen but is disabled:

```yaml
- widget: prompt-input
  enabledWhen:
    - waiting_for_user # Only enabled at this place
  options:
    transition: userMessage
```

### `showWhen`

Controls when a widget is visible. Outside the listed places the widget is not rendered at all — use it for widgets that only make sense at one step, such as a cancel or recover button:

```yaml
- widget: button
  showWhen:
    - awaiting_tools # Only rendered at this place
  options:
    transition: cancelPendingTools
    label: Cancel pending tools
```

When a widget sets both, `showWhen` decides whether it is rendered and `enabledWhen` whether it is enabled. See [Workflow YAML Schema — `showWhen`](/docs/reference/workflow-yaml#showwhen).

### Form Actions

Buttons that trigger `wait: true` transitions when clicked:

```yaml
actions:
  - type: button
    transition: confirm # Must match the method name
    label: 'Confirm'
```

## Module Registration

```typescript
@Module({
  imports: [ClaudeModule],
  providers: [ChatWorkflow],
  exports: [ChatWorkflow],
})
export class ChatModule {}
```

## File Structure

```
src/
├── workflows/
│   ├── chat.workflow.ts
│   ├── chat.ui.yaml
│   └── templates/
│       └── systemMessage.md
├── chat.module.ts
└── index.ts
```

## Registry References

- [Prompt Input Chat example](/docs/examples/hitl#prompt-input-chat) — Multi-turn chat loop with the prompt-input widget, without an LLM
- [Prompt example](/docs/examples/llm#prompt) — Simple single-turn prompt workflow
- [Custom Agent example](/docs/examples/agent#custom-agent) — Tool calling loop with guards and conditional routing
- [Dynamic Routing example](/docs/examples/advanced-workflows#dynamic-routing) — Multi-level guard-based routing
- [Workflow State example](/docs/examples/advanced-workflows#workflow-state) — State management with typed state interface
- [Sub-Workflow example](/docs/examples/advanced-workflows#sub-workflow) — Sub-workflow execution with callbacks

---

> **Using an AI coding agent?** See [Skill: Create a Custom Workflow](../../skills/create-custom-workflow.md) for a dense checklist and syntax reference optimized for code generation.
