Crear una actividad
En esta página
¿Qué es una actividad?
Una actividad es la unidad operativa básica de un flujo de trabajo. Aquí es donde se realiza el trabajo real: llamadas a API externas, consultas a bases de datos, envío de correos electrónicos, procesamiento de archivos y llamadas a modelos de IA. La división de tareas es sencilla y te servirá de brújula durante todo este curso: cualquier operación que implique entrada/salida (E/S) o efectos secundarios debe encapsularse en una actividad.
Mientras el flujo de trabajo orquesta, la actividad ejecuta. Esta es la distinción fundamental, y tiene una consecuencia directa: al estar el trabajo de riesgo aislado dentro de las actividades, el motor puede reintentar, medir y reproducir la ejecución sin duplicar jamás los efectos secundarios.
Anatomía de una actividad
Una actividad es una función Python async decorada con @workflows.activity():
import mistralai.workflows as workflows
@workflows.activity()
async def get_user_profile(user_id: str) -> dict:
"""Recupera el perfil de un usuario desde la 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()
Cuatro elementos de estas pocas líneas merecen tu atención. El decorador @workflows.activity() registra la función como una actividad ante el motor, lo que permite invocarla desde un flujo de trabajo. La sentencia async def es obligatoria: todas las actividades deben ser asíncronas, sin excepción. Los parámetros deben ser serializables en JSON, es decir, tipos simples (str, int, float, bool, list, dict) o modelos de Pydantic; pasar como argumento un objeto de conexión o un manejador de archivo fallará en la serialización. La misma regla se aplica al valor de retorno, que viaja por la red antes de escribirse en el registro de eventos.
Ejemplos concretos de actividades
El primer caso, probablemente el más común en este curso, encapsula una llamada a un modelo de Mistral. Observa que la actividad también devuelve el consumo de tokens: una vez en el registro, este tipo de metadatos te permite reconstruir el coste de una ejecución a posteriori.
import mistralai.workflows as workflows
from mistralai.client import Mistral
@workflows.activity()
async def generate_summary(text: str) -> dict:
"""Genera un resumen del texto proporcionado mediante Mistral."""
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Eres un asistente especializado en resumir textos."},
{"role": "user", "content": f"Resume este texto en 3 frases:\n\n{text}"}
]
)
return {
"summary": response.choices[0].message.content,
"tokens_used": response.usage.total_tokens
}
El segundo caso ilustra el acceso a una base de datos. El bloque try/finally no es decorativo: si la actividad falla y se reintenta, dejar una conexión abierta en cada intento agotará rápidamente el pool de PostgreSQL.
import mistralai.workflows as workflows
import asyncpg
@workflows.activity()
async def save_report(report: dict) -> dict:
"""Guarda un informe en 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()
El tercer caso, el envío de correo electrónico, es donde los efectos secundarios son más visibles: una vez enviado el mensaje, ningún reintento puede recuperarlo.
import mistralai.workflows as workflows
import aiosmtplib
@workflows.activity()
async def send_notification(recipient: str, subject: str, body: str) -> dict:
"""Envía un correo electrónico de notificación."""
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}
Características principales
En primer lugar, una libertad bienvenida: a diferencia de los flujos de trabajo, las actividades no tienen restricciones de determinismo. Puedes usar libremente datetime.now(), uuid.uuid4(), random.random() o cualquier otra llamada no determinista dentro de una actividad. Precisamente para eso sirven las actividades: para absorber todo lo que el flujo de trabajo no tiene permitido hacer.
La plataforma trata cada llamada a una actividad como una unidad atómica: o tiene éxito por completo o falla por completo, sin que el flujo de trabajo vea ningún estado intermedio. Si tu actividad hace tres cosas y la segunda falla, el flujo de trabajo solo ve un fallo, no un éxito parcial. Por eso debes evitar apilar cinco operaciones distintas en una sola función.
Una vez que una actividad tiene éxito, su resultado queda registrado permanentemente en el registro de eventos del flujo de trabajo. Durante una reproducción, la actividad nunca se vuelve a ejecutar: solo se usa el resultado registrado. A cambio, dado que una actividad puede reintentarse tras un fallo (tiempo de espera de red, error transitorio), debe ser idempotente: ejecutada varias veces con los mismos parámetros, debe producir el mismo resultado. Cambiar de un POST a un PUT sobre un identificador estable suele bastar para lograr esta propiedad, como aquí, donde el correo electrónico sirve de clave:
@workflows.activity()
async def create_or_update_client(email: str, name: str) -> dict:
"""Idempotente: usa un upsert en lugar de un 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()
Nombrar una actividad
El decorador acepta un nombre explícito, lo que mejora significativamente la legibilidad del rastreo cuando una función técnica tiene un nombre en inglés que nadie más en el equipo relaciona con el dominio de negocio:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Este nombre aparecerá en los rastros de OpenTelemetry y facilitará la depuración. Acostúmbrate a establecerlo desde el principio: el día que intentes averiguar por qué una ejecución tardó cuarenta minutos, leerás etiquetas significativas en lugar de una lista de nombres de funciones.
Restricciones de tamaño
Dos límites rigen los intercambios: 2 MB máximo para los parámetros de entrada y 2 MB máximo para el valor de retorno. Esto se deriva directamente del event sourcing, ya que estos valores se serializan y almacenan en el registro.
La consecuencia práctica es clara. Si necesitas procesar archivos grandes (un PDF escaneado de 40 MB, un archivo de exportación), no los pases de una actividad a otra. Almacénalos en un servicio externo (S3, GCS) y circula solo la URL o el identificador: la actividad descarga el archivo, lo procesa, escribe el resultado de nuevo en el almacenamiento y devuelve una referencia de unos pocos cientos de bytes.
Puntos clave
- Una actividad es una función
asyncdecorada con@workflows.activity()que realiza el trabajo real (E/S, API, BD) - Los parámetros y los valores de retorno deben ser serializables en JSON
- Las actividades no tienen restricciones de determinismo
- Una actividad exitosa nunca se vuelve a ejecutar durante una reproducción
- Las actividades deben ser idempotentes (mismo resultado si se ejecutan varias veces)
- Límite de 2 MB en la entrada y la salida por actividad