Cookbook examples

Use the Workflows cookbook templates when you want to start with complete examples. Each cookbook demonstrates a different pattern such as human approval, parallel fan-out, or sub-workflows.

After setup, each generated project includes the workflow code, sample data, a worker entrypoint, and helper commands to run the example.

Before running a cookbook, make sure you have:

1. A Mistral account.
2. Python 3.12 installed.
3. uvx available in your shell.
4. A Mistral API key for the workspace where you want to run workflows.

You can inspect the execution timeline or complete a human approval step in Studio.

Run the setup command and select the cookbook template you want to scaffold:

uvx mistralai-workflows-cli setup

uvx mistralai-workflows-cli setup

After setup completes, move into the generated project directory and start the examples:

cd my-workflow # or the name of the folder you created
make start-examples

cd my-workflow # or the name of the folder you created
make start-examples

This registers the cookbook workflows with your workspace and keeps the worker ready to process executions. You can start an execution either from a second terminal with the example command shown under each cookbook, or from Studio.

What it does

This cookbook automates cargo release for maritime logistics. It extracts the shipping document, classifies the cargo, runs dangerous goods checks when needed, validates customs compliance, and pauses for a reviewer if an anomaly is detected.

Use this example when you want to understand wait_for_input(), child workflows, and typed LLM outputs in one end-to-end flow.

How to run it

Run the default path with the included sample document:

make execute-cargo-release

make execute-cargo-release

Run the anomaly path to trigger human review:

make execute-cargo-release \
  input='{"document_uri":"examples/cargo_release/sample_data/shipping_doc_anomaly.png","shipment_id":"BL-2024-RTD-004812"}'

make execute-cargo-release \
  input='{"document_uri":"examples/cargo_release/sample_data/shipping_doc_anomaly.png","shipment_id":"BL-2024-RTD-004812"}'

You can also start cargo-release-compliance in Studio with this input:

{
  "document_uri": "examples/cargo_release/sample_data/shipping_doc_anomaly.png",
  "shipment_id": "BL-2024-HAM-009371"
}

{
  "document_uri": "examples/cargo_release/sample_data/shipping_doc_anomaly.png",
  "shipment_id": "BL-2024-HAM-009371"
}

What to look for

In Studio, inspect the child workflow for dangerous goods validation, then find the wait_for_input event on the anomaly path. Approve or block the shipment and confirm that the parent workflow resumes from the approval step instead of replaying the earlier activities.

What it does

This cookbook triages an insurance claim from text and photo inputs. It analyzes claim photos in parallel, checks the written description for inconsistencies, assigns a deterministic severity, scores fraud risk, and returns a structured triage report.

Use this example when you want to see how a workflow can combine parallel activity execution with deterministic routing and typed outputs.

How to run it

Run the default workflow:

make execute-insurance-claims

make execute-insurance-claims

You can provide your own input:

make execute-insurance-claims input='{"claim_id":"CLM-001","claimant_name":"Jane","description":"My car was hit.","photos":["examples/insurance_claims/sample_data/photos/claim_low_scratch_door.jpg"]}'

make execute-insurance-claims input='{"claim_id":"CLM-001","claimant_name":"Jane","description":"My car was hit.","photos":["examples/insurance_claims/sample_data/photos/claim_low_scratch_door.jpg"]}'

Or start the workflow in Studio with this input:

{
  "claim_id": "CLM-2024-001",
  "claimant_name": "Maria Gonzalez",
  "description": "My car was T-boned at an intersection.",
  "photos": [
    "examples/insurance_claims/sample_data/photos/claim_high_totaled_front.jpg",
    "examples/insurance_claims/sample_data/photos/claim_high_totaled_side.jpg"
  ]
}

{
  "claim_id": "CLM-2024-001",
  "claimant_name": "Maria Gonzalez",
  "description": "My car was T-boned at an intersection.",
  "photos": [
    "examples/insurance_claims/sample_data/photos/claim_high_totaled_front.jpg",
    "examples/insurance_claims/sample_data/photos/claim_high_totaled_side.jpg"
  ]
}

What to look for

In Studio, confirm that the analyze_photo activities start in parallel, then inspect the consistency check, fraud scoring, and final typed report. The routing decision comes from workflow code, not from a separate model call.

What it does

This cookbook modernizes a legacy Python codebase file by file. The parent workflow scans the repository, dispatches one child workflow per file, validates generated code in a subprocess, aggregates the results into a change set, and pauses for human review before producing a PR proposal.

Use this example when you want to learn how to combine sub-workflow fan-out with durable human approval.

How to run it

Run the default workflow:

make execute-code-modernization

make execute-code-modernization

You can also start code-modernization in Studio with this input:

{
  "repo_path": "examples/code_modernization/sample_data/legacy_repo",
  "target": "Python 2.7 → 3.12"
}

{
  "repo_path": "examples/code_modernization/sample_data/legacy_repo",
  "target": "Python 2.7 → 3.12"
}

What to look for

In Studio, confirm that each source file appears as its own child execution. After the child workflows finish, inspect the wait_for_input pause, approve or decline the change set, and verify that the workflow only writes the PR proposal after approval.

What it does

This cookbook generates concise weekly summaries of activity in Linear projects. It accepts a team name or ID and a project name or ID, fetches recent issues in parallel, runs LLM summarization, and pauses for human clarification if the team or project cannot be resolved.

Use this example when you want to see how connectors, on-behalf-of (OBO) authentication, parallel activities, and human-in-the-loop fallback work together in a single workflow.

Prerequisites

This cookbook uses the Linear Connector with on-behalf-of (OBO) mode, which requires a hardened deployment. Before running it:

1. Create a Linear Connector in Studio › Context › Connectors. Name it linear to match the workflow code.
2. Follow the auth flow to add the credential under the connector's Credentials tab.
3. Bootstrap your deployment, then harden it in Settings › Hardened Deployments. Re-register the workflow after hardening so the OBO workflow can register successfully.

For full details, see hardened deployments and connectors.

How to run it

Run the default workflow:

make execute-linear-summary

make execute-linear-summary

When no input is provided, the workflow pauses and prompts for team and project in Studio. You can also provide input directly:

make execute-linear-summary \
  input='{"team":"Engineering","project":"*"}'

make execute-linear-summary \
  input='{"team":"Engineering","project":"*"}'

Or start linear-weekly-summary in Studio with this input:

{
  "team": "Engineering",
  "project": "*"
}

{
  "team": "Engineering",
  "project": "*"
}

What to look for

In Studio, confirm that the issue-fetching and summary-generation activities run in parallel. If the team or project name cannot be resolved, the workflow pauses at a wait_for_input step — answer the prompt in Studio and verify that execution resumes with the corrected values. Check the final output for a structured JSON summary.

After you're comfortable with a cookbook template, open the generated workflow files in src/workflows/ and adapt the activities, input models, and execution paths to your own use case.

For the SDK concepts behind these examples, continue with Core Concepts - Workflows and Building workflows.