Tarefas assíncronas

Algumas operações da WebApiAlcance levam dezenas de segundos ou minutos - gerar PDF de certidão, converter extrato bancário, consultar portais externos. Para não prender o request do cliente, a API aceita a operação, devolve um task_id imediatamente e processa em segundo plano. O cliente consulta o status quando quiser.

Para o LLM esse desacoplamento é fundamental: nenhuma tool MCP bloqueia o usuário esperando um resultado longo. O contrato é sempre devolver o task_id na hora e acompanhar depois.

Fluxo padrão

  1. O cliente chama o endpoint da automação; a API valida e responde com task_id.
  2. A tarefa é processada em segundo plano e o estado é atualizado.
  3. O cliente consulta GET /api/v1/worker-automation/status/{task_id} e recebe o estado atual e, quando houver, o resultado.

Estados possíveis

A tool MCP consultar_status_task propaga os estados literalmente:

EstadoSignificado
PENDINGTarefa aceita, ainda não iniciada.
STARTEDEm execução.
SUCCESSConcluída sem erro. O campo result contém o payload final.
FAILURETerminou com erro. O campo erro traz uma mensagem resumida.
RETRYErro transitório; nova tentativa automática agendada. Não exige ação do usuário.
REVOKEDTarefa cancelada manualmente antes de concluir.

Tool MCP consultar_status_task

Endpoint upstream: GET /api/v1/worker-automation/status/{task_id}. A tool é readOnly e devolve um markdown estruturado:

  • Estado em negrito para leitura rápida.
  • Em SUCCESS, o result aparece como bloco de código (JSON truncado em 500 caracteres).
  • Em FAILURE, a mensagem resumida do erro.
  • Em RETRY, PENDING e STARTED, instrução para consultar novamente em alguns segundos.

O task_id é um UUID v4 - o LLM deve copiá-lo literalmente da resposta da tool que disparou a automação.

Devolva sempre o task_id ao usuário

Tarefas assíncronas não bloqueiam - quando uma tool MCP dispara uma automação, ela retorna o task_id imediatamente. Apresente esse id ao usuário e oriente que ele consulte o progresso com consultar_status_task em alguns segundos. Nunca finja que o resultado já está pronto.