Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Input e timeout

Lezione 9 di 14 Aggiornata il 29 luglio 2026 Avanzato
In questa pagina
  1. Cosa entra in un workflow
  2. Struttura e valida con Pydantic
  3. Durata dell’esecuzione
  4. Due livelli di timeout da non confondere
  5. Punti chiave

Cosa entra in un workflow

Ogni workflow riceve parametri di input che definiscono il suo contesto di esecuzione. Poiché questi parametri viaggiano attraverso la rete e vengono archiviati nel log di esecuzione, devono seguire una regola ferrea: devono essere serializzabili in JSON. I tipi primitivi di Python passano senza problemi, così come liste, dizionari e valori null.

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

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

# Nullable
commentaire: str | None = None

Tuttavia, datetime, bytes, set, tuple e classi personalizzate non Pydantic non sono supportati direttamente. Se il tuo workflow deve ricevere una data di fatturazione, convertila in una stringa ISO 8601 prima di passarla e ricostruisci l’oggetto all’interno dell’attività. Questo principio si applica a tutti questi tipi: la conversione è responsabilità tua, non della piattaforma.

Struttura e valida con Pydantic

Passare un dizionario libero funziona, ma perdi ogni garanzia sul suo contenuto. Per parametri strutturati e validati, affidati ai modelli Pydantic, che documentano l’interfaccia del workflow tanto quanto la proteggono.

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

Dal lato del chiamante, non c’è nulla di speciale da fare: i campi del BaseModel diventano semplicemente chiavi di primo livello nel dizionario di input.

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 valida automaticamente i dati ricevuti. Se un campo non è valido, il workflow fallisce immediatamente con un messaggio di errore esplicito, invece di avviare l’esecuzione e crashare tre attività dopo. Questa validazione si stringe secondo le necessità: vincoli di formato su un indirizzo email, limiti numerici su una priorità e, soprattutto, extra = "forbid", che rifiuta i campi sconosciuti.

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

    class Config:
        extra = "forbid"  # Rifiuta i campi sconosciuti

Quest’ultimo punto merita attenzione. Senza extra="forbid", un errore di battitura nel nome di un campo passa inosservato: il campo atteso prende il suo valore predefinito e il workflow gira con parametri diversi da quelli che intendevi. Il fallimento è silenzioso, quindi costoso.

Quando un singolo workflow deve accettare più forme di input, i tipi unione ti permettono di descrivere queste varianti senza moltiplicare i workflow.

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"

Durata dell’esecuzione

Ogni workflow ha una durata massima di esecuzione, impostata dal parametro execution_timeout. Di default, è di un’ora: oltre questa scadenza, il workflow viene automaticamente annullato, indipendentemente dal suo avanzamento. Per un processo destinato a durare trenta secondi, questo valore è comodo; per una pipeline notturna, è una trappola.

Regola questo timeout in base alla natura dell’elaborazione, sia al ribasso che al rialzo. Un workflow a elaborazione rapida beneficia di un limite stretto, perché un superamento segnala allora un problema reale piuttosto che un rallentamento temporaneo.

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)

All’altro estremo, il tetto consentito è di 7 giorni. Questa durata ha senso solo per processi in attesa di un evento esterno, tipicamente una validazione umana: un report raccolto automaticamente ma firmato da un manager che non tornerà dalle ferie prima della settimana successiva.

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:
        # Questo workflow può durare fino a 7 giorni
        # Utile per processi con periodi di attesa umana
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Per calibrare, usa questo ordine di grandezza per famiglia di utilizzo.

Caso d’usoTimeout consigliato
Elaborazione in tempo reale1-5 minuti
Pipeline dati15-60 minuti
Generazione report complessi1-4 ore
Workflow con validazione umana1-7 giorni

Due livelli di timeout da non confondere

execution_timeout delimita l’intero workflow; start_to_close_timeout delimita una singola attività. I due coesistono e si completano: il primo ti protegge da un workflow che non termina mai, il secondo da un’attività bloccata su un servizio silenzioso. Nota nell’esempio sotto che il timeout del client HTTP (240 secondi) è intenzionalmente inferiore allo start_to_close_timeout (5 minuti), così l’errore emerge pulitamente prima che la piattaforma tagli la connessione.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Questa attività ha 5 minuti per completarsi
    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'intero workflow ha 2 ore
        # Ma ogni singola attività ha il proprio timeout
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Un ultimo riflesso per i tuoi input: mantienili leggeri. Il limite è 2 MB e nulla ti obbliga ad avvicinarti. Passa l’URL di un documento piuttosto che il suo contenuto, un ID ordine piuttosto che l’ordine completo, e lascia che siano le attività a recuperare i dati. Definisci valori predefiniti per tutto ciò che è opzionale, documenta ogni campo con Field(description="...") e affida la validazione a Pydantic piuttosto che a istruzioni if sparse nel workflow.

Punti chiave

  • Gli input del workflow devono essere serializzabili in JSON (str, int, float, bool, list, dict)
  • Usa Pydantic BaseModel per input strutturati con validazione automatica
  • Il timeout predefinito è 1 ora, configurabile fino a un massimo di 7 giorni
  • Distingui il timeout del workflow (execution_timeout) da quello dell’attività (start_to_close_timeout)
  • Mantieni gli input leggeri: ID e URL invece di grandi dati grezzi