Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Een activiteit maken

Les 4 van 14 Bijgewerkt op 2 november 2026 Gevorderd
Op deze pagina
  1. Wat is een activiteit?
  2. Anatomie van een activiteit
  3. Concrete voorbeelden van activiteiten
  4. Kernkenmerken
  5. Een activiteit een naam geven
  6. Groottebeperkingen
  7. Belangrijkste punten

Wat is een activiteit?

Een activiteit is de basisoperationele eenheid binnen een workflow. Hier vindt het eigenlijke werk plaats: externe API-aanroepen, databasequery’s, het verzenden van e-mails, bestandsverwerking en aanroepen naar AI-modellen. De taakverdeling is eenvoudig en dient als uw kompas tijdens deze cursus: elke bewerking die input/output (I/O) of neveneffecten met zich meebrengt, moet worden ondergebracht in een activiteit.

Terwijl de workflow orchestreert, voert de activiteit uit. Dit is het fundamentele onderscheid, met een direct gevolg: omdat risicovol werk geïsoleerd is binnen activiteiten, kan de engine opnieuw proberen, meten en afspelen zonder ooit neveneffecten te dupliceren.

Anatomie van een activiteit

Een activiteit is een Python async-functie die is voorzien van het decorateur @workflows.activity():

import mistralai.workflows as workflows

@workflows.activity()
async def get_user_profile(user_id: str) -> dict:
    """Retrieves a user profile from the API."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        response.raise_for_status()
        return response.json()

Vier elementen in deze paar regels verdienen uw aandacht. Het decorateur @workflows.activity() registreert de functie als een activiteit bij de engine, waardoor deze vanuit een workflow kan worden aangeroepen. De async def is verplicht: alle activiteiten moeten asynchroon zijn, zonder uitzondering. Parameters moeten JSON-serialiseerbaar zijn, wat betekent dat het gaat om eenvoudige typen—str, int, float, bool, list, dict—of Pydantic-modellen; het doorgeven van een connectieobject of bestandshandle als argument zal de serialisatie doen mislukken. Dezelfde regel geldt voor de retourwaarde, die via het netwerk reist voordat deze naar het gebeurtenislogboek wordt geschreven.

Concrete voorbeelden van activiteiten

Het eerste geval, waarschijnlijk het meest voorkomende in deze cursus, kapselt een aanroep naar een Mistral-model in. Merk op dat de activiteit ook het tokenverbruik retourneert: eenmaal in het logboek stelt dit soort metadata u in staat om achteraf de kosten van een uitvoering te reconstrueren.

import mistralai.workflows as workflows
from mistralai.client import Mistral

@workflows.activity()
async def generate_summary(text: str) -> dict:
    """Generates a summary of the provided text via Mistral."""
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "You are an assistant specialized in text summarization."},
            {"role": "user", "content": f"Summarize this text in 3 sentences:\n\n{text}"}
        ]
    )
    return {
        "summary": response.choices[0].message.content,
        "tokens_used": response.usage.total_tokens
    }

Het tweede geval illustreert databanktoegang. Het try/finally-blok is niet louter decoratief: als de activiteit faalt en opnieuw wordt geprobeerd, zal het bij elke poging openlaten van een verbinding de PostgreSQL-pool snel uitputten.

import mistralai.workflows as workflows
import asyncpg

@workflows.activity()
async def save_report(report: dict) -> dict:
    """Saves a report to PostgreSQL."""
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "INSERT INTO reports (title, content, created_at) VALUES ($1, $2, NOW()) RETURNING id",
            report["title"],
            report["content"]
        )
        return {"id": row["id"], "status": "saved"}
    finally:
        await conn.close()

Het derde geval, het verzenden van e-mail, is waar neveneffecten het meest zichtbaar zijn: zodra het bericht is verzonden, kan geen enkele nieuwe poging dit nog ondervangen.

import mistralai.workflows as workflows
import aiosmtplib

@workflows.activity()
async def send_notification(recipient: str, subject: str, body: str) -> dict:
    """Sends a notification email."""
    message = f"Subject: {subject}\nTo: {recipient}\n\n{body}"
    await aiosmtplib.send(
        message,
        hostname="smtp.example.com",
        port=587,
        username="[email protected]",
        password="secret",
        use_tls=True
    )
    return {"status": "sent", "recipient": recipient}

Kernkenmerken

Ten eerste een welkome vrijheid: in tegenstelling tot workflows hebben activiteiten geen determinismebeperkingen. U kunt vrijelijk datetime.now(), uuid.uuid4(), random.random() of elke andere niet-deterministische aanroep binnen een activiteit gebruiken. Dat is precies waar activiteiten voor dienen—alles opvangen wat de workflow niet mag doen.

Het platform behandelt elke activiteitsaanroep vervolgens als een atomische eenheid: deze slaagt volledig of faalt volledig, zonder dat er een tussenliggende staat zichtbaar is voor de workflow. Als uw activiteit drie dingen doet en de tweede crasht, ziet de workflow alleen een mislukking, geen gedeeltelijk succes. Dit is de reden waarom u moet vermijden om vijf verschillende bewerkingen in één enkele functie te stapelen.

Zodra een activiteit succesvol is, wordt het resultaat permanent vastgelegd in het gebeurtenislogboek van de workflow. Tijdens een replay wordt de activiteit nooit opnieuw uitgevoerd: alleen het vastgelegde resultaat wordt gebruikt. Als tegenprestatie moet een activiteit, omdat deze bij een mislukking opnieuw kan worden geprobeerd—netwerktime-out, tijdelijke fout—idempotent zijn: meerdere keren uitgevoerd met dezelfde parameters, moet deze hetzelfde resultaat opleveren. De overstap van een POST naar een PUT op een stabiele identifier is vaak voldoende om deze eigenschap te bereiken, zoals hier waar het e-mailadres als sleutel dient:

@workflows.activity()
async def create_or_update_client(email: str, name: str) -> dict:
    """Idempotent: uses an upsert instead of an insert."""
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://api.crm.com/clients/{email}",
            json={"name": name, "email": email}
        )
        return response.json()

Een activiteit een naam geven

Het decorateur accepteert een expliciete naam, wat de leesbaarheid van traces aanzienlijk verbetert wanneer een technische functie een Engelse naam draagt die niemand anders in het team linkt aan het bedrijfsdomein:

@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
    # ...
    pass

Deze naam verschijnt in OpenTelemetry-traces en vergemakkelijkt het debuggen. Maak er een gewoonte van om dit vanaf het begin in te stellen: op de dag dat u probeert uit te zoeken waarom een uitvoering veertig minuten duurde, leest u betekenisvolle labels in plaats van een lijst met functienamen.

Groottebeperkingen

Twee limieten beheersen de uitwisselingen: maximaal 2 MB voor inputparameters en maximaal 2 MB voor de retourwaarde. Deze vloeien rechtstreeks voort uit event sourcing, aangezien deze waarden worden geserialiseerd en in het logboek worden opgeslagen.

Het praktische gevolg is duidelijk. Als u grote bestanden moet verwerken—een gescande PDF van 40 MB, een exportarchief—geef deze dan niet door van activiteit naar activiteit. Sla ze op in een externe service (S3, GCS) en circuleer alleen de URL of identifier: de activiteit downloadt het bestand, verwerkt het, schrijft het resultaat terug naar de opslag en retourneert een referentie van enkele honderden bytes.

Belangrijkste punten

  • Een activiteit is een async-functie met het decorateur @workflows.activity() die het eigenlijke werk uitvoert (I/O, API, DB)
  • Parameters en retourwaarden moeten JSON-serialiseerbaar zijn
  • Activiteiten hebben geen determinismebeperkingen
  • Een geslaagde activiteit wordt nooit opnieuw uitgevoerd tijdens een replay
  • Activiteiten moeten idempotent zijn (hetzelfde resultaat bij meerdere uitvoeringen)
  • Limiet van 2 MB op input en output per activiteit