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

Criar um fluxo de trabalho

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. O papel do fluxo de trabalho
  2. Estrutura do fluxo de trabalho
  3. Exemplo completo: pipeline de processamento
  4. Durabilidade do fluxo de trabalho
  5. Fluxo de trabalho com ramificação condicional
  6. Entradas com Pydantic
  7. Boas práticas
  8. Pontos-chave

O papel do fluxo de trabalho

O fluxo de trabalho é a camada de orquestração da sua aplicação. Define o que deve acontecer, em que ordem e sob quais condições — sem executar o trabalho em si. Concretamente, coordena atividades, aguarda eventos externos, gere temporizadores e ramos condicionais, mas nunca toca na rede nem no disco.

Pode resumir isto numa frase para ter sempre em mente ao rever código: as atividades fazem o trabalho, o fluxo de trabalho dirige. Se vir httpx ou open() dentro de uma classe de fluxo de trabalho, algo precisa de ser movido.

Estrutura do fluxo de trabalho

Um fluxo de trabalho é uma classe Python decorada com @workflows.workflow.define(), contendo um método de entrada decorado com @workflows.workflow.entrypoint:

import mistralai.workflows as workflows

@workflows.workflow.define(name="mon_premier_workflow")
class MonPremierWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, nom: str) -> dict:
        """Workflow entry point."""
        resultat = await saluer(nom)
        return resultat

O decorador @workflows.workflow.define(name="...") regista a classe como um fluxo de trabalho. O name que recebe é o identificador único que utilizará para acionar uma execução — é esta cadeia de caracteres, e não o nome da classe Python, que o chamador vê. O decorador @workflows.workflow.entrypoint marca o método chamado no arranque. O primeiro parâmetro, self, permanece a instância da classe, como em qualquer objeto Python, e cada chamada de atividade utiliza await.

Exemplo completo: pipeline de processamento

Eis um fluxo de trabalho realista que orquestra múltiplas atividades para processar um documento. Note a divisão de tarefas: as três funções no topo contêm todo o código que toca no mundo exterior, enquanto a classe na parte inferior simplesmente encadeia chamadas await e monta um resultado.

import mistralai.workflows as workflows
from mistralai.client import Mistral

# --- Activities ---

@workflows.activity()
async def extraire_texte(url_document: str) -> dict:
    """Download and extract text from a document."""
    async with httpx.AsyncClient() as client:
        response = await client.get(url_document)
        texte = response.text
    return {"texte": texte, "longueur": len(texte)}

@workflows.activity()
async def analyser_avec_mistral(texte: str) -> dict:
    """Analyze text with Mistral to extract key points."""
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Extract the 5 key points from this text."},
            {"role": "user", "content": texte}
        ]
    )
    return {"analyse": response.choices[0].message.content}

@workflows.activity()
async def sauvegarder_resultat(analyse: dict) -> dict:
    """Save the analysis result."""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/rapports",
            json=analyse
        )
        return {"id_rapport": response.json()["id"]}

# --- Workflow ---

@workflows.workflow.define(name="pipeline_analyse_document")
class PipelineAnalyseDocument:
    @workflows.workflow.entrypoint
    async def run(self, url_document: str) -> dict:
        """Orchestrate extraction, analysis, and saving."""
        # Step 1: Extract text
        extraction = await extraire_texte(url_document)

        # Step 2: Analyze with Mistral
        analyse = await analyser_avec_mistral(extraction["texte"])

        # Step 3: Save
        sauvegarde = await sauvegarder_resultat(analyse)

        return {
            "url_source": url_document,
            "longueur_texte": extraction["longueur"],
            "id_rapport": sauvegarde["id_rapport"]
        }

Cada await no fluxo de trabalho constitui um ponto de persistência. Vale a pena verificar isto mentalmente com o exemplo acima: se o processo falhar entre o passo 2 e o passo 3, o documento não será transferido novamente e o modelo não será chamado outra vez — logo, sem custos adicionais de tokens. O fluxo de trabalho será retomado diretamente no passo de gravação.

Durabilidade do fluxo de trabalho

Os fluxos de trabalho sobrevivem a reinícios, falhas de infraestrutura e erros transitórios porque a plataforma regista cada evento e reconstrói o estado do fluxo de trabalho durante a repetição. Esta reconstrução só é fiável sob uma condição, mencionada anteriormente: o código do fluxo de trabalho deve produzir sempre a mesma sequência de operações para as mesmas entradas. Esta é a restrição de determinismo. Abordaremos os detalhes na lição 8.

Fluxo de trabalho com ramificação condicional

Um fluxo de trabalho não se limita a uma sequência linear. Pode conter lógica condicional, como neste exemplo de processamento de encomendas onde o caminho depende do estado do stock:

@workflows.workflow.define(name="traitement_commande")
class OrderProcessing:
    @workflows.workflow.entrypoint
    async def run(self, order: dict) -> dict:
        # Check stock
        stock = await check_stock(order["produit_id"])

        if stock["disponible"]:
            # Standard path
            payment = await process_payment(order["montant"])
            shipment = await prepare_shipment(order)
            await send_confirmation(order["email"], shipment)
            return {"status": "confirmée", "tracking": shipment["tracking"]}
        else:
            # Alternative path
            await notify_stockout(order["email"], order["produit_id"])
            return {"status": "rupture_stock"}

Os ramos if/else são totalmente suportados. A única restrição diz respeito ao material utilizado para a decisão: o resultado do ramo deve depender do valor de retorno de uma atividade — um valor registado no log e repetido de forma idêntica — e não de uma chamada direta a um serviço externo a partir do fluxo de trabalho. Aqui, verifier_stock consulta o inventário dentro de uma atividade, e a instrução if lê apenas um dicionário que já foi persistido.

Entradas com Pydantic

Um fluxo de trabalho que aceita seis parâmetros posicionais torna-se rapidamente ilegível. Para entradas estruturadas, utilize modelos Pydantic, que também fornecem validação de tipos no início da execução:

from pydantic import BaseModel

class ReportParams(BaseModel):
    report_type: str
    include_details: bool = False
    start_date: str
    end_date: str

@workflows.workflow.define(name="generation_rapport")
class ReportGeneration:
    @workflows.workflow.entrypoint
    async def run(self, params: ReportParams) -> dict:
        data = await collect_data(params.report_type, params.start_date, params.end_date)
        
        if params.include_details:
            data = await enrich_data(data)
        
        report = await generate_pdf_report(data)
        return {"url_rapport": report["url"]}

Um ponto de atenção ao acionar este fluxo de trabalho: quando utiliza um BaseModel, os campos tornam-se chaves de nível superior no JSON de entrada enviado para o fluxo de trabalho. Enviará {"type_rapport": ..., "date_debut": ...}, e não um objeto aninhado sob uma chave params.

Boas práticas

Quatro hábitos fazem a diferença a longo prazo. Primeiro, atenha-se a uma responsabilidade por fluxo de trabalho: misturar faturação e acompanhamento de vendas na mesma classe torna impossível repetir um sem o outro. Em seguida, preste atenção à nomenclatura, já que o name do fluxo de trabalho é um identificador público chamado a partir de outros sistemas — "traitement_commande" é sustentável, "workflow_1" não é. Não introduza nenhuma E/S no fluxo de trabalho: cada chamada de rede, acesso a ficheiro ou consulta à base de dados pertence a uma atividade. Por fim, mantenha o código do fluxo de trabalho simples, delegando lógica complexa — análise sintática, transformações, cálculos pesados — às atividades, onde pode ser testada isoladamente sem restrições de determinismo.

Pontos-chave

  • Um fluxo de trabalho é uma classe decorada com @workflows.workflow.define() que orquestra atividades
  • O método @workflows.workflow.entrypoint é o ponto de entrada chamado no arranque
  • Cada await de atividade é um ponto de persistência (retoma automática em caso de falha)
  • Ramos condicionais e ciclos são suportados
  • Utilize modelos Pydantic para parâmetros de entrada estruturados
  • O fluxo de trabalho não deve conter nenhuma operação direta de E/S