Criar uma Atividade
Nesta página
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
asyncdecorada 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