Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Entrées et délais d'expiration

Lektion 9 av 14 Uppdaterad 29 juli 2026 Avancerad
På denna sida
  1. Ce qui entre dans un workflow
  2. Structurer et valider avec Pydantic
  3. Durée de vie de l’exécution
  4. Deux niveaux de délai d’expiration à ne pas confondre
  5. Viktiga punkter

Ce qui entre dans un workflow

Chaque workflow reçoit des paramètres d’entrée qui définissent son contexte d’exécution. Comme ces paramètres transitent par le réseau et sont stockés dans le journal d’exécution, ils doivent respecter une règle stricte : être sérialisables en JSON. Les types primitifs Python passent sans problème, tout comme les listes, les dictionnaires et les valeurs nulles.

# Types primitifs
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True

# Collections
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}

# Nullable
commentaire: str | None = None

En revanche, datetime, bytes, set, tuple et les classes personnalisées non-Pydantic ne sont pas pris en charge directement. Si ton workflow doit recevoir une date de facture, convertis-la en chaîne ISO 8601 avant de la transmettre, puis reconstruis l’objet à l’intérieur de l’activité. Ce principe s’applique à tous ces types : la conversion est ta responsabilité, pas celle de la plateforme.

Structurer et valider avec Pydantic

Transmettre un dictionnaire libre fonctionne, mais tu perds toute garantie sur son contenu. Pour des paramètres structurés et validés, appuie-toi sur les modèles Pydantic, qui documentent l’interface du workflow autant qu’ils la protègent.

from pydantic import BaseModel, Field

class ParametresAnalyse(BaseModel):
    url_document: str
    langue: str = "fr"
    max_tokens: int = Field(default=1000, ge=100, le=10000)
    inclure_metadata: bool = False

@workflows.workflow.define(name="analyse_documentaire")
class AnalyseDocumentaire:
    @workflows.workflow.entrypoint
    async def run(self, params: ParametresAnalyse) -> dict:
        extraction = await extraire_texte(params.url_document, params.langue)
        analyse = await analyser_contenu(extraction["texte"], params.max_tokens)
        
        if params.inclure_metadata:
            metadata = await extraire_metadata(params.url_document)
            return {**analyse, "metadata": metadata}
        
        return analyse

Côté appelant, rien de spécial à faire : les champs du BaseModel deviennent simplement des clés de premier niveau dans le dictionnaire d’entrée.

execution = await client.workflows.execute_workflow_async(
    workflow_identifier="analyse_documentaire",
    input={
        "url_document": "https://example.com/rapport.pdf",
        "langue": "fr",
        "max_tokens": 2000,
        "inclure_metadata": True
    }
)

Pydantic valide automatiquement les données reçues. Si un champ est invalide, le workflow échoue immédiatement avec un message d’erreur explicite, au lieu de démarrer l’exécution pour planter trois activités plus tard. Cette validation se resserre selon les besoins : contraintes de format sur une adresse e-mail, bornes numériques sur une priorité, et surtout extra = "forbid", qui rejette les champs inconnus.

class ParametresStricts(BaseModel):
    email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
    priorite: int = Field(ge=1, le=5)

    class Config:
        extra = "forbid"  # Rejette les champs inconnus

Ce dernier point mérite attention. Sans extra="forbid", une faute de frappe dans un nom de champ passe inaperçue : le champ attendu prend sa valeur par défaut et le workflow s’exécute avec des paramètres différents de ceux que tu voulais. L’échec est silencieux, donc coûteux.

Lorsqu’un seul workflow doit accepter plusieurs formes d’entrée, les types union te permettent de décrire ces variantes sans multiplier les workflows.

from typing import Union

class TraitementTexte(BaseModel):
    texte: str
    type_traitement: str = "resume"

class TraitementURL(BaseModel):
    url: str
    type_traitement: str = "resume"

class ParametresFlexibles(BaseModel):
    source: Union[TraitementTexte, TraitementURL]

    class Config:
        extra = "forbid"

Durée de vie de l’exécution

Chaque workflow possède une durée d’exécution maximale, définie par le paramètre execution_timeout. Par défaut, elle est d’une heure : passé ce délai, le workflow est automatiquement annulé, quelle que soit sa progression. Pour un processus censé durer trente secondes, cette valeur est confortable ; pour un pipeline nocturne, c’est un piège.

Ajuste ce délai d’expiration à la nature du traitement, à la baisse comme à la hausse. Un workflow au traitement rapide bénéficie d’une limite serrée, car un dépassement signale alors un vrai problème plutôt qu’un ralentissement passager.

from datetime import timedelta

@workflows.workflow.define(
    name="traitement_rapide",
    execution_timeout=timedelta(minutes=10)
)
class TraitementRapide:
    @workflows.workflow.entrypoint
    async def run(self, donnees: dict) -> dict:
        return await traiter(donnees)

À l’autre extrémité, le plafond autorisé est de 7 jours. Cette durée n’a de sens que pour des processus en attente d’un événement externe, typiquement une validation humaine : un rapport collecté automatiquement mais signé par un manager qui ne reviendra de congés que la semaine suivante.

from datetime import timedelta

@workflows.workflow.define(
    name="workflow_longue_duree",
    execution_timeout=timedelta(days=7)
)
class WorkflowLongueDuree:
    @workflows.workflow.entrypoint
    async def run(self, params: dict) -> dict:
        # Ce workflow peut durer jusqu'à 7 jours
        # Utile pour les processus avec des périodes d'attente humaine
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Pour calibrer, utilise cet ordre de grandeur par famille d’usage.

Cas d’usageDélai d’expiration recommandé
Traitement en temps réel1-5 minutes
Pipeline de données15-60 minutes
Génération de rapports complexes1-4 heures
Workflow avec validation humaine1-7 jours

Deux niveaux de délai d’expiration à ne pas confondre

execution_timeout borne l’ensemble du workflow ; start_to_close_timeout borne une seule activité. Les deux coexistent et se complètent : le premier te protège d’un workflow qui ne se termine jamais, le second d’une activité bloquée sur un service silencieux. Note dans l’exemple ci-dessous que le délai d’expiration du client HTTP (240 secondes) est volontairement inférieur au start_to_close_timeout (5 minutes), afin que l’erreur remonte proprement avant que la plateforme ne coupe la connexion.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Cette activité dispose de 5 minutes pour se terminer
    async with httpx.AsyncClient(timeout=240) as client:
        response = await client.post(params["url"], json=params["data"])
    return response.json()

@workflows.workflow.define(
    name="pipeline_multi_etapes",
    execution_timeout=timedelta(hours=2)
)
class PipelineMultiEtapes:
    @workflows.workflow.entrypoint
    async def run(self, sources: list) -> dict:
        # L'ensemble du workflow dispose de 2 heures
        # Mais chaque activité individuelle a son propre délai d'expiration
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Un dernier réflexe pour tes entrées : garde-les légères. La limite est de 2 Mo, et rien ne t’oblige à t’en approcher. Transmets l’URL d’un document plutôt que son contenu, un ID de commande plutôt que la commande complète, et laisse les activités récupérer les données. Définis des valeurs par défaut pour tout ce qui est optionnel, documente chaque champ avec Field(description="..."), et confie la validation à Pydantic plutôt qu’à des instructions if éparpillées dans le workflow.

Viktiga punkter

  • Les entrées de workflow doivent être sérialisables en JSON (str, int, float, bool, list, dict)
  • Utilise Pydantic BaseModel pour des entrées structurées avec validation automatique
  • Le délai d’expiration par défaut est 1 heure, configurable jusqu’à 7 jours maximum
  • Distingue le délai d’expiration du workflow (execution_timeout) de celui de l’activité (start_to_close_timeout)
  • Garde les entrées légères : IDs et URLs plutôt que grandes données brutes