Your First Workflow

We'll walk through creating a simple workflow that executes a single activity.

To complete this quickstart, you will need:

1. A Mistral account.
2. Python 3.12 installed on your machine.
3. uvx installed in your environment.

To get started, run the following uvx command in your terminal:

uvx mistralai-workflows-cli setup

uvx mistralai-workflows-cli setup

This scaffolds a ready-to-run Python project with the Workflows SDK already configured, a minimal example workflow, and helper commands to run your worker and trigger executions.

The command prompts you to generate a Mistral API key in the Mistral Console. Follow the prompts to generate the API key, and then pass it to the command when requested. Note that API keys are only accessible once.

Open the my-workflow directory in the IDE of your choice.

Navigate to src/workflows/hello.py to see an example workflow. This file contains the following code:

"""Minimal example workflow — edit this file or create new ones."""

from pydantic import BaseModel

import mistralai.workflows as workflows


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


@workflows.activity()
async def greet(name: str) -> str:
    """A simple activity that returns a greeting."""
    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)

"""Minimal example workflow — edit this file or create new ones."""

from pydantic import BaseModel

import mistralai.workflows as workflows


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


@workflows.activity()
async def greet(name: str) -> str:
    """A simple activity that returns a greeting."""
    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)

This code defines a Mistral Workflow that takes a name as input and returns a greeting.

Open src/discover.py. Focus on the following snippet:

await workflows.run_worker(discovered)

await workflows.run_worker(discovered)

This code auto-discovers all workflows in the src/workflows directory, and then auto-watches them using the Mistral Workflows run_worker function.

To start the worker, run the following command in your terminal:

make start-worker

make start-worker

This command starts the worker, connects to the Mistral API, and registers your workflow to wait for a task to do. For details on this command, check out the Makefile. To see the workflow running, you need to trigger execution using one of the methods in the following step.

You can trigger your workflow using the Mistral Console, the Mistral Python SDK, or the Mistral API. The my-workflow project also includes a Makefile command to easily trigger workflows.

{
  "result": "Hello, <your_name>! Welcome to Mistral Workflows."
}

{
  "result": "Hello, <your_name>! Welcome to Mistral Workflows."
}

When you're done testing your workflow, press Ctrl+C to stop the worker.

You've successfully created and executed your first workflow! To learn more workflow concepts, view Core Concepts - Workflows. For scaling patterns and running multiple workers, see Core Concepts - Scaling with Multiple Workers.