Build a workflow

Workflows let you run multi-step AI pipelines that survive crashes, retries, and long waits. Your code runs in your environment; Mistral handles orchestration, state, and observability.

By the end of this quickstart you'll have a working workflow running locally, triggered from the Mistral Console.

Time to complete: ~15 minutes

• A Mistral API key (see Send your first API request if you don't have one yet)
• Python 3.12 or later
• uv installed (uvx ships with it)

Run the following command in your terminal:

uvx mistralai-workflows-cli setup

uvx mistralai-workflows-cli setup

The CLI scaffolds a ready-to-run Python project and prompts you for your Mistral API key. Enter the key when asked — it's stored in the project's environment configuration.

Open the generated directory (default name: my-workflow) in your editor.

Open src/workflows/hello.py. The scaffolded project includes a minimal example:

from pydantic import BaseModel
import mistralai.workflows as workflows


class HelloInput(BaseModel):
    name: str = "World"


@workflows.activity()
async def greet(name: str) -> str:
    return f"Hello, {name}! Welcome to Mistral Workflows."


@workflows.workflow.define(
    name="hello-world",
    workflow_display_name="Hello World",
    workflow_description="A minimal hello-world workflow.",
)
class HelloWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, input: HelloInput) -> str:
        return await greet(input.name)

from pydantic import BaseModel
import mistralai.workflows as workflows


class HelloInput(BaseModel):
    name: str = "World"


@workflows.activity()
async def greet(name: str) -> str:
    return f"Hello, {name}! Welcome to Mistral Workflows."


@workflows.workflow.define(
    name="hello-world",
    workflow_display_name="Hello World",
    workflow_description="A minimal hello-world workflow.",
)
class HelloWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, input: HelloInput) -> str:
        return await greet(input.name)

Two things to notice:

• @workflows.activity() marks a function as a durable step. If the process crashes mid-run, the platform replays from the last completed activity.
• @workflows.workflow.define registers the workflow with a name you'll use to trigger it.

From the root of your project, run:

make start-worker

make start-worker

The worker connects to the Mistral API, registers your workflow, and waits for tasks. Keep this terminal open.

With the worker running, open a second terminal and trigger an execution using the Makefile command:

make execute workflow=hello-world input='{"name": "World"}'

make execute workflow=hello-world input='{"name": "World"}'

Or trigger it from the Mistral Console:

1. Navigate to Workflows in the sidebar.
2. Select hello-world.
3. Click Start Workflow and pass {"name": "World"} as input.
4. Open the Executions tab to watch it run.

The execution completes with:

{
  "result": "Hello, World! Welcome to Mistral Workflows."
}

{
  "result": "Hello, World! Welcome to Mistral Workflows."
}

If the worker terminal shows a connection error, confirm your API key is set correctly and that the worker process is still running.

Press Ctrl+C to stop the worker when you're done.