Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Inputs en time-outs

Les 9 van 14 Bijgewerkt op 29 juli 2026 Gevorderd
Op deze pagina
  1. Wat gaat er in een workflow
  2. Structureren en valideren met Pydantic
  3. Levensduur van de uitvoering
  4. Twee time-out niveaus die u niet mag verwarren
  5. Belangrijkste punten

Wat gaat er in een workflow

Elke workflow ontvangt invoerparameters die de uitvoeringscontext definiëren. Omdat deze parameters via het netwerk worden verzonden en in het uitvoeringslogboek worden opgeslagen, moeten ze één strikte regel volgen: ze moeten JSON-serialiseerbaar zijn. Python-primitieven werken zonder problemen, evenals lijsten, dictionaries en null-waarden.

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

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

# Nullable
commentaire: str | None = None

datetime, bytes, set, tuple en niet-Pydantic aangepaste klassen worden echter niet direct ondersteund. Als uw workflow een factuurdatum moet ontvangen, converteer deze dan naar een ISO 8601-tekenreeks voordat u deze doorgeeft, en reconstrueer het object binnen de activiteit. Dit principe geldt voor al dergelijke types: conversie is uw verantwoordelijkheid, niet die van het platform.

Structureren en valideren met Pydantic

Het doorgeven van een vrij gevormde dictionary werkt, maar u verliest alle garanties over de inhoud. Voor gestructureerde, gevalideerde parameters vertrouwt u op Pydantic-modellen, die de workflow-interface documenteren én beschermen.

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

Aan de kant van de aanroeper is er niets bijzonders nodig: de velden van het BaseModel worden simpelweg top-level sleutels in de invoerdictionary.

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 valideert ontvangen gegevens automatisch. Als een veld ongeldig is, faalt de workflow onmiddellijk met een expliciete foutmelding, in plaats van de uitvoering te starten en pas drie activiteiten later te crashen. Deze validatie wordt zo streng als nodig: formaatbeperkingen op een e-mailadres, numerieke grenzen op een prioriteit, en bovenal extra = "forbid", wat onbekende velden weigert.

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

    class Config:
        extra = "forbid"  # Weigert onbekende velden

Dit laatste punt verdient aandacht. Zonder extra="forbid" blijft een typefout in een veldnaam onopgemerkt: het verwachte veld neemt zijn standaardwaarde aan en de workflow draait met parameters die niet zijn wat u bedoelde. De fout is stil, en dus kostbaar.

Wanneer één workflow meerdere vormen van invoer moet accepteren, laten union-types u toe deze varianten te beschrijven zonder workflows te vermenigvuldigen.

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"

Levensduur van de uitvoering

Elke workflow heeft een maximale uitvoeringsduur, ingesteld via de parameter execution_timeout. Standaard is dit één uur: na deze deadline wordt de workflow automatisch geannuleerd, ongeacht de voortgang. Voor een proces dat dertig seconden moet duren, is deze waarde comfortabel; voor een nachtelijke pipeline is het een valstrik.

Pas deze time-out aan op de aard van de verwerking, zowel naar beneden als naar boven. Een snel verwerkende workflow heeft baat bij een strakke limiet, omdat een overschrijding dan een echt probleem signaleert in plaats van een tijdelijke vertraging.

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)

Aan de andere kant is het toegestane maximum 7 dagen. Deze duur is alleen zinvol voor processen die wachten op een externe gebeurtenis, typisch menselijke validatie: een rapport dat automatisch wordt verzameld maar ondertekend moet worden door een manager die pas volgende week terugkomt van verlof.

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:
        # Deze workflow kan tot 7 dagen duren
        # Nuttig voor processen met wachttijden voor menselijke tussenkomst
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Gebruik voor de kalibratie deze orde van grootte per gebruiksfamilie.

Use caseAanbevolen time-out
Real-time verwerking1-5 minuten
Data-pipeline15-60 minuten
Genereren van complexe rapporten1-4 uur
Workflow met menselijke validatie1-7 dagen

Twee time-out niveaus die u niet mag verwarren

execution_timeout begrenst de volledige workflow; start_to_close_timeout begrenst een enkele activiteit. De twee bestaan naast elkaar en vullen elkaar aan: de eerste beschermt u tegen een workflow die nooit voltooid wordt, de tweede tegen een activiteit die blijft hangen op een stille service. Merk in het onderstaande voorbeeld op dat de time-out van de HTTP-client (240 seconden) bewust lager is dan de start_to_close_timeout (5 minuten), zodat de fout netjes boven water komt voordat het platform de verbinding verbreekt.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Deze activiteit heeft 5 minuten om te voltooien
    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:
        # De volledige workflow heeft 2 uur
        # Maar elke individuele activiteit heeft zijn eigen time-out
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Eén laatste reflex voor uw inputs: houd ze licht. De limiet is 2 MB, en niets dwingt u om deze te benaderen. Geef de URL van een document door in plaats van de inhoud, een bestel-ID in plaats van de volledige bestelling, en laat de activiteiten de data ophalen. Definieer standaardwaarden voor alles wat optioneel is, documenteer elk veld met Field(description="..."), en vertrouw de validatie toe aan Pydantic in plaats van aan if-statements die door de workflow verspreid staan.

Belangrijkste punten

  • Workflow-invoer moet JSON-serialiseerbaar zijn (str, int, float, bool, list, dict)
  • Gebruik Pydantic BaseModel voor gestructureerde invoer met automatische validatie
  • De standaard time-out is 1 uur, configureerbaar tot maximaal 7 dagen
  • Onderscheid de time-out van de workflow (execution_timeout) van die van de activiteit (start_to_close_timeout)
  • Houd inputs licht: ID’s en URL’s in plaats van grote ruwe data