Salt la conținutul principal
Română— Alege o limbă
Meniu

Crearea unei activități

Lecția 4 din 14 Actualizată 2 noiembrie 2026 Avansat
Pe această pagină
  1. Ce este o activitate?
  2. Anatomia unei activități
  3. Exemple concrete de activități
  4. Caracteristici esențiale
  5. Denumirea unei activități
  6. Constrângeri de dimensiune
  7. Puncte cheie

Ce este o activitate?

O activitate reprezintă unitatea operațională de bază într-un flux de lucru. Aici are loc munca propriu-zisă: apeluri către API-uri externe, interogări de baze de date, trimiterea de e-mailuri, procesarea fișierelor și apeluri către modele de inteligență artificială. Diviziunea muncii este simplă și vă va servi drept busolă pe tot parcursul acestui curs: orice operațiune care implică intrări/ieșiri (I/O) sau efecte secundare trebuie encapsulată într-o activitate.

În timp ce fluxul de lucru orchestrează, activitatea execută. Aceasta este distincția fundamentală, iar ea are o consecință directă: deoarece munca riscantă este izolată în interiorul activităților, motorul poate reîncerca, măsura și reda execuția fără a duplica vreodată efectele secundare.

Anatomia unei activități

O activitate este o funcție Python async decorată cu @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()

Patru elemente din aceste câteva linii merită atenția dumneavoastră. Decoratorul @workflows.activity() înregistrează funcția ca activitate în motor, făcând-o apelabilă dintr-un flux de lucru. Sintaxa async def este obligatorie: toate activitățile trebuie să fie asincrone, fără excepție. Parametrii trebuie să fie serializabili în JSON, adică tipuri simple—str, int, float, bool, list, dict—sau modele Pydantic; transmiterea unui obiect de conexiune sau a unui descriptor de fișier ca argument va eșua la serializare. Aceeași regulă se aplică valorii returnate, care traversează rețeaua înainte de a fi scrisă în jurnalul de evenimente.

Exemple concrete de activități

Primul caz, probabil cel mai frecvent în acest curs, encapsulează un apel către un model Mistral. Rețineți că activitatea returnează, de asemenea, consumul de token-uri: odată înregistrat în jurnal, acest tip de metadate vă permite să reconstruiți costul unei execuții după fapt.

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
    }

Al doilea caz ilustrează accesul la baza de date. Blocul try/finally nu este decorativ: dacă activitatea eșuează și este reîncercată, lăsarea unei conexiuni deschise la fiecare tentativă va epuiza rapid pool-ul 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()

Al treilea caz, trimiterea de e-mailuri, este locul unde efectele secundare sunt cele mai vizibile: odată mesajul trimis, nicio reîncercare nu îl mai poate intercepta.

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}

Caracteristici esențiale

În primul rând, o libertate binevenită: spre deosebire de fluxurile de lucru, activitățile nu au constrângeri de determinism. Puteți utiliza liber datetime.now(), uuid.uuid4(), random.random() sau orice alt apel non-determinist în interiorul unei activități. Exact acesta este rolul activităților—să absoarbă tot ceea ce fluxul de lucru nu are voie să facă.

Platforma tratează apoi fiecare apel de activitate ca o unitate atomică: fie reușește în totalitate, fie eșuează în totalitate, fără ca fluxul de lucru să vadă vreo stare intermediară. Dacă activitatea dumneavoastră face trei lucruri, iar al doilea se blochează, fluxul de lucru vede doar o eroare, nu un succes parțial. De aceea, ar trebui să evitați stivuirea a cinci operațiuni distincte într-o singură funcție.

Odată ce o activitate reușește, rezultatul său este înregistrat permanent în jurnalul de evenimente al fluxului de lucru. În timpul unei redări (replay), activitatea nu este niciodată reexecutată: se utilizează doar rezultatul înregistrat. În schimb, deoarece o activitate poate fi reîncercată în caz de eșec—timeout de rețea, eroare tranzitorie—aceasta trebuie să fie idempotentă: executată de mai multe ori cu aceiași parametri, trebuie să producă același rezultat. Trecerea de la un POST la un PUT pe un identificator stabil este adesea suficientă pentru a obține această proprietate, așa cum se întâmplă aici, unde e-mailul servește drept cheie:

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

Denumirea unei activități

Decoratorul acceptă un nume explicit, ceea ce îmbunătățește semnificativ lizibilitatea urmăririi (tracing) atunci când o funcție tehnică poartă un nume în engleză pe care nimeni altcineva din echipă nu îl asociază cu domeniul de activitate:

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

Acest nume va apărea în trace-urile OpenTelemetry și va facilita depanarea. Faceți din aceasta un obicei de la început: în ziua în care veți investiga de ce o execuție a durat patruzeci de minute, veți citi etichete semnificative, nu o listă de nume de funcții.

Constrângeri de dimensiune

Două limite guvernează schimburile de date: maximum 2 MB pentru parametrii de intrare și maximum 2 MB pentru valoarea returnată. Acestea decurg direct din principiul „event sourcing“, deoarece aceste valori sunt serializate și stocate în jurnal.

Consecința practică este clară. Dacă trebuie să procesați fișiere mari—un PDF scanat de 40 MB, o arhivă de export—nu le transmiteți de la o activitate la alta. Stocați-le într-un serviciu extern (S3, GCS) și circulați doar URL-ul sau identificatorul: activitatea descarcă fișierul, îl procesează, scrie rezultatul înapoi în stocare și returnează o referință de câteva sute de octeți.

Puncte cheie

  • O activitate este o funcție async decorată cu @workflows.activity() care efectuează munca reală (I/O, API, BD)
  • Parametrii și valorile returnate trebuie să fie serializabili în JSON
  • Activitățile nu au constrângeri de determinism
  • O activitate reușită nu este niciodată reexecutată în timpul unei redări
  • Activitățile trebuie să fie idempotente (același rezultat dacă sunt executate de mai multe ori)
  • Limită de 2 MB pentru intrări și ieșiri per activitate