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

Criar uma Atividade

Aula 4 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. O Que É uma Atividade?
  2. Anatomia de uma Atividade
  3. Exemplos Concretos de Atividades
  4. Características Fundamentais
  5. Nomear uma Atividade
  6. Restrições de Tamanho
  7. Pontos-chave

O Que É uma Atividade?

Uma atividade é a unidade operacional básica num fluxo de trabalho. É aqui que ocorre o trabalho real: chamadas a APIs externas, consultas à base de dados, envio de e-mails, processamento de ficheiros e chamadas a modelos de IA. A divisão de tarefas é simples e servirá de bússola ao longo deste curso: qualquer operação que envolva entrada/saída (I/O) ou efeitos colaterais deve ser encapsulada numa atividade.

Enquanto o fluxo de trabalho orquestra, a atividade executa. Esta é a distinção fundamental, com uma consequência direta: como o trabalho de risco está isolado nas atividades, o motor pode repetir tentativas, medir e reproduzir a execução sem nunca duplicar os efeitos colaterais.

Anatomia de uma Atividade

Uma atividade é uma função Python async decorada com @workflows.activity():

import mistralai.workflows as workflows

@workflows.activity()
async def get_user_profile(user_id: str) -> dict:
    """Retrieves a user profile from the API."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        response.raise_for_status()
        return response.json()

Quatro elementos nestas poucas linhas merecem a sua atenção. O decorador @workflows.activity() regista a função como uma atividade no motor, tornando-a invocável a partir de um fluxo de trabalho. O async def é obrigatório: todas as atividades devem ser assíncronas, sem exceção. Os parâmetros devem ser serializáveis em JSON, ou seja, tipos simples — str, int, float, bool, list, dict — ou modelos Pydantic; passar um objeto de ligação ou um manipulador de ficheiro como argumento falhará na serialização. A mesma regra aplica-se ao valor de retorno, que viaja pela rede antes de ser escrito no registo de eventos.

Exemplos Concretos de Atividades

O primeiro caso, provavelmente o mais comum neste curso, encapsula uma chamada a um modelo Mistral. Note que a atividade também devolve o consumo de tokens: uma vez no registo, este tipo de metadados permite-lhe reconstruir o custo de uma execução após o facto.

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

@workflows.activity()
async def generate_summary(text: str) -> dict:
    """Generates a summary of the provided text via Mistral."""
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "You are an assistant specialized in text summarization."},
            {"role": "user", "content": f"Summarize this text in 3 sentences:\n\n{text}"}
        ]
    )
    return {
        "summary": response.choices[0].message.content,
        "tokens_used": response.usage.total_tokens
    }

O segundo caso ilustra o acesso à base de dados. O bloco try/finally não é decorativo: se a atividade falhar e for repetida, deixar uma ligação aberta em cada tentativa esgotará rapidamente o pool do PostgreSQL.

import mistralai.workflows as workflows
import asyncpg

@workflows.activity()
async def save_report(report: dict) -> dict:
    """Saves a report to PostgreSQL."""
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "INSERT INTO reports (title, content, created_at) VALUES ($1, $2, NOW()) RETURNING id",
            report["title"],
            report["content"]
        )
        return {"id": row["id"], "status": "saved"}
    finally:
        await conn.close()

O terceiro caso, o envio de e-mail, é onde os efeitos colaterais são mais visíveis: uma vez enviada a mensagem, nenhuma repetição de tentativa a poderá recuperar.

import mistralai.workflows as workflows
import aiosmtplib

@workflows.activity()
async def send_notification(recipient: str, subject: str, body: str) -> dict:
    """Sends a notification email."""
    message = f"Subject: {subject}\nTo: {recipient}\n\n{body}"
    await aiosmtplib.send(
        message,
        hostname="smtp.example.com",
        port=587,
        username="[email protected]",
        password="secret",
        use_tls=True
    )
    return {"status": "sent", "recipient": recipient}

Características Fundamentais

Em primeiro lugar, uma liberdade bem-vinda: ao contrário dos fluxos de trabalho, as atividades não têm restrições de determinismo. Pode utilizar livremente datetime.now(), uuid.uuid4(), random.random() ou qualquer outra chamada não determinística dentro de uma atividade. É exatamente para isso que servem as atividades — absorver tudo o que o fluxo de trabalho não tem permissão para fazer.

A plataforma trata depois cada chamada de atividade como uma unidade atómica: ou tem sucesso na totalidade ou falha na totalidade, sem nenhum estado intermédio visível para o fluxo de trabalho. Se a sua atividade fizer três coisas e a segunda falhar, o fluxo de trabalho verá apenas uma falha, não um sucesso parcial. É por isso que deve evitar empilhar cinco operações distintas numa única função.

Assim que uma atividade tem sucesso, o seu resultado fica permanentemente registado no registo de eventos do fluxo de trabalho. Durante uma reprodução, a atividade nunca é reexecutada: apenas o resultado registado é utilizado. Em contrapartida, como uma atividade pode ser repetida em caso de falha — tempo limite de rede, erro transitório —, deve ser idempotente: executada várias vezes com os mesmos parâmetros, deve produzir o mesmo resultado. Mudar de um POST para um PUT num identificador estável é frequentemente suficiente para alcançar esta propriedade, como aqui, onde o e-mail serve de chave:

@workflows.activity()
async def create_or_update_client(email: str, name: str) -> dict:
    """Idempotent: uses an upsert instead of an insert."""
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://api.crm.com/clients/{email}",
            json={"name": name, "email": email}
        )
        return response.json()

Nomear uma Atividade

O decorador aceita um nome explícito, o que melhora significativamente a legibilidade dos rastreios quando uma função técnica tem um nome em inglês que ninguém na equipa associa ao domínio de negócio:

@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
    # ...
    pass

Este nome aparecerá nos rastreios OpenTelemetry e facilitará a depuração. Adote o hábito de o definir desde o início: no dia em que estiver a investigar porque é que uma execução demorou quarenta minutos, lerá rótulos significativos em vez de uma lista de nomes de funções.

Restrições de Tamanho

Dois limites regem as trocas: máximo de 2 MB para os parâmetros de entrada e máximo de 2 MB para o valor de retorno. Estes decorrem diretamente da origem de eventos (event sourcing), uma vez que estes valores são serializados e armazenados no registo.

A consequência prática é clara. Se precisar de processar ficheiros grandes — um PDF digitalizado de 40 MB, um arquivo de exportação —, não os passe de atividade para atividade. Armazene-os num serviço externo (S3, GCS) e circule apenas o URL ou o identificador: a atividade descarrega o ficheiro, processa-o, escreve o resultado de volta no armazenamento e devolve uma referência de algumas centenas de bytes.

Pontos-chave

  • Uma atividade é uma função async decorada com @workflows.activity() que realiza o trabalho real (I/O, API, BD)
  • Os parâmetros e valores de retorno devem ser serializáveis em JSON
  • As atividades não têm restrições de determinismo
  • Uma atividade bem-sucedida nunca é reexecutada durante uma reprodução
  • As atividades devem ser idempotentes (mesmo resultado se executadas várias vezes)
  • Limite de 2 MB na entrada e na saída por atividade