Asincronía y buenas prácticas
En esta página
E/S asíncrona: un requisito técnico
Todas las actividades en Mistral Workflows deben utilizar operaciones de entrada/salida asíncronas. No se trata de una recomendación de estilo, sino de una restricción técnica. Una llamada síncrona bloqueante como requests.post() congela el worker e impide que se ejecute cualquier otra actividad.
Este requisito deriva de la arquitectura del worker, que ejecuta las actividades dentro de un bucle de eventos asyncio. Cuando una corrutina espera una respuesta de red de forma asíncrona, cede el control al bucle, permitiendo que otras actividades continúen. Por el contrario, una llamada síncrona no cede nada.
import requests
# INCORRECTO: Bloquea todo el worker
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() es síncrono — bloquea el bucle de eventos
response = requests.post(url, json={"query": "test"})
return response.json()
El síntoma en producción puede resultar confuso: lanzas diez actividades en paralelo con asyncio.gather, pero en realidad se ejecutan una tras otra. Si cada una espera dos segundos una API remota, medirás veinte segundos en lugar de los dos esperados, sin que se lance ningún error.
Elige bibliotecas nativamente asíncronas
La solución consiste en sustituir cada biblioteca bloqueante por su equivalente asíncrono. Para llamadas HTTP, httpx es la opción predeterminada.
import httpx
# CORRECTO: No bloqueante
@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 cumple la misma función con una API ligeramente diferente basada en sesiones.
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()
Para bases de datos, asyncpg reemplaza a psycopg2 en PostgreSQL. Observa el bloque try/finally: la conexión debe cerrarse incluso si la consulta lanza una excepción. De lo contrario, los reintentos sucesivos agotarán el pool de conexiones.
import asyncpg
# CORRECTO: Controlador asíncrono para PostgreSQL
@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()
El acceso a archivos sigue la misma lógica con aiofiles, incluso para archivos pequeños donde podrías sentir la tentación de seguir usando open().
import aiofiles
# CORRECTO: Lectura asíncrona de archivos
@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)}
El propio SDK de Mistral no es una excepción: cada método tiene una variante con el sufijo _async, y esa es la que debes llamar desde una actividad.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Usa complete_async, NO complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Ten esta tabla de mapeo a mano durante las revisiones de código: cualquier línea de la columna izquierda que aparezca en una actividad es un posible error de rendimiento.
| Operación | Incorrecto (bloqueante) | Correcto (asíncrono) |
|---|---|---|
| HTTP | requests.get() | httpx.AsyncClient().get() |
| HTTP | urllib.request.urlopen() | aiohttp.ClientSession().get() |
| PostgreSQL | psycopg2.connect() | asyncpg.connect() |
| MySQL | mysql.connector.connect() | aiomysql.connect() |
| Redis | redis.Redis() | redis.asyncio.Redis() |
| Archivos | open() | aiofiles.open() |
| Pausa | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Cuando no existe una versión asíncrona
Algunas bibliotecas de negocio, como un SDK propietario o un cliente heredado, simplemente no ofrecen una variante asíncrona. En estos casos, asyncio.to_thread() te permite ejecutar el código bloqueante en un hilo separado sin congelar el bucle de eventos.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Envuelve una llamada bloqueante en un hilo."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Esto es un compromiso, no una solución equivalente: cada llamada consume un hilo del pool, que tiene un tamaño finito. Para una actividad llamada masivamente en paralelo, simplemente desplazas el cuello de botella en lugar de eliminarlo. Prefiere siempre una biblioteca nativamente asíncrona cuando exista.
Diseño de actividades limpias
Más allá de la asincronía, cuatro hábitos distinguen una actividad robusta de una que te costará horas de depuración.
El primero es el alcance. Una actividad debe tener una y solo una responsabilidad, porque también es la unidad de reintento y persistencia: una actividad comodín que falla al enviar un correo electrónico repetirá la extracción y el análisis desde el principio.
# BUENO: Cada actividad tiene una responsabilidad clara
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# MALO: Actividad comodín
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # extracción
sentiment = ... # análisis
# enviar correo
# guardar en BD
pass
El segundo concierne a los recursos. El gestor de contexto async with garantiza que el cliente se cierre incluso si ocurre una excepción, algo que las llamadas manuales inevitablemente olvidan tarde o temprano.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Usa async with para garantizar el cierre
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# El cliente se cierra automáticamente aquí
return response.json()
El tercero es más sutil: no todos los errores merecen un reintento. Un tiempo de espera agotado, un 429 o un 500 son transitorios y deben propagarse para desencadenar un reintento. Un error 4xx, sin embargo, indica una solicitud inválida que repetir tres veces no solucionará. En su lugar, devuelve un resultado explícito y deja que el flujo de trabajo 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 # La plataforma lo reintentará
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Límite de tasa alcanzado — se reintentará
elif e.response.status_code >= 500:
raise # Error del servidor — se reintentará
else:
# Error del cliente (4xx) — no reintentar
return {"status": "error", "code": e.response.status_code}
Finalmente, el cuarto hábito deriva del límite de 2 MB por invocación: devuelve solo lo que el flujo de trabajo necesita realmente para decidir el siguiente paso. Un recuento, una muestra y la URL al resultado completo suelen ser suficientes.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Devuelve solo lo que el flujo de trabajo necesita
return {
"item_count": len(data),
"summary": data[:10], # Solo los primeros 10
"full_url": await upload_results(data)
}
Puntos clave
- Las E/S asíncronas son obligatorias: usa
httpx,asyncpg,aiofilesen lugar de sus equivalentes síncronos - Las llamadas bloqueantes (
requests,psycopg2,open) congelan todo el worker - Usa
asyncio.to_thread()como último recurso para bibliotecas sin versión asíncrona - Cada actividad debe tener una responsabilidad clara
- Cierra siempre las conexiones con
async with - Gestiona los errores explícitamente: algunos deben reintentarse, otros no
- Limita el tamaño de lo devuelto para mantenerte bajo el límite de 2 MB