Criar um fluxo de trabalho
Nesta página
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
awaitde 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