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

Executar e testar um fluxo de trabalho

Aula 7 de 14 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Acionar um fluxo de trabalho
  2. Acionamento via SDK Python
  3. Acionamento via cURL
  4. Exemplo de ponta a ponta
  5. Verificar resultados
  6. Gestão de erros
  7. Testes locais
  8. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base no SDK mistralai 3.7.0: o acompanhamento de uma execução utiliza agora client.workflows.executions.get_workflow_execution_async, e o resultado é lido a partir de result. Adenda do mesmo dia: os exemplos anteriores referenciavam ainda execution.id, execution.output e execution.error, que estão ausentes do SDK, e comparavam o estado com "completed" ou "failed" em minúsculas; utilizam agora execution_id, result, wait_for_result=True e estados em maiúsculas. Fonte: client-python.

Acionar um fluxo de trabalho

Já escreveu as suas atividades, definiu o seu fluxo de trabalho e iniciou o seu worker. Agora precisa de lançar uma execução. Tem duas opções: o SDK Python ou uma chamada cURL à API REST. A primeira adapta-se aos seus scripts e serviços Python; a segunda funciona para testes rápidos na linha de comandos ou acionamentos a partir de sistemas não Python — um webhook, um agendador ou um backend escrito noutra linguagem.

Três condições devem ser cumpridas antes de acionar qualquer coisa. O seu worker deve estar em execução (uv run python worker.py), a sua chave de API deve estar definida em MISTRAL_API_KEY e o fluxo de trabalho deve estar registado nesse worker, o que significa que aparece na lista passada a run_worker().

Acionamento via SDK Python

Escreva o acionamento num script separado do worker, uma vez que o processo do worker nunca devolve o controlo:

import asyncio
from mistralai.client import Mistral

async def main():
    client = Mistral()

    execution = await client.workflows.execute_workflow_async(
        workflow_identifier="salutation_workflow",
        input={"nom": "Marie"},
        wait_for_result=True,  # aguarda a conclusão e recebe o resultado
    )

    print(f"Execution ID: {execution.execution_id}")
    print(f"Result: {execution.result}")

if __name__ == "__main__":
    asyncio.run(main())

O workflow_identifier corresponde exatamente ao name declarado em @workflows.workflow.define(), e as chaves no dicionário input correspondem aos parâmetros do seu método run. Execute este script num terminal separado, deixando o primeiro ocupado pelo worker:

uv run python trigger.py

Com wait_for_result=True, o SDK aguarda o fim da execução e devolve o resultado diretamente, tornando os testes muito legíveis para fluxos de trabalho curtos. Sem este parâmetro, a chamada retorna imediatamente com o identificador da execução, que poderá depois acompanhar (veja abaixo).

Acionamento via cURL

Para testes rápidos ou integração com outros sistemas, a API REST expõe o mesmo acionador:

curl -X POST https://api.mistral.ai/v1/workflows/salutation_workflow/execute \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"nom": "Marie"}, "wait_for_result": true}'

Com wait_for_result, a resposta contém o nome do fluxo de trabalho, o identificador da execução e o seu resultado; estes são os campos do modelo WorkflowExecutionSyncResponse do SDK:

{
  "workflow_name": "salutation_workflow",
  "execution_id": "…",
  "result": {
    "message": "Bonjour, Marie !"
  }
}

Guarde este execution_id: é a chave que utilizará mais tarde para consultar a execução ou recuperar os seus traços. Sem wait_for_result, a resposta descreve a execução em curso, incluindo o seu status (RUNNING inicialmente).

Exemplo de ponta a ponta

Vamos revisitar o exemplo do pipeline de análise de documentos, desta vez totalmente configurado. O primeiro ficheiro combina as definições e o arranque do worker; note o truncamento para 5000 caracteres, que protege tanto o limite de tamanho da atividade como o seu orçamento de tokens.

Ficheiro workflow.py (worker + definições)

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

@workflows.activity()
async def extraire_texte(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
    return {"texte": response.text[:5000]}  # Limitar a 5000 caracteres

@workflows.activity()
async def resumer_texte(texte: str) -> dict:
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Summarize in 3 sentences."},
            {"role": "user", "content": texte}
        ]
    )
    return {"resume": response.choices[0].message.content}

@workflows.workflow.define(name="resume_page_web")
class ResumePageWeb:
    @workflows.workflow.entrypoint
    async def run(self, url: str) -> dict:
        extraction = await extraire_texte(url)
        resume = await resumer_texte(extraction["texte"])
        return {
            "url_source": url,
            "resume": resume["resume"]
        }

async def main() -> None:
    await workflows.run_worker([ResumePageWeb])

if __name__ == "__main__":
    asyncio.run(main())

O segundo ficheiro aciona o fluxo de trabalho e apresenta o resultado, gerindo explicitamente o caso de falha — um reflexo a adotar desde o seu primeiro script:

Ficheiro trigger.py (acionador)

import asyncio
from mistralai.client import Mistral

async def main():
    client = Mistral()

    print("Lançamento do fluxo de trabalho...")
    execution = await client.workflows.execute_workflow_async(
        workflow_identifier="resume_page_web",
        input={"url": "https://example.com/article"},
    )
    print(f"Execução lançada: {execution.execution_id}")

    # Acompanhar a execução até à conclusão
    while True:
        suivi = await client.workflows.executions.get_workflow_execution_async(
            execution_id=execution.execution_id
        )
        if suivi.status not in ("RUNNING", "RETRYING_AFTER_ERROR"):
            break
        await asyncio.sleep(2)

    if suivi.status == "COMPLETED":
        print(f"Resumo: {suivi.result['resume']}")
    else:
        print(f"Execução terminada com o estado {suivi.status}")

if __name__ == "__main__":
    asyncio.run(main())

Execução

Terminal 1 — Iniciar o worker:

uv run python workflow.py

Terminal 2 — Acionar a execução:

uv run python trigger.py

Verificar resultados

O terminal do worker é o seu primeiro ponto de observação: exibe as atividades executadas em tempo real, juntamente com a sua duração, mostrando-lhe imediatamente qual o passo que consome mais tempo.

[INFO] Executing activity: extraire_texte
[INFO] Activity completed: extraire_texte (1.2s)
[INFO] Executing activity: resumer_texte
[INFO] Activity completed: resumer_texte (3.4s)
[INFO] Workflow completed: resume_page_web

Para fluxos de trabalho longos, obviamente não ficará colado ao terminal. Assim que tiver o ID da execução, pode consultar o seu estado a qualquer momento a partir de outro processo:

execution = await client.workflows.executions.get_workflow_execution_async(
    execution_id="exec_abc123"
)
print(f"Status: {execution.status}")
print(f"Result: {execution.result}")

A mesma operação está disponível via cURL, útil num script de monitorização:

curl https://api.mistral.ai/v1/workflows/executions/exec_abc123 \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

Gestão de erros

Uma falha não ocorre à primeira exceção: a plataforma tenta primeiro repetir a atividade de acordo com a sua política de retry. Só após esgotar as tentativas é que a execução passa para o estado FAILED (os estados do SDK estão em maiúsculas: RUNNING, COMPLETED, FAILED, CANCELED, TERMINATED, TIMED_OUT, etc.), e o seu código chamador deve gerir este caso em vez de assumir que um result está sempre presente:

execution = await client.workflows.executions.get_workflow_execution_async(
    execution_id="exec_abc123"
)

if execution.status == "FAILED":
    print(f"Execução {execution.execution_id} falhou")

A resposta não contém uma mensagem de erro: a causa aparece no histórico de execução e nos logs (get_workflow_execution_history_async, get_workflow_execution_logs_async). Para identificar a atividade defeituosa e a sequência que a levou a isso, analisará os traços OpenTelemetry, abordados na Lição 14.

Testes locais

Alternar entre dois terminais torna-se rapidamente fastidioso durante o desenvolvimento. Para desenvolvimento, um único script pode iniciar o worker em segundo plano, acionar o fluxo de trabalho e depois parar tudo:

import asyncio
import mistralai.workflows as workflows

# ... definições de atividade e fluxo de trabalho ...

async def main():
    # Iniciar worker em segundo plano
    worker_task = asyncio.create_task(
        workflows.run_worker([MonWorkflow])
    )

    # Aguardar que o worker esteja pronto
    await asyncio.sleep(2)

    # Acionar fluxo de trabalho
    from mistralai.client import Mistral
    client = Mistral()
    execution = await client.workflows.execute_workflow_async(
        workflow_identifier="mon_workflow",
        input={"test": True},
        wait_for_result=True,
    )
    print(f"Result: {execution.result}")

    # Parar worker
    worker_task.cancel()

if __name__ == "__main__":
    asyncio.run(main())

O asyncio.sleep(2) dá tempo ao worker para estabelecer a sua ligação antes do acionamento, e o worker_task.cancel() final impede que o script fique bloqueado indefinidamente. Reserve esta configuração para desenvolvimento: em produção, o worker e os acionadores permanecem processos separados com ciclos de vida independentes.

Pontos-chave

  • Dois métodos de acionamento: SDK Python (execute_workflow_async) e API REST (cURL)
  • O worker deve estar em execução para que o fluxo de trabalho seja executado
  • Com wait_for_result=True, o SDK aguarda a conclusão e devolve o resultado (result); caso contrário, devolve o execution_id para acompanhamento
  • Utilize client.workflows.executions.get_workflow_execution_async() para verificar o estado de uma execução
  • Os estados estão em maiúsculas (RUNNING, COMPLETED, FAILED, etc.); as causas de falha aparecem no histórico de execução, logs e traços
  • Para desenvolvimento, combine worker e acionador num único script utilizando asyncio