> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.meetluno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how to build and run workflows.

A workflow is a reliable sequence of steps written in TypeScript. Prefer one when you already know the order of work—even if an individual step uses an LLM or agent for judgment: call an action, prompt an agent, branch on the result, wait for approval, then continue.

Luno OS records each action, agent, or LLM step as it finishes. If a later step fails or the run is retried, the workflow resumes from the first unfinished step instead of starting over.

## Example requests

Ask your coding agent for an automation with known steps. It can turn that request into a workflow whose steps are tracked, retried, and inspected.

> "When a new signup comes in, research the account, score the lead, add it to Salesforce, and post a brief to Slack."

> "Every Friday, collect closed deals from HubSpot, generate a sales summary, and email it to the leadership team."

> "When a support escalation is approved, create a Linear issue, notify the account owner, and wait for a human resolution before closing the loop."

## How workflows are defined

In Luno OS, workflows live in your project code under `src/workflows/`. Each file default-exports a `defineWorkflow()` definition with typed input and output, and the runtime discovers it when you run or deploy the project.

```ts src/workflows/signup-pipeline.ts theme={null}
import { defineWorkflow } from "@meetluno/luno/workflow";
import { z } from "zod";
import { researchSignup } from "../actions/research-signup";
import { postBrief } from "../actions/post-brief";

export default defineWorkflow({
  slug: "signup-pipeline",
  name: "Signup Pipeline",
  description: "Research a signup lead and post a brief to Slack.",
  input: z.object({ name: z.string(), email: z.string().email() }),
  output: z.object({ posted: z.boolean() }),
})
  .then(researchSignup) // { name, email } → { brief }
  .map(({ inputData }) => ({ text: inputData.brief }))
  .then(postBrief) // { text } → { posted }
  .commit();
```

`defineWorkflow()` returns a builder. Chain steps with `.then()` (and `.parallel()`, `.branch()`, `.foreach()`, `.sleep()`, …), reshape data between them with `.map()`, then finish with `.commit()`. Each step receives the previous step's output as its input, and TypeScript checks that every step accepts what the one before it produces and that the last step returns the declared `output`. Each step's result is recorded, so a retried run resumes instead of repeating finished work.

## What workflows can do

| Capability | How it works |
| - | - |
| **Typed input and output** | Zod schemas validate the payload going in and the result coming out |
| **Action steps** | Chain any [action](https://docs.os.meetluno.ai/learn/actions/overview.md) with `.then(action)`, your own or one from an integration |
| **Agent steps** | Prompt an [agent](https://docs.os.meetluno.ai/learn/agents/overview.md) with `agentStep()` when a step needs judgment |
| **LLM steps** | Use `llmStep()` for a one-shot model call without defining a full agent |
| **Control flow** | `.parallel()`, `.branch()`, `.foreach()`, `.dowhile()` / `.dountil()`, and `.map()` to reshape data |
| **Durability** | Completed steps are recorded, so retries resume from the failed step instead of restarting |
| **Durable waits** | `.sleep()` / `.sleepUntil()` and `hookStep()` suspend a run for a delay or until it is resumed externally |
| **Sandbox** | An optional `/workspace` shared with agent steps for file and code work |

Workflows are one of the main primitives in a project, alongside [agents](https://docs.os.meetluno.ai/learn/agents/overview.md), [actions](https://docs.os.meetluno.ai/learn/actions/overview.md), and [triggers](https://docs.os.meetluno.ai/learn/triggers/overview.md). Reach for a workflow when the work is a known sequence that should run reliably; reach for an [agent](https://docs.os.meetluno.ai/learn/agents/overview.md) when the work needs open-ended reasoning. The two compose: a workflow can prompt an agent as a step, and an agent can run a workflow as a [tool](https://docs.os.meetluno.ai/learn/agents/build-agents.md#workflows-as-tools).

## How to run workflows

Most workflows run from a [trigger](https://docs.os.meetluno.ai/learn/triggers/overview.md), such as a webhook, schedule, poll, or app event attached to the workflow. While building, run them directly from the CLI:

```bash theme={null}
luno workflows run signup-pipeline --input '{"name":"Ada","email":"ada@example.com"}'
```

To let people outside your team start a run from a link, publish a [workflow form](https://docs.os.meetluno.ai/learn/workflows/forms.md). See [run workflows](https://docs.os.meetluno.ai/learn/workflows/run-workflows.md) for triggers, forms, the HTTP API, and using a workflow as an agent tool.

## Running deployed workflows

Deploy your project, then run the workflow against the deployed project:

```bash theme={null}
luno deploy --project <slug>   # or --filter workflows/signup-pipeline
luno workflows run signup-pipeline --input '{"name":"Ada","email":"ada@example.com"}'
```

## Next steps

> **[Build workflows](https://docs.os.meetluno.ai/learn/workflows/build-workflows.md)**
>
> Define workflows with typed input, steps, durability, and waits.

> **[Best practices](https://docs.os.meetluno.ai/learn/workflows/authoring-best-practices.md)**
>
> Keep workflow steps small, typed, and safe to retry.

> **[Run workflows](https://docs.os.meetluno.ai/learn/workflows/run-workflows.md)**
>
> Start runs from the CLI, triggers, forms, the API, and agent tools.

> **[Workflow forms](https://docs.os.meetluno.ai/learn/workflows/forms.md)**
>
> Publish a public form that starts a run from a shareable link.

> **[Test workflows](https://docs.os.meetluno.ai/learn/workflows/test-workflows.md)**
>
> Run workflows in tests and assert their output.

> **[Workflow runs](https://docs.os.meetluno.ai/learn/logs/workflow-runs.md)**
>
> Inspect input, output, steps, errors, and traces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.