Criar um worker
Nesta página
O papel do worker
O worker é o processo Python que executa efetivamente os seus workflows e atividades. Este conecta-se à plataforma Mistral, escuta tarefas pendentes e executa-as localmente na sua máquina ou servidor. Este detalhe arquitetural surpreende frequentemente os recém-chegados: o seu código nunca sai do seu ambiente; apenas o estado da orquestração reside na Mistral.
A implicação é direta e explica a maioria dos problemas de “nada está a acontecer” encontrados no início de um projeto: sem um worker em execução, os seus workflows não podem ser executados. Pode desencadear uma execução, mas esta ficará simplesmente à espera até que um worker capaz apareça. O worker é o elo de ligação entre a plataforma de orquestração Mistral e o seu código local.
Criar um worker mínimo
Um worker funcional cabe em poucas linhas. O exemplo abaixo combina intencionalmente a atividade, o workflow e a lógica de arranque num único ficheiro para que possa executá-lo imediatamente:
import asyncio
import mistralai.workflows as workflows
# Import your workflows and activities
@workflows.activity()
async def dire_bonjour(nom: str) -> dict:
return {"message": f"Bonjour, {nom} !"}
@workflows.workflow.define(name="salutation_workflow")
class SalutationWorkflow:
@workflows.workflow.entrypoint
async def run(self, nom: str) -> dict:
resultat = await dire_bonjour(nom)
return resultat
# Start the worker
async def main() -> None:
await workflows.run_worker([SalutationWorkflow])
if __name__ == "__main__":
asyncio.run(main())
A função chave é workflows.run_worker(). Esta aceita uma lista de classes de workflow que este worker pode executar — e apenas workflows. As atividades são descobertas através delas, pelo que não precisa de listar as atividades separadamente.
O que faz run_worker()
Quando chama workflows.run_worker([MyWorkflow]), ocorrem cinco coisas em sequência. Primeiro, o worker autentica-se na plataforma Mistral usando a sua chave de API. Em seguida, regista os workflows e atividades declarados. Este registo informa a plataforma de que existe um executor para o identificador salutation_workflow. De seguida, abre uma ligação persistente e aguarda tarefas, permanecendo intencionalmente inativo até que uma execução seja desencadeada. Quando uma execução chega, o worker executa o código localmente e os resultados são enviados de volta à plataforma para persistência.
O worker mantém-se ativo enquanto o processo Python estiver em execução, razão pela qual nunca devolve o controlo ao seu terminal. Utilize Ctrl+C para o parar corretamente.
Worker com múltiplos workflows
Nada exige um worker por workflow. Um único processo pode alojar múltiplos workflows, mesmo quando estes partilham atividades. Aqui, extraire_texte e analyser_sentiment servem ambos:
import asyncio
import mistralai.workflows as workflows
# --- Activities ---
@workflows.activity()
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text}
@workflows.activity()
async def analyser_sentiment(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Analysez le sentiment : positif, négatif ou neutre."},
{"role": "user", "content": texte}
]
)
return {"sentiment": response.choices[0].message.content}
@workflows.activity()
async def envoyer_alerte(message: str) -> dict:
# Envoi vers Slack, email, etc.
return {"status": "envoyé"}
# --- Workflows ---
@workflows.workflow.define(name="analyse_document")
class DocumentAnalysis:
@workflows.workflow.entrypoint
async def run(self, url: str) -> dict:
extraction = await extraire_texte(url)
sentiment = await analyser_sentiment(extraction["texte"])
return sentiment
@workflows.workflow.define(name="surveillance_mentions")
class MentionMonitoring:
@workflows.workflow.entrypoint
async def run(self, url: str, seuil: str) -> dict:
extraction = await extraire_texte(url)
sentiment = await analyser_sentiment(extraction["texte"])
if sentiment["sentiment"] == "négatif":
await envoyer_alerte(f"Mention négative détectée : {url}")
return sentiment
# --- Worker ---
async def main() -> None:
await workflows.run_worker([
DocumentAnalysis,
MentionMonitoring,
])
if __name__ == "__main__":
asyncio.run(main())
Estrutura de ficheiros recomendada
Um único ficheiro funciona para aprendizagem, mas não para um projeto em produção. Para produção, separe o seu código em módulos por tipo:
mon-projet/
├── activities/
│ ├── __init__.py
│ ├── extraction.py # extraire_texte()
│ ├── analyse.py # analyser_sentiment()
│ └── notifications.py # envoyer_alerte()
├── workflows/
│ ├── __init__.py
│ ├── analyse_document.py
│ └── surveillance.py
└── worker.py # Single entry point
O ficheiro worker.py contém então apenas importações e lógica de arranque, tornando-se num inventário legível do que este processo pode executar:
import asyncio
import mistralai.workflows as workflows
from workflows.document_analysis import DocumentAnalysis
from workflows.monitoring import MentionMonitoring
async def main() -> None:
await workflows.run_worker([
DocumentAnalysis,
MentionMonitoring,
])
if __name__ == "__main__":
asyncio.run(main())
Iniciar o worker
uv run python worker.py
O worker apresenta uma mensagem de ligação e mantém-se ativo, à espera de tarefas. Deverá ver algo como:
Worker connected. Listening for tasks...
Até que esta linha apareça, não desencadeie nada. Primeiro, verifique a sua chave de API e a ligação de rede.
Worker em produção
Um worker lançado manualmente num terminal desaparece após a primeira desconexão SSH. Entregue-o a um gestor de processos — systemd, supervisor ou pm2 — que o reiniciará automaticamente após uma falha ou reinício:
# With pm2 (if Node.js is available)
pm2 start "uv run python worker.py" --name workflow-worker
# With systemd (create a .service file)
Este reinício automático combina bem com a durabilidade: os workflows em execução retomam por si próprios assim que o novo processo se conecta. No que diz respeito aos segredos, nunca codifique a chave de API diretamente no ficheiro do worker, ou esta acabará no seu repositório Git. O SDK lê a variável de ambiente automaticamente:
import os
# The SDK automatically reads MISTRAL_API_KEY
# No need to pass it explicitly
Por fim, considere o registo de logs (logging). O worker emite mensagens através do módulo padrão logging do Python. Uma configuração simples no arranque fornece-lhe um rasto das atividades executadas, o que é valioso para compreender o que estava em execução durante um incidente:
import logging
logging.basicConfig(level=logging.INFO)
Pontos-chave
- O worker é o processo que executa os seus workflows e atividades localmente
workflows.run_worker([...])aceita uma lista de classes de workflow a executar- Um único worker pode executar múltiplos workflows diferentes
- O worker mantém-se ativo e escuta tarefas enquanto o processo estiver em execução
- Em produção, utilize um gestor de processos para manter o worker em execução
- A chave de API é lida automaticamente a partir de
MISTRAL_API_KEY