Política de Retentativas
Nesta página
Por que as retentativas são essenciais
Num sistema distribuído, os erros transitórios são inevitáveis: tempos limite de rede excedidos, limites de taxa ultrapassados, serviços temporariamente indisponíveis. Nenhuma destas falhas indica um erro no seu código, mas qualquer uma delas pode causar a falha de um processo se nada absorver o impacto. Uma política de retentativas permite que as suas atividades sobrevivam a estes erros sem intervenção manual, fazendo com que a plataforma as relance automaticamente de acordo com a configuração que definir para cada atividade.
Configurar uma política de retentativas
O decorador @workflows.activity() aceita parâmetros que governam este comportamento. Eis uma atividade de chamada a uma API externa devidamente preparada para a resiliência.
from datetime import timedelta
import mistralai.workflows as workflows
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5),
retry_policy_max_attempts=3,
retry_policy_backoff_coefficient=2.0,
)
async def call_external_api(url: str, data: dict) -> dict:
"""Calls an external API with automatic retry."""
async with httpx.AsyncClient(timeout=60) as client:
response = await client.post(url, json=data)
response.raise_for_status()
return response.json()
Três parâmetros, três funções complementares.
-
start_to_close_timeout— Duração máxima para uma única tentativa de execução. Se a atividade não for concluída dentro deste prazo, é considerada falhada e uma nova tentativa é lançada. -
retry_policy_max_attempts— Número máximo de tentativas. O valor padrão depende da plataforma. Após este número de tentativas, a atividade falha definitivamente e o fluxo de trabalho recebe um erro. -
retry_policy_backoff_coefficient— Multiplicador para o atraso entre tentativas. Com um coeficiente de 2,0, os atrasos duplicam a cada tentativa (1s, 2s, 4s, 8s…). Isto é um recuo exponencial (exponential backoff).
Este mecanismo de recuo merece atenção porque o seu objetivo não é apenas esperar: dá tempo ao serviço em dificuldades para se recuperar, em vez de o sobrecarregar. A progressão de uma chamada que acaba por ter sucesso ilustra isto claramente.
Attempt 1: immediate execution
→ Failure (network timeout)
→ Wait 1 second
Attempt 2: execution
→ Failure (service unavailable)
→ Wait 2 seconds (1 × 2.0)
Attempt 3: execution
→ Failure (rate limit)
→ Wait 4 seconds (2 × 2.0)
Attempt 4: execution
→ Success!
Perante uma resposta “429 Too Many Requests”, este mecanismo é particularmente eficaz: uma política que retentasse imediatamente apenas sustentaria a saturação, enquanto que o aumento do espaçamento acaba por baixar abaixo do limiar do fornecedor.
Nunca omitir o start_to_close_timeout
Este tempo limite é crítico e deve aparecer em todas as atividades, sem exceção. Sem ele, uma atividade que fique bloqueada — deadlock, ligação pendente, serviço que aceita o pedido mas nunca responde — espera indefinidamente e congela todo o fluxo de trabalho. Pior ainda: não desencadeia nenhuma retentativa, pois, na sua perspetiva, ainda não falhou.
# BAD PRACTICE: no timeout
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
# If the service never responds, the activity waits indefinitely
async with httpx.AsyncClient() as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
# GOOD PRACTICE: explicit timeout
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2)
)
async def safe_activity(params: dict) -> dict:
async with httpx.AsyncClient(timeout=90) as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
Para definir o valor, meça primeiro o tempo de execução normal da atividade e, em seguida, adicione uma margem de duas a três vezes para cobrir casos lentos. Finalmente, assegure-se de que o tempo limite interno do cliente HTTP permanece inferior ao start_to_close_timeout — no exemplo acima, 90 segundos contra 2 minutos — para que o erro se propague limparmente a partir do seu código, em vez de ser cortado pela plataforma.
Idempotência: uma condição não negociável
Uma vez que uma atividade pode ser reproduzida várias vezes com os mesmos parâmetros, deve produzir o mesmo efeito, independentemente do número de execuções. Esta propriedade chama-se idempotência e a sua ausência transforma uma política de retentativas num gerador de incidentes.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
"""DANGEROUS: if retried, credit is added multiple times!"""
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://api.billing.com/credits/add",
json={"user_id": user_id, "amount": amount}
)
return response.json()
O cenário temido é comum: a API de faturação processa o pedido corretamente, mas a resposta perde-se na rede. A atividade conclui como falhada, a plataforma retenta e o cliente é creditado duas vezes. Uma chave de idempotência elimina o problema, dando ao serviço remoto uma forma de reconhecer um pedido já processado.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
"""CORRECT: idempotency key prevents duplication."""
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://api.billing.com/credits/add",
json={
"user_id": user_id,
"amount": amount,
"idempotency_key": idempotency_key
}
)
return response.json()
Gere a chave no fluxo de trabalho usando workflow.uuid4(), o que garante que permanece idêntica de uma reprodução para outra — um uuid.uuid4() clássico produziria um novo valor em cada tentativa e cancelaria toda a proteção. Quando o serviço remoto não oferece este mecanismo, existem outras duas vias: upsert na base de dados, usando INSERT ... ON CONFLICT UPDATE em vez de apenas INSERT, ou verificação prévia, que envolve consultar o estado antes de agir.
Três perfis de configuração
Os valores calibram-se de acordo com a natureza da operação. Um pagamento ou notificação deve ter sucesso rapidamente ou falhar rapidamente: tempo limite curto, três tentativas, recuo moderado.
@workflows.activity(
start_to_close_timeout=timedelta(seconds=30),
retry_policy_max_attempts=3,
retry_policy_backoff_coefficient=2.0,
)
async def process_payment(params: dict) -> dict:
# ...
pass
Processamento de longa duração, como geração de relatórios ou inferência pesada, inverte a lógica: cada tentativa custa um tempo de computação significativo, pelo que autoriza menos tentativas com um espaçamento mais amplo.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=15),
retry_policy_max_attempts=2,
retry_policy_backoff_coefficient=3.0,
)
async def generate_ml_report(params: dict) -> dict:
# ...
pass
Perante uma API de terceiros instável sujeita a limitação de taxa, assume finalmente a persistência: cinco tentativas, mesmo que se estenda por vários minutos.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2),
retry_policy_max_attempts=5,
retry_policy_backoff_coefficient=2.0,
)
async def call_third_party_api(params: dict) -> dict:
# ...
pass
Pontos-chave
- Configure sempre o
start_to_close_timeoutpara evitar atividades bloqueadas - O recuo exponencial (
retry_policy_backoff_coefficient) aumenta o atraso entre tentativas retry_policy_max_attemptsdefine o número máximo de tentativas antes da falha definitiva- Atividades com retentativa devem ser idempotentes — mesmo resultado se executadas várias vezes
- Utilize chaves de idempotência ou upserts para garantir a idempotência
- Adapte os tempos limite e as contagens de retentativa ao tipo de operação (rápida vs. longa, estável vs. instável)