Créer une activité
In questa pagina
Qu’est-ce qu’une activité ?
Une activité est l’unité opérationnelle de base d’un workflow. C’est ici que se déroule le vrai travail : appels d’API externes, requêtes en base de données, envoi d’e-mails, traitement de fichiers et appels à des modèles d’IA. La répartition des tâches est simple et te servira de boussole tout au long de ce cours : toute opération impliquant des entrées/sorties (I/O) ou des effets de bord doit être encapsulée dans une activité.
Alors que le workflow orchestre, l’activité exécute. Telle est la distinction fondamentale, avec une conséquence directe : parce que le travail à risque est isolé au sein des activités, le moteur peut réessayer, mesurer et rejouer sans jamais dupliquer les effets de bord.
Anatomie d’une activité
Une activité est une fonction Python async décorée avec @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()
Quatre éléments dans ces quelques lignes méritent ton attention. Le décorateur @workflows.activity() enregistre la fonction comme une activité auprès du moteur, la rendant appelable depuis un workflow. La syntaxe async def est obligatoire : toutes les activités doivent être asynchrones, sans exception. Les paramètres doivent être sérialisables en JSON, c’est-à-dire des types simples — str, int, float, bool, list, dict — ou des modèles Pydantic ; passer un objet de connexion ou un descripteur de fichier en argument échouera lors de la sérialisation. La même règle s’applique à la valeur de retour, qui traverse le réseau avant d’être écrite dans le journal d’événements.
Exemples concrets d’activités
Le premier cas, probablement le plus courant dans ce cours, encapsule un appel à un modèle Mistral. Note que l’activité renvoie également la consommation de jetons : une fois dans le journal, ce type de métadonnées te permet de reconstruire le coût d’une exécution après coup.
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
}
Le deuxième cas illustre l’accès à une base de données. Le bloc try/finally n’est pas décoratif : si l’activité échoue et est réessayée, laisser une connexion ouverte à chaque tentative épuisera rapidement le 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()
Le troisième cas, l’envoi d’e-mail, est celui où les effets de bord sont les plus visibles : une fois le message envoyé, aucun réessai ne peut le rattraper.
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}
Caractéristiques fondamentales
D’abord, une liberté bienvenue : contrairement aux workflows, les activités n’ont aucune contrainte de déterminisme. Tu peux librement utiliser datetime.now(), uuid.uuid4(), random.random() ou tout autre appel non déterministe à l’intérieur d’une activité. C’est précisément le rôle des activités : absorber tout ce que le workflow n’a pas le droit de faire.
La plateforme traite ensuite chaque appel d’activité comme une unité atomique : elle réussit entièrement ou échoue entièrement, sans état intermédiaire visible pour le workflow. Si ton activité fait trois choses et que la seconde plante, le workflow ne voit qu’un échec, pas une réussite partielle. C’est pourquoi tu dois éviter d’empiler cinq opérations distinctes dans une seule fonction.
Une fois qu’une activité réussit, son résultat est enregistré de manière permanente dans le journal d’événements du workflow. Lors d’un rejouage, l’activité n’est jamais réexécutée : seul le résultat enregistré est utilisé. En contrepartie, parce qu’une activité peut être réessayée en cas d’échec (délai d’attente réseau, erreur transitoire), elle doit être idempotente : exécutée plusieurs fois avec les mêmes paramètres, elle doit produire le même résultat. Passer d’un POST à un PUT sur un identifiant stable suffit souvent à obtenir cette propriété, comme ici où l’e-mail sert de clé :
@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()
Nommer une activité
Le décorateur accepte un nom explicite, ce qui améliore considérablement la lisibilité de la traçabilité lorsqu’une fonction technique porte un nom anglais que personne d’autre dans l’équipe ne relie au domaine métier :
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Ce nom apparaîtra dans les traces OpenTelemetry et facilitera le débogage. Prends l’habitude de le définir dès le départ : le jour où tu chercheras pourquoi une exécution a duré quarante minutes, tu liras des étiquettes significatives plutôt qu’une liste de noms de fonctions.
Contraintes de taille
Deux limites régissent les échanges : 2 Mo maximum pour les paramètres d’entrée et 2 Mo maximum pour la valeur de retour. Cela découle directement de l’Event Sourcing, car ces valeurs sont sérialisées et stockées dans le journal.
La conséquence pratique est claire. Si tu dois traiter de gros fichiers — un PDF numérisé de 40 Mo, une archive d’exportation — ne les passe pas d’activité en activité. Stocke-les dans un service externe (S3, GCS) et ne fais circuler que l’URL ou l’identifiant : l’activité télécharge le fichier, le traite, écrit le résultat dans le stockage et renvoie une référence de quelques centaines d’octets.
Punti chiave
- Une activité est une fonction
asyncdécorée avec@workflows.activity()qui effectue le vrai travail (I/O, API, DB) - Les paramètres et les valeurs de retour doivent être sérialisables en JSON
- Les activités n’ont aucune contrainte de déterminisme
- Une activité réussie n’est jamais réexécutée lors d’un rejouage
- Les activités doivent être idempotentes (même résultat si exécutées plusieurs fois)
- Limite de 2 Mo sur les entrées et sorties par activité