Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Async e migliori pratiche

Lezione 13 di 14 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. I/O asincrono: un requisito tecnico
  2. Scegli librerie nativamente asincrone
  3. Quando non esiste una versione Async
  4. Progettare attività pulite
  5. Punti chiave

I/O asincrono: un requisito tecnico

Tutte le attività in Mistral Workflows devono utilizzare operazioni di input/output asincrone. Non si tratta di una raccomandazione di stile, ma di un vincolo tecnico. Una chiamata sincrona bloccante come requests.post() congela il worker e impedisce l’esecuzione di qualsiasi altra attività.

Questo requisito deriva dall’architettura del worker, che esegue le attività all’interno di un event loop asyncio. Quando una coroutine attende asincronamente una risposta di rete, cede il controllo al loop, permettendo ad altre attività di procedere. Al contrario, una chiamata sincrona non cede nulla.

import requests

# ERRATO: Blocca l'intero worker
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() è sincrono — blocca l'event loop
    response = requests.post(url, json={"query": "test"})
    return response.json()

Il sintomo in produzione può essere confuso: lanci dieci attività in parallelo con asyncio.gather, ma queste vengono eseguite effettivamente una dopo l’altra. Se ciascuna attende due secondi per un’API remota, misuri venti secondi invece dei due previsti, senza che venga sollevato alcun errore.

Scegli librerie nativamente asincrone

La soluzione consiste nel sostituire ogni libreria bloccante con la sua equivalente asincrona. Per le chiamate HTTP, httpx è la scelta predefinita.

import httpx

# CORRETTO: Non bloccante
@workflows.activity()
async def async_activity(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(url, json={"query": "test"})
    return response.json()

aiohttp svolge la stessa funzione con un’API leggermente diversa basata sulle sessioni.

import aiohttp

@workflows.activity()
async def aiohttp_activity(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json={"query": "test"}) as response:
            return await response.json()

Per i database, asyncpg sostituisce psycopg2 per PostgreSQL. Nota il blocco try/finally: la connessione deve essere chiusa anche se la query solleva un’eccezione. Altrimenti, i tentativi successivi esauriranno il pool di connessioni.

import asyncpg

# CORRETTO: Driver PostgreSQL asincrono
@workflows.activity()
async def async_db_query(user_id: str) -> dict:
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "SELECT * FROM users WHERE id = $1", user_id
        )
        return dict(row) if row else {"error": "user not found"}
    finally:
        await conn.close()

L’accesso ai file segue la stessa logica con aiofiles, anche per file piccoli dove potresti essere tentato di continuare a usare open().

import aiofiles

# CORRETTO: Lettura file asincrona
@workflows.activity()
async def read_file_async(path: str) -> dict:
    async with aiofiles.open(path, mode="r") as f:
        content = await f.read()
    return {"content": content, "size": len(content)}

Nemmeno l’SDK Mistral fa eccezione: ogni metodo ha una variante con suffisso _async, ed è quella che devi chiamare da un’attività.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Usa complete_async, NON complete
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )
    return {"response": response.choices[0].message.content}

Tieni a portata di mano questa tabella di corrispondenza durante le revisioni del codice: qualsiasi riga della colonna di sinistra individuata in un’attività rappresenta un potenziale bug di prestazioni.

OperazioneErrato (bloccante)Corretto (async)
HTTPrequests.get()httpx.AsyncClient().get()
HTTPurllib.request.urlopen()aiohttp.ClientSession().get()
PostgreSQLpsycopg2.connect()asyncpg.connect()
MySQLmysql.connector.connect()aiomysql.connect()
Redisredis.Redis()redis.asyncio.Redis()
Fileopen()aiofiles.open()
Sleeptime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Quando non esiste una versione Async

Alcune librerie di business, come un SDK proprietario o un client legacy, semplicemente non offrono una variante asincrona. In questi casi, asyncio.to_thread() ti permette di eseguire il codice bloccante in un thread separato senza congelare l’event loop.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Avvolge una chiamata bloccante in un thread."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Questo è un compromesso, non una soluzione equivalente: ogni chiamata consuma un thread dal pool, che ha una dimensione finita. Per un’attività chiamata massicciamente in parallelo, sposti semplicemente il collo di bottiglia invece di rimuoverlo. Preferisci sempre una libreria nativamente asincrona quando ne esiste una.

Progettare attività pulite

Oltre all’asincronia, quattro abitudini distinguono un’attività robusta da una che ti costerà ore di debug.

La prima è l’ambito. Un’attività dovrebbe avere una e una sola responsabilità, poiché è anche l’unità di retry e persistenza: un’attività “tuttofare” che fallisce durante l’invio di un’email ripeterà dall’inizio l’estrazione e l’analisi.

# BUONO: Ogni attività ha una responsabilità chiara
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
    # ...
    pass

# CATTIVO: Attività tuttofare
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # estrazione
    sentiment = ...  # analisi
    # invia email
    # salva su DB
    pass

La seconda riguarda le risorse. Il context manager async with garantisce che il client venga chiuso anche se si verifica un’eccezione, qualcosa che le chiamate manuali inevitabilmente dimenticano prima o poi.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Usa async with per garantire la chiusura
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Il client viene chiuso automaticamente qui
    return response.json()

La terza è più sottile: non tutti gli errori meritano un retry. Un timeout, un 429 o un 500 sono transitori e dovrebbero propagarsi per attivare un nuovo tentativo. Un errore 4xx, invece, indica una richiesta non valida che ripetere tre volte non risolverà. Invece, restituisci un risultato esplicito e lascia che il workflow decida.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2),
    retry_policy_max_attempts=3,
)
async def robust_activity(params: dict) -> dict:
    async with httpx.AsyncClient(timeout=60) as client:
        try:
            response = await client.post(params["url"], json=params["data"])
            response.raise_for_status()
            return {"status": "success", "data": response.json()}
        except httpx.TimeoutException:
            raise  # Verrà ritentato dalla piattaforma
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Limite di frequenza raggiunto — verrà ritentato
            elif e.response.status_code >= 500:
                raise  # Errore server — verrà ritentato
            else:
                # Errore client (4xx) — non ritentare
                return {"status": "error", "code": e.response.status_code}

Infine, la quarta abitudine deriva dal limite di 2 MB per invocazione: restituisci solo ciò di cui il workflow ha effettivamente bisogno per decidere il passo successivo. Un conteggio, un campione e l’URL al risultato completo sono quasi sempre sufficienti.

@workflows.activity()
async def extract_data(source: str) -> dict:
    data = await retrieve_large_data(source)

    # Restituisci solo ciò di cui il workflow ha bisogno
    return {
        "item_count": len(data),
        "summary": data[:10],  # Solo i primi 10
        "full_url": await upload_results(data)
    }

Punti chiave

  • I/O asincrono è obbligatorio: usa httpx, asyncpg, aiofiles invece delle loro controparti sincrone
  • Le chiamate bloccanti (requests, psycopg2, open) congelano l’intero worker
  • Usa asyncio.to_thread() come ultima risorsa per le librerie senza versione asincrona
  • Ogni attività deve avere una responsabilità chiara
  • Chiudi sempre le connessioni con async with
  • Gestisci gli errori in modo esplicito: alcuni vanno ritentati, altri no
  • Limita le dimensioni dei dati restituiti per rimanere sotto il limite di 2 MB