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
- O cliente chama o endpoint da automação; a API valida e responde com
task_id. - A tarefa é processada em segundo plano e o estado é atualizado.
- 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:
| Estado | Significado |
|---|---|
PENDING | Tarefa aceita, ainda não iniciada. |
STARTED | Em execução. |
SUCCESS | Concluída sem erro. O campo result contém o payload final. |
FAILURE | Terminou com erro. O campo erro traz uma mensagem resumida. |
RETRY | Erro transitório; nova tentativa automática agendada. Não exige ação do usuário. |
REVOKED | Tarefa 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, oresultaparece como bloco de código (JSON truncado em 500 caracteres). - Em
FAILURE, a mensagem resumida do erro. - Em
RETRY,PENDINGeSTARTED, 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.