Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Opret en aktivitet

Lektion 4 af 14 Opdateret 2. november 2026 Avanceret
På denne side
  1. Hvad er en aktivitet?
  2. Anatomien af en aktivitet
  3. Konkrete eksempler på aktiviteter
  4. Kernekarakteristika
  5. Navngivning af en aktivitet
  6. Størrelsesbegrænsninger
  7. Vigtige pointer

Hvad er en aktivitet?

En aktivitet er den grundlæggende operative enhed i et workflow. Det er her, det egentlige arbejde finder sted: eksterne API-kald, databaseforespørgsler, udsendelse af e-mails, filbehandling og kald til AI-modeller. Arbejdsdelingen er enkel og vil fungere som dit kompas gennem dette kursus: Enhver operation, der involverer input/output (I/O) eller bivirkninger, skal kapsles ind i en aktivitet.

Mens workflow’et orchestrerer, udfører aktiviteten. Dette er den fundamentale forskel, og den har en direkte konsekvens: Fordi risikabelt arbejde er isoleret inden for aktiviteter, kan motoren genprøve, måle og afspille uden nogensinde at duplikere bivirkninger.

Anatomien af en aktivitet

En aktivitet er en Python async-funktion dekoreret med @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()

Fire elementer i disse få linjer fortjener din opmærksomhed. Dekoratøren @workflows.activity() registrerer funktionen som en aktivitet hos motoren, hvilket gør den kaldbar fra et workflow. async def er obligatorisk: Alle aktiviteter skal være asynkrone, uden undtagelse. Parametre skal være JSON-serialiserbare, hvilket betyder simple typer – str, int, float, bool, list, dict – eller Pydantic-modeller; det vil fejle at sende et forbindelsesobjekt eller et filhåndtag som argument. Den samme regel gælder for returværdien, som rejser på tværs af netværket, før den skrives til hændelsesloggen.

Konkrete eksempler på aktiviteter

Det første tilfælde, som sandsynligvis er det mest almindelige i dette kursus, kapsler et kald til en Mistral-model. Bemærk, at aktiviteten også returnerer token-forbrug: Når dette først er i loggen, giver denne type metadata dig mulighed for at rekonstruere omkostningerne ved en eksekvering i eftertid.

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
    }

Det andet tilfælde illustrerer databaseadgang. Blokken try/finally er ikke dekorativ: Hvis aktiviteten fejler og genprøves, vil det at efterlade en forbindelse åben ved hvert forsøg hurtigt udtømme PostgreSQL-puljen.

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()

Det tredje tilfælde, udsendelse af e-mail, er hvor bivirkninger er mest synlige: Når beskeden først er sendt, kan ingen genprøvning fange den.

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}

Kernekarakteristika

For det første en velkommen frihed: I modsætning til workflow’er har aktiviteter ingen determinisme-begrænsninger. Du kan frit bruge datetime.now(), uuid.uuid4(), random.random() eller ethvert andet ikke-deterministisk kald inde i en aktivitet. Det er præcis, hvad aktiviteter er til – at absorbere alt det, som workflow’et ikke må gøre.

Platformen behandler derefter hvert aktivitetskald som en atomar enhed: Det lykkes enten fuldt ud eller fejler fuldt ud, uden nogen mellemliggende tilstand synlig for workflow’et. Hvis din aktivitet gør tre ting, og den anden crashe, ser workflow’et kun en fejl, ikke en delvis succes. Derfor bør du undgå at stable fem forskellige operationer ind i en enkelt funktion.

Når en aktivitet er gennemført, bliver dens resultat permanent registreret i workflow’ets hændelseslog. Under en afspilning bliver aktiviteten aldrig genudført: Kun det registrerede resultat bruges. Til gengæld, fordi en aktivitet kan blive genprøvet ved fejl – netværkstimeout, forbigående fejl – skal den være idempotent: Ved udførelse flere gange med de samme parametre skal den producere det samme resultat. At skifte fra et POST til et PUT på en stabil identifikator er ofte nok til at opnå denne egenskab, som her hvor e-mailen fungerer som nøgle:

@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()

Dekoratøren accepterer et eksplicit navn, hvilket forbedrer læsbarheden af sporingen betydeligt, når en teknisk funktion bærer et engelsk navn, som ingen andre på teamet kobler til forretningsdomænet:

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

Dette navn vil fremgå af OpenTelemetry-sporinger og lette fejlsøgningen. Gør det til en vane at sætte det fra starten: Den dag du jagter årsagen til, at en eksekvering tog fyrre minutter, vil du læse meningsfulde labels i stedet for en liste over funktionsnavne.

Størrelsesbegrænsninger

To grænser styrer udvekslinger: Maksimum 2 MB for inputparametre og maksimum 2 MB for returværdien. Disse stammer direkte fra event sourcing, da disse værdier serialiseres og gemmes i loggen.

Den praktiske konsekvens er klar. Hvis du skal behandle store filer – en scannet PDF på 40 MB, et eksportarkiv – så send dem ikke fra aktivitet til aktivitet. Gem dem i en ekstern tjeneste (S3, GCS) og cirkulér kun URL’en eller identifikatoren: Aktiviteten downloader filen, behandler den, skriver resultatet tilbage til lageret og returnerer en reference på få hundrede bytes.

Vigtige pointer

  • En aktivitet er en async-funktion dekoreret med @workflows.activity(), der udfører det egentlige arbejde (I/O, API, DB)
  • Parametre og returværdier skal være JSON-serialiserbare
  • Aktiviteter har ingen determinisme-begrænsninger
  • En succesfuld aktivitet bliver aldrig genudført under en afspilning
  • Aktiviteter skal være idempotente (samme resultat hvis udført flere gange)
  • Grænse på 2 MB for input og output pr. aktivitet