Seu Agente de IA Concluiu o Trabalho, Mas a Mensagem Nunca Foi Enviada

Um agente reiniciado pode estar saudável e ainda assim perder a parte mais importante de um fluxo de trabalho: informar ao mundo exterior o que aconteceu.

Isso ocorre porque a recuperação de execução e a recuperação de entrega são domínios de falha diferentes.

• A recuperação de execução pergunta: a tarefa foi executada e podemos reconstruir seu resultado?
• A recuperação de entrega pergunta: a notificação, webhook, email ou efeito colateral saiu do sistema?

Tratar ambos como um único booleano, como status = done, cria uma falha estranha: o agente completou o trabalho, travou antes de enviar a mensagem e, em seguida, se recusou a tentar novamente porque a tarefa já parecia completa.

Este artigo mostra um pequeno padrão que você pode adaptar para um trabalhador agente, executor de ferramenta MCP ou automação agendada.

1. Registre a execução e a entrega separadamente

Use um registro durável em vez da memória do processo. SQLite é suficiente para um protótipo de trabalhador único:

CREATE TABLE IF NOT EXISTS jobs (
  id TEXT PRIMARY KEY,
  input_json TEXT NOT NULL,
  result_json TEXT,
  execution_state TEXT NOT NULL,
  delivery_state TEXT NOT NULL,
  attempt INTEGER NOT NULL DEFAULT 0,
  updated_at TEXT NOT NULL
);

Uma execução bem-sucedida deve definir execution_state = succeeded enquanto deixa delivery_state = pending até que o sistema externo reconheça a mensagem.

2. Torne a operação externa idempotente

A recuperação significa tentar novamente. Tentar novamente sem uma chave de idempotência pode duplicar um email, ticket, implantação ou solicitação de pagamento. Derive a chave do ID do trabalho durável, não de um valor aleatório gerado em cada tentativa:

def deliver(job_id, payload):
    key = f"agent-job:{job_id}"
    response = requests.post(
        "https://example.invalid/webhook",
        json=payload,
        headers={"Idempotency-Key": key},
        timeout=10,
    )
    response.raise_for_status()

O receptor também deve persistir a chave ou, de outra forma, documentar que a deduplica. Um cabeçalho gerado pelo cliente sozinho não é uma garantia.

3. Recupere cada estado de forma independente

Na inicialização do trabalhador, não procure apenas por trabalhos running. Também encontre execuções concluídas cuja entrega ainda está pendente:

SELECT id, result_json
FROM jobs
WHERE execution_state = succeeded
  AND delivery_state IN (pending, failed)
ORDER BY updated_at
LIMIT 20;

Para cada linha: reenvie o resultado armazenado com a mesma chave de idempotência; marque a entrega como enviada apenas após uma resposta de sucesso confirmada; mantenha linhas com falha com um erro e tempo da próxima tentativa; alerte sobre a idade, não apenas a contagem.

4. Teste a janela de falha deliberadamente

Force a terminação após o resultado ser comprometido, antes da entrega, após a entrega, mas antes de marcar como enviado, e durante um tempo limite de entrega. O terceiro caso é o motivo pelo qual a idempotência é importante: o receptor pode ter aceitado a solicitação, mesmo que o trabalhador nunca tenha registrado a resposta.

5. Use esta lista de verificação de aceitação

• [ ] O resultado é durável antes do sucesso da execução.
• [ ] A entrega tem seu próprio estado e cronograma de tentativas.
• [ ] As tentativas reutilizam uma chave de idempotência estável.
• [ ] O receptor deduplica ou expõe um ID de entrega.
• [ ] A recuperação de reinício verifica a entrega pendente.
• [ ] As métricas distinguem falhas de execução de falhas de entrega.
• [ ] Os logs incluem ID do trabalho e tentativa, mas nunca credenciais.

A hospedagem é parte da recuperação

Se um agente deve permanecer disponível para trabalho agendado ou automação de navegador, o host precisa de estado persistente, comportamento de reinício e uma maneira de inspecionar entregas com falha. Uma opção gerenciada, como hospedagem OpenClaw sempre ativa na Ampere, pode ser relevante quando esses requisitos operacionais importam mais do que executar um processo em um laptop. Isso não elimina a necessidade de estado durável ou receptores idempotentes.

A lição prática é simples: “o agente está em execução” é um sinal de atividade, não uma prova de que o trabalho foi recuperado ou entregue. Modele esses limites explicitamente e, em seguida, teste a falha entre eles.