Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Criar um worker

Aula 6 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. O papel do worker
  2. Criar um worker mínimo
  3. O que faz run_worker()
  4. Worker com múltiplos workflows
  5. Estrutura de ficheiros recomendada
  6. Iniciar o worker
  7. Worker em produção
  8. Pontos-chave

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