Workflows Documentation

This skill provides comprehensive documentation and guidance for the Mistral Workflows framework, which is designed for building durable, fault-tolerant workflows with orchestrated activities.

About Workflows

Mistral Workflows is an orchestration control plane that accelerates the development and reliable execution of complex, AI-driven workflows. Built on Temporal for fault-tolerant workflow execution, it combines a user-friendly API with a rich Python framework optimized for Mistral's AI services.

Documentation Structure

The documentation is organized into several categories:

Getting Started

Introduction: Overview of Mistral Workflows and its core architecture
Installation: Guide to installing and setting up the Workflows framework (CLI scaffolding, optional deps)
Core Concepts: Workflows, activities, workers, executions vs runs
Python SDK: Documentation for the Python SDK and WorkflowsClient
Your First Workflow: Step-by-step guide to creating your first workflow

Guides

Workflows: Creating workflows, determinism enforcement (sandbox), input types, timeouts, signals/queries/updates, child workflows, continue-as-new
Activities: Timeouts, retries, heartbeats, local activities, sticky sessions, nested activities
Workflows Exception Handling: WorkflowsException, ErrorCode enum, factory methods
Error Codes: API error codes WF_1000-WF_1600 with HTTP status, description, and resolution
Signals, Queries, and Updates: Workflow communication patterns with input validation
Scheduling: Cron expressions, ScheduleDefinition, SchedulePolicy, overlap handling
Dependency Injection: FastAPI-style Depends() pattern
Streaming: Task API, token streaming, progress updates
Streaming Consumption: WorkflowsClient.stream_events(), NATS subjects, SSE API
Concurrency: execute_activities_in_parallel() with List/Chain/Offset executors
Rate Limiting: Distributed rate limiting across workers
Handling Large Data: OffloadableField, blob storage (S3/Azure/GCS)
Payload Encoding: Payload offloading, AES-GCM encryption, key rotation
Observability: OpenTelemetry traces, trace sampling
Durable Agents: Agent, Runner, RemoteSession/LocalSession, MCP, multi-agent handoffs
Conversational Workflows: InteractiveWorkflow, HITL, ChatInput/FormInput, Canvas editing, Rich UI components, Tool UI states
Local Execution: No-infra dev mode with Pydantic model params
Limitations: System constraints and limits
Workflows Plugins: Mistral AI plugin, Webhook plugin, Nuage plugin, custom plugins
Deployment Patterns: Best practices for deploying workflows
Migration v2 to v3: Breaking changes and upgrade steps from SDK v2 to v3

Testing

Testing Workflows: Integration testing with create_test_worker, hang prevention, sandbox pitfalls

Quick-test script — run any workflow in a local Temporal test environment with zero setup:

python .agents/skills/workflows/scripts/test_workflow.py <workflow_file> --input '{"key": "value"}' [--timeout 30]

Timeout policy for testing: Use aggressive (short) timeouts to keep the feedback loop tight. A hanging test wastes more time than a false timeout. Defaults:

Context	Recommended timeout	When to increase
`--timeout` (quick-test script)	`15` seconds	Workflow makes multiple LLM calls or heavy I/O
`execution_timeout` (pytest)	`timedelta(seconds=10)`	Known long-running workflow
`asyncio.wait_for` (pytest)	`15` seconds	Should always be slightly above `execution_timeout`

If a workflow is known to be long-running (e.g. multi-step agent, large data processing), increase timeouts proportionally — but start short and only raise them when you see legitimate timeout failures, not preemptively.

Internal References

These are additional patterns and utilities not covered in the official docs:

Execution IDs: Generate deterministic execution IDs for child workflows
Pipeline Pattern: Build multi-step workflows with declarative StepSpec definitions
Progress Decorator: Track workflow step progress with automatic event recording
Workflow Testing: Ensure workflow classes are properly registered in workers

When to Use This Skill

Use this skill when you need to:

Build durable workflows: Create long-running, fault-tolerant processes
Orchestrate activities: Coordinate multiple tasks and operations
Handle background jobs: Manage asynchronous processing and task queues
Create multi-step pipelines: Build complex workflows with multiple stages
Schedule tasks: Set up recurring or delayed execution of workflows
Develop LLM agents: Build durable AI agents with MCP tool support
Build conversational workflows: Create interactive workflows with HITL, forms, canvas, and rich UI
Ensure fault tolerance: Implement systems that can recover from failures automatically
Stream events: Real-time token streaming and progress updates via NATS

Key Features

Fault tolerance: Automatic recovery from failures and retries
Durable execution: Workflows can run for extended periods (seconds to years)
Determinism enforcement: Sandbox-based determinism with configurable enforcement
Rich Python framework: Easy-to-use decorators and APIs (mistralai.workflows)
Built-in observability: Deep integration with OpenTelemetry for monitoring
Streaming: NATS-backed real-time token and progress streaming
Rate limiting: Distributed rate limiting shared across workers
Dependency injection: FastAPI-style Depends() pattern
Large payload handling: OffloadableField with S3/Azure/GCS blob storage
Conversational workflows: Interactive workflows with Le Chat integration, forms, canvas, and rich UI components
Durable agents: AI agents with MCP support, multi-agent handoffs, and persistent state
Scalability: Designed to handle complex, distributed applications

workflows

SKILL.mdskills/workflows/SKILL.md