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

Skapa en aktivitet

Lektion 4 av 14 Uppdaterad 2 november 2026 Avancerad
På denna sida
  1. Vad är en aktivitet?
  2. En aktivitets anatomi
  3. Konkreta exempel på aktiviteter
  4. Kärnegenskaper
  5. Namnge en aktivitet
  6. Storleksbegränsningar
  7. Viktiga punkter

Vad är en aktivitet?

En aktivitet är den grundläggande operativa enheten i ett arbetsflöde. Det är här det faktiska arbetet utförs: anrop till externa API:er, databasfrågor, utskick av e-post, filhantering och anrop till AI-modeller. Arbetsfördelningen är enkel och kommer att fungera som din kompass genom hela denna kurs: varje operation som involverar in/ut-data (I/O) eller sidoeffekter måste kapslas in i en aktivitet.

Medan arbetsflödet orkestrerar, exekverar aktiviteten. Detta är den fundamentala skillnaden, och den har en direkt konsekvens: eftersom riskfyllt arbete isoleras inom aktiviteter kan motorn försöka igen, mäta och spela upp utan att någonsin duplicera sidoeffekter.

En aktivitets anatomi

En aktivitet är en Python-funktion async dekorerad 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()

Fyra element i dessa få rader förtjänar din uppmärksamhet. Dekoratorn @workflows.activity() registrerar funktionen som en aktivitet hos motorn, vilket gör den anropbar från ett arbetsflöde. async def är obligatoriskt: alla aktiviteter måste vara asynkrona, utan undantag. Parametrar måste vara JSON-serialiserbara, vilket innebär enkla typer – str, int, float, bool, list, dict – eller Pydantic-modeller; att skicka ett anslutningsobjekt eller filhandtag som argument kommer att misslyckas vid serialiseringen. Samma regel gäller för returvärdet, som färdas över nätverket innan det skrivs till händelseloggen.

Konkreta exempel på aktiviteter

Det första fallet, sannolikt det vanligaste i denna kurs, kapslar in ett anrop till en Mistral-modell. Observera att aktiviteten också returnerar tokenanvändning: när detta väl finns i loggen låter denna typ av metadata dig rekonstruera kostnaden för en exekvering i efterhand.

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 andra fallet illustrerar databåsåtkomst. Blocket try/finally är inte dekorativt: om aktiviteten misslyckas och försöks igen, kommer en öppen anslutning vid varje försök snabbt att tömma PostgreSQL-poolen.

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 fallet, att skicka e-post, är där sidoeffekter är mest synliga: när meddelandet väl har skickats kan inget nytt försök fånga upp det.

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}

Kärnegenskaper

Först, en välkommen frihet: till skillnad från arbetsflöden har aktiviteter inga determinismkrav. Du kan fritt använda datetime.now(), uuid.uuid4(), random.random() eller vilket annat icke-deterministiskt anrop som helst inuti en aktivitet. Det är precis vad aktiviteter är till för – att absorbera allt som arbetsflödet inte får göra.

Plattformen behandlar sedan varje aktivitetsanrop som en atomär enhet: det lyckas antingen helt eller misslyckas helt, utan något mellanliggande tillstånd synligt för arbetsflödet. Om din aktivitet gör tre saker och den andra kraschar, ser arbetsflödet bara ett misslyckande, inte en partiell framgång. Därför bör du undvika att stapla fem distinkta operationer i en enda funktion.

När en aktivitet har lyckats registreras dess resultat permanent i arbetsflödets händelselogg. Under en uppspelning exekveras aldrig aktiviteten igen: endast det registrerade resultatet används. I gengäld, eftersom en aktivitet kan försökas igen vid misslyckande – nätverkstidsöverskridning, övergående fel – måste den vara idempotent: vid flera körningar med samma parametrar måste den producera samma resultat. Att byta från en POST till en PUT på en stabil identifierare räcker ofta för att uppnå denna egenskap, som här där e-postadressen fungerar som nyckel:

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

Namnge en aktivitet

Dekoratorn accepterar ett explicit namn, vilket avsevärt förbättrar läsbarheten i spårningen när en teknisk funktion bär ett engelskt namn som ingen annan i teamet kopplar till affärsdomänen:

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

Detta namn kommer att visas i OpenTelemetry-spår och underlätta felsökning. Gör det till en vana att ange det från början: den dag du jagar varför en exekvering tog fyrtio minuter kommer du att läsa meningsfulla etiketter istället för en lista med funktionsnamn.

Storleksbegränsningar

Två gränser styr utbytet: max 2 MB för inparametrar och max 2 MB för returvärdet. Dessa härrör direkt från event sourcing, eftersom dessa värden serialiseras och lagras i loggen.

Den praktiska konsekvensen är tydlig. Om du behöver bearbeta stora filer – en skannad PDF på 40 MB, ett exportarkiv – ska du inte skicka dem från aktivitet till aktivitet. Lagra dem i en extern tjänst (S3, GCS) och cirkulera endast URL:en eller identifieraren: aktiviteten laddar ner filen, bearbetar den, skriver tillbaka resultatet till lagringen och returnerar en referens på några hundra byte.

Viktiga punkter

  • En aktivitet är en async-funktion dekorerad med @workflows.activity() som utför det faktiska arbetet (I/O, API, DB)
  • Parametrar och returvärden måste vara JSON-serialiserbara
  • Aktiviteter har inga determinismkrav
  • En lyckad aktivitet exekveras aldrig igen under en uppspelning
  • Aktiviteter måste vara idempotenta (samma resultat vid flera körningar)
  • Gräns på 2 MB för in- och utdata per aktivitet