Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vytvoření aktivity

Lekce 4 z 14 Aktualizováno 2. listopadu 2026 Pokročilý
Na této stránce
  1. Co je to aktivita?
  2. Anatomie aktivity
  3. Konkrétní příklady aktivit
  4. Klíčové vlastnosti
  5. Pojmenování aktivity
  6. Omezení velikosti
  7. Klíčové poznatky

Co je to aktivita?

Aktivita je základní operační jednotka ve workflow. Právě zde probíhá skutečná práce: volání externích API, dotazy do databáze, odesílání e-mailů, zpracování souborů a volání modelů umělé inteligence. Rozdělení práce je jednoduché a bude ti sloužit jako kompas během celého kurzu: jakákoli operace zahrnující vstup/výstup (I/O) nebo vedlejší efekty musí být zapouzdřena v aktivitě.

Zatímco workflow orchestruje, aktivita vykonává. To je zásadní rozdíl, který má přímý důsledek: protože je riziková práce izolována uvnitř aktivit, engine může opakovat pokusy, měřit a přehrávat, aniž by kdy zdvojil vedlejší efekty.

Anatomie aktivity

Aktivita je Python funkce async označená dekorátorem @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()

Čtyři prvky v těchto několika řádcích si zaslouží tvou pozornost. Dekorátor @workflows.activity() registruje funkci jako aktivitu u enginu, což ji činí volatelnou z workflow. Klíčové slovo async def je povinné: všechny aktivity musí být asynchronní, bez výjimky. Parametry musí být serializovatelné do JSON, což znamená jednoduché typy – str, int, float, bool, list, dict – nebo modely Pydantic; předání objektu připojení nebo popisovače souboru jako argumentu selže při serializaci. Stejné pravidlo platí pro návratovou hodnotu, která putuje přes síť, než je zapsána do logu událostí.

Konkrétní příklady aktivit

První případ, pravděpodobně nejčastější v tomto kurzu, zapouzdřuje volání modelu Mistral. Všimni si, že aktivita také vrací spotřebu tokenů: jakmile je tato metadata v logu, umožňuje ti dodatečně rekonstruovat náklady na provedení.

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
    }

Druhý případ ilustruje přístup k databázi. Blok try/finally není jen ozdobný: pokud aktivita selže a je zopakována, ponechání otevřeného připojení při každém pokusu rychle vyčerpá pool PostgreSQL.

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

Třetí případ, odesílání e-mailu, je místem, kde jsou vedlejší efekty nejviditelnější: jakmile je zpráva odeslána, žádný opakovaný pokus ji nemůže zachytit.

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}

Klíčové vlastnosti

Zaprvé, vítaná svoboda: na rozdíl od workflow nemají aktivity žádná omezení determinismu. Uvnitř aktivity můžeš volně používat datetime.now(), uuid.uuid4(), random.random() nebo jakékoli jiné nedeterministické volání. Přesně k tomu slouží aktivity – absorbují vše, co workflow dělat nesmí.

Platforma pak zachází s každým voláním aktivity jako s atomickou jednotkou: buď zcela uspěje, nebo zcela selže, přičemž workflow nevidí žádný mezistav. Pokud tvoje aktivita udělá tři věci a druhá z nich spadne, workflow vidí pouze selhání, nikoli částečný úspěch. Proto bys se měl vyvarovat skládání pěti různých operací do jedné funkce.

Jakmile aktivita uspěje, její výsledek je trvale zaznamenán v logu událostí workflow. Během přehrávání se aktivita nikdy znovu neprovede: použije se pouze zaznamenaný výsledek. Na oplátku, protože může být aktivita při selhání zopakována (časový limit sítě, přechodná chyba), musí být idempotentní: při několikanásobném provedení se stejnými parametry musí produkovat stejný výsledek. Přechod z POST na PUT na stabilním identifikátoru často stačí k dosažení této vlastnosti, jako zde, kde e-mail slouží jako klíč:

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

Pojmenování aktivity

Dekorátor přijímá explicitní název, což výrazně zlepšuje čitelnost trasování, když technická funkce nese anglický název, který nikdo jiný v týmu nespojuje s business doménou:

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

Tento název se objeví v trasách OpenTelemetry a usnadní ladění. Zvykni si nastavovat jej od začátku: v den, kdy budeš pátrat po důvodu, proč provedení trvalo čtyřicet minut, budeš číst smysluplné štítky namísto seznamu názvů funkcí.

Omezení velikosti

Výměnu dat řídí dva limity: maximálně 2 MB pro vstupní parametry a maximálně 2 MB pro návratovou hodnotu. Tyto limity přímo vyplývají ze zdrojování událostí (event sourcing), protože tyto hodnoty jsou serializovány a uloženy v logu.

Praktický důsledek je jasný. Pokud potřebuješ zpracovávat velké soubory – 40MB naskenované PDF, exportní archiv – nepředávej je z aktivity do aktivity. Ulož je do externí služby (S3, GCS) a obíhej pouze URL nebo identifikátor: aktivita soubor stáhne, zpracuje jej, zapíše výsledek zpět do úložiště a vrátí odkaz o velikosti několika set bajtů.

Klíčové poznatky

  • Aktivita je funkce async označená dekorátorem @workflows.activity(), která vykonává skutečnou práci (I/O, API, DB)
  • Parametry a návratové hodnoty musí být serializovatelné do JSON
  • Aktivity nemají žádná omezení determinismu
  • Úspěšná aktivita se během přehrávání nikdy znovu neprovede
  • Aktivity musí být idempotentní (stejný výsledek při několikanásobném provedení)
  • Limit 2 MB pro vstup a výstup na jednu aktivitu