Quando um agente de IA precisa executar uma tarefa demorada, a aplicação pode aceitar o pedido, devolver um identificador e oferecer uma consulta de andamento. O processamento continua em um executor separado, com estado persistido. Assim, fechar a tela ou perder a conexão não obriga a começar tudo novamente.
O identificador precisa apontar para uma tarefa real e recuperável. Ele não comprova conclusão e não substitui autenticação. A solução depende de um contrato claro entre quem solicita, quem executa e quem entrega o resultado, inclusive quando há falha, repetição ou cancelamento.
Resumo rápido
- Separe aceitação do pedido, execução e entrega do resultado.
- Grave a tarefa de forma durável antes de confirmar o recebimento.
- Documente estados finais e estados que ainda podem mudar.
- Consulte o andamento com intervalo controlado e autorização por usuário.
- Defina recuperação de falhas, prazo de retenção e política de cancelamento.
1. Quando devolver um identificador
Esse desenho faz sentido para atividades como analisar um conjunto de documentos, preparar uma pesquisa comercial ou montar um relatório com várias fontes. Em vez de manter a mesma requisição aberta durante toda a execução, o sistema fornece um endereço para acompanhar a tarefa. O usuário pode retomar a consulta posteriormente.
A especificação HTTP define o código 202 como aceitação para processamento ainda não concluído. Receber esse código não garante que o pedido terá sucesso. A resposta deve ajudar o cliente a encontrar informações sobre seu andamento. A interface pode traduzir isso como “pedido recebido”, evitando uma confirmação prematura de entrega.
Não transforme toda interação em tarefa assíncrona. Uma consulta simples pode ser atendida diretamente. Acrescentar fila, armazenamento e limpeza de resultados tem custo operacional. Use a separação quando a duração, a possibilidade de retomada ou a necessidade de acompanhar etapas justificar essa estrutura.
Também diferencie processamento assíncrono de exibição gradual. Mostrar trechos enquanto o modelo responde resolve outra parte da experiência. Para entender essa distinção, consulte o guia sobre streaming de IA e respostas incompletas. Um texto aparecendo na tela não representa, por si só, uma tarefa persistida que sobreviverá à queda de um processo.
2. Desenhe o contrato de criação e consulta
Uma proposta de API é receber POST /tarefas com o pedido validado e responder com o identificador, o estado inicial e o endereço de consulta. O corpo também pode informar quando o registro será removido. Evite colocar documentos, credenciais ou informações pessoais na própria URL.
O padrão de requisição e resposta assíncronas da Microsoft apresenta o uso de Location para indicar o recurso de acompanhamento e Retry-After para orientar a espera. São decisões que o cliente precisa saber interpretar. Não basta incluir os cabeçalhos e presumir que qualquer ferramenta seguirá o mesmo fluxo automaticamente.
HTTP/1.1 202 Accepted
Location: /tarefas/tarefa_exemplo
Retry-After: 5
{"id":"tarefa_exemplo","estado":"na_fila"}O intervalo acima é apenas ilustrativo. Escolha a frequência conforme a duração do trabalho e a capacidade do serviço. Na consulta, devolva campos estáveis: estado, etapa, horário de criação, última atualização e, quando existir, referência ao resultado. Separe uma mensagem amigável de um código de erro que o suporte consiga pesquisar.
Defina também a resposta para identificador inexistente, acesso negado e resultado expirado. Sem essas distinções, a aplicação pode tratar um erro de digitação como processamento infinito. O consumidor deve parar de consultar quando receber um estado final ou uma resposta que exija intervenção.
3. Estados que ajudam a tomar decisões
Os estados são um acordo do produto. Eles devem permitir que a tela responda à pergunta “o que posso fazer agora?”. Não exponha cada detalhe interno do executor como uma nova situação pública. Isso aumenta o acoplamento e dificulta mudanças futuras na infraestrutura.
| Estado proposto | Significado para o usuário | Próxima ação |
|---|---|---|
| Na fila | Pedido registrado, execução ainda não iniciada | Aguardar ou solicitar cancelamento |
| Executando | Uma etapa está em processamento | Consultar depois |
| Aguardando aprovação | Há uma decisão humana pendente | Abrir a revisão |
| Concluída | Resultado validado e disponível | Consultar o resultado |
| Falhou | A execução terminou sem entregar o combinado | Revisar motivo e eventual nova tentativa |
| Cancelada | O cancelamento foi efetivado | Verificar efeitos já realizados |
“Cancelamento solicitado” pode ser um estado intermediário se o executor precisar terminar uma etapa antes de parar. “Expirado” pode representar a retenção do resultado, sem alterar o fato de que a execução foi concluída. Não confunda o ciclo de vida do trabalho com o prazo durante o qual o arquivo pode ser baixado.
Se houver aprovação humana, estabeleça quem pode aprovar e por quanto tempo. O artigo sobre fila de aprovações de IA aprofunda essa etapa. Uma tarefa esperando autorização não deve parecer travada, nem consumir recursos de processamento enquanto depende de uma pessoa.
Evite percentuais inventados. Quando não há uma medida consistente do total, mostre etapas verificáveis, como “arquivos recebidos” e “revisão em andamento”. Um percentual que volta de noventa para vinte cria mais confusão do que uma descrição honesta do que já terminou.
4. Persistência, repetição e recuperação
Gravar um identificador apenas na memória do servidor é insuficiente para oferecer retomada. O registro precisa guardar proprietário, parâmetros normalizados, estado e referência aos artefatos. O executor recebe o identificador e busca os dados necessários em armazenamento controlado. O histórico de tentativas fica associado à mesma solicitação de negócio.
Há um ponto delicado entre salvar o pedido e enviá-lo à fila. Se o processo cair entre essas ações, o sistema pode ter um registro sem execução. Uma implementação possível é manter o pedido e uma pendência de envio na mesma transação do banco; um publicador separado entrega as pendências à fila. Essa é uma proposta de arquitetura, que exige testes de concorrência e reconciliação.
Planeje a repetição antes de habilitar novas tentativas automáticas. Uma etapa que gera um rascunho tem consequências diferentes de uma etapa que envia uma mensagem. Associe cada efeito externo a uma chave estável e verifique se ele já aconteceu antes de repeti-lo. O identificador da tarefa ajuda na rastreabilidade, mas não elimina duplicidades sozinho.
A documentação de tarefas do Celery discute idempotência, que é a capacidade de repetir uma operação sem criar um novo efeito indevido, e mecanismos de novas tentativas. Se essa ferramenta for adotada, revise suas opções de confirmação de mensagens conforme o comportamento da tarefa. Não copie uma configuração de exemplo sem avaliar o que acontece quando o executor morre.
Um sinal periódico de atividade pode ajudar a detectar execuções abandonadas. A ausência de atualização deve acionar investigação ou recuperação controlada. Ela não prova que o serviço externo deixou de trabalhar. Antes de recomeçar uma etapa com efeitos, reconcilie o estado conhecido e registre por que uma nova tentativa foi autorizada.
5. Exemplo: relatório comercial em Belo Horizonte
Considere uma distribuidora de materiais elétricos em Belo Horizonte que quer um relatório de oportunidades com base em arquivos enviados pela equipe. O cenário é ilustrativo. O agente organiza os documentos, extrai informações e prepara uma síntese para revisão comercial. Nenhum resultado financeiro é presumido.
Ao enviar os arquivos, a atendente recebe um protocolo e vê a tarefa na lista de trabalhos. O sistema confirma o recebimento somente depois de registrar o pedido. O executor começa pela conferência dos anexos e atualiza a etapa visível. Se um arquivo estiver ilegível, informa qual documento precisa ser substituído, sem concluir o relatório com uma lacuna silenciosa.
A atendente fecha o navegador. Mais tarde, entra novamente e abre o mesmo protocolo. A consulta exige a mesma autorização de acesso aos documentos originais. Quando o relatório fica pronto, o sistema mostra a versão gerada e suas fontes. O envio ao cliente permanece uma ação separada, aprovada por uma pessoa.
Se a conexão cair depois do primeiro envio, a interface reutiliza a chave de solicitação definida para aquele pedido. O servidor retorna a tarefa já criada em vez de iniciar outro relatório. Caso a atendente altere os arquivos, isso passa a ser uma nova solicitação ou uma revisão explicitamente identificada. O histórico distingue uma repetição técnica de uma mudança real de escopo.
Antes da liberação, a equipe simula interrupção do executor, duas consultas simultâneas e um pedido de cancelamento durante a geração. O critério de aceitação é observar um resultado coerente em cada situação: tarefa recuperável, nenhum envio duplicado e explicação clara de quais etapas terminaram.
6. Erros comuns
Confundir o prazo da consulta com o prazo do trabalho. A referência de resultados assíncronos do Celery diferencia a espera do cliente da execução: atingir o tempo de espera ao buscar um resultado não encerra automaticamente a tarefa. A aplicação precisa tratar esses eventos separadamente.
Devolver um protocolo antes de garantir persistência. O usuário guarda uma referência que o sistema perdeu. Teste a queda imediatamente após a resposta de aceitação e verifique se a consulta posterior encontra o pedido.
Usar o identificador como senha. Um protocolo compartilhado em um chamado de suporte não deve liberar documentos. Autorize criação, consulta, cancelamento e download de forma independente, conforme as regras do negócio.
Prometer cancelamento imediato. Parar a aplicação não desfaz uma mensagem enviada ou um arquivo já publicado. Mostre quando a solicitação foi recebida e quando o cancelamento foi confirmado, incluindo os efeitos preservados.
Guardar resultados indefinidamente. Defina retenção para arquivos, registros e erros. Na limpeza, preserve somente o necessário para explicar o ocorrido. Se uma credencial expira durante o trabalho, trate a renovação conforme o guia de credenciais temporárias para agentes, sem copiá-la para o histórico da tarefa.
7. Perguntas frequentes
Preciso de uma fila para devolver um identificador?
Não necessariamente. Você precisa de execução desacoplada e estado durável, com mecanismos coerentes de recuperação. Uma fila é uma alternativa frequente, mas um agendador que busca tarefas pendentes também pode atender ao projeto. A decisão depende do volume, das garantias necessárias e da capacidade de operação da equipe.
O usuário deve deixar a página aberta?
O objetivo desse desenho é permitir que ele volte depois. Para isso, o trabalho precisa sobreviver ao encerramento da conexão e aparecer em uma lista autenticada de solicitações. Um script executado apenas na aba do navegador não oferece essa mesma garantia.
Como reduzir consultas repetidas?
Oriente o intervalo de consulta, aumente a espera após respostas sem mudança e pare ao atingir um estado final. Acrescente variação aos intervalos para evitar que muitos clientes consultem juntos. Também ofereça atualização manual e indique quando o estado foi verificado pela última vez.
Um webhook elimina o endereço de consulta?
É prudente manter uma forma de reconciliação. A notificação pode avisar que houve mudança, enquanto a consulta autenticada informa o estado atual. Isso ajuda quando uma entrega se perde, chega repetida ou encontra o sistema consumidor indisponível.
Quando considerar a tarefa concluída?
Quando o resultado combinado estiver validado, persistido e acessível ao usuário autorizado. Terminar a chamada ao modelo pode ser apenas uma etapa. Verifique também a gravação do arquivo, a integridade das referências e a disponibilidade do destino antes de publicar o estado final.
