Processamento assíncrono de agentes
O que significa assíncrono aqui
Por padrão, a REDA AI executa o loop agêntico de forma síncrona. A mensagem do usuário chega, a plataforma chama o modelo, o agente usa ferramentas, o modelo produz uma resposta final e o registro da conversa é atualizado — tudo dentro da transação que fez a chamada. O usuário (ou o Fluxo, ou o sistema externo) recebe a resposta na própria chamada.
Algumas solicitações não cabem em uma única transação. O motivo mais comum é um payload de arquivo grande o suficiente para superar os limites de processamento síncrono do Salesforce. Quando a plataforma detecta essa condição, ela muda para o processamento assíncrono em vez de falhar.
O que o chamador vê
As solicitações roteadas de forma assíncrona retornam imediatamente com dois campos reveladores na resposta:
| Campo | Significado |
|---|---|
isAsync | true quando a solicitação foi roteada para processamento em segundo plano. |
asyncRequestId | O Id do registro de Solicitação assíncrona que rastreia o trabalho. |
conversationId | A conversa à qual a solicitação pertence. A resposta final do agente chega como uma nova Mensagem nessa conversa. |
O campo síncrono response fica vazio quando isAsync é true — a resposta real ainda não foi gerada. Os chamadores devem ramificar com base em isAsync e, ou fazer polling até a conclusão, ou aguardar a conversa receber a nova Mensagem.
O ciclo de vida da Solicitação assíncrona
Cada solicitação roteada de forma assíncrona cria um registro de Solicitação assíncrona que a plataforma atualiza à medida que o trabalho avança:
| Status | Significado |
|---|---|
| Em fila (Queued) | O Queueable foi enfileirado; o processamento ainda não começou. |
| Em processamento (Processing) | O processador em segundo plano assumiu a solicitação e está chamando o modelo. |
| Complete (Complete) | O trabalho terminou corretamente; a resposta está disponível na conversa. |
| Error (Error) | O trabalho falhou mesmo após a nova tentativa. O campo Error Message (Mensagem de erro) do registro contém o motivo. |
Outros campos do registro fornecem o contexto completo: a Conversa e a mensagem do usuário relacionadas, a Definição de Agente que tratou a solicitação, o contexto de registro ao qual a solicitação estava vinculada, os IDs dos arquivos em processamento, os contadores de novas tentativas e um timestamp de quando o trabalho terminou.
Tratamento de falhas
Uma solicitação assíncrona que falha não é repetida. Quando o processador em segundo plano encontra um erro, ele grava Error no Status da Solicitação assíncrona e o motivo em Error Message, e para por aí. Nada a recoloca na fila — nem um erro transitório do modelo, nem um callout interrompido.
Implemente sua própria repetição se o trabalho importa. Um Flow que chama um agente de
forma assíncrona e considera a entrega garantida perderá o turno em qualquer falha transitória. Verifique
o Status da Solicitação assíncrona e invoque de novo quando for Error.
O registro traz os campos Retry Count e Max Retries. O Retry Count é incrementado uma vez quando a solicitação é retirada da fila, mas nenhum código o compara ao Max Retries, então hoje nenhum dos dois campos muda o que acontece.
Os erros continuam visíveis: a menos que quem chamou tenha desligado o log de incidentes, a falha é capturada nos Registros de incidentes de IA com sua classe, método e stack trace, que é onde olhar primeiro.
Como os canais lidam com o assíncrono
UI interna do Salesforce (widget de chat em uma página de registro)
O widget de chat detecta isAsync e exibe um estado de espera amigável. Quando a conversa recebe a nova mensagem do agente, o widget é atualizado no local. Os usuários veem um breve atraso; fora isso, a conversa permanece inalterada.
Widget externo
O widget externo em um site público detecta isAsync e exibe um estado de espera semelhante. Como o widget faz polling em vez de streaming, o usuário vê a resposta chegar poucos segundos após a conclusão.
Chamadores via Fluxo / API
Para chamadores orientados por Fluxo e de API direta, o assíncrono exige um tratamento explícito. O padrão mais simples é um Fluxo acionado por registro no objeto Solicitação assíncrona: quando o registro atinge Complete, dispare o que quer que a integração precise em seguida — publicar a resposta de volta em um sistema de mensageria, atualizar um registro, enviar um e-mail. Veja Integração do canal de mensageria para o padrão mais amplo.
Canal de e-mail — Entrada
E-mails de recebimento de documentos sempre são executados de forma assíncrona por design. O manipulador do Email Service armazena os anexos e enfileira um Queueable; o agente é executado em segundo plano. Veja Canal de e-mail — Entrada.
Observabilidade
- O registro da solicitação assíncrona é a principal fonte da verdade: status, contagem de novas tentativas, mensagem de erro, timestamp de conclusão.
- A conversa mostra a mensagem do usuário imediatamente e a resposta do agente quando o trabalho assíncrono é concluído — sem mensagens de “em andamento”.
- O Conversation Debugger mostra o prompt montado, as chamadas de ferramentas e os créditos usados na execução final do agente, de forma idêntica a uma execução síncrona.
- O Registro de incidentes de IA captura qualquer falha que esgote o orçamento de novas tentativas. Veja Registros de incidentes de IA.
Projetando agentes para o assíncrono
A maioria dos agentes não precisa de nenhum design especial para o assíncrono — o roteamento é automático e a conversa se comporta da mesma forma. Há duas considerações de design que vale a pena ter em mente:
Orçamento de tokens. O caminho assíncrono é executado em um Queueable, que tem seus próprios limites reguladores. Loops agênticos muito longos ou prompts com tamanho excessivo ainda podem atingir limites no modo assíncrono. Mantenha o orçamento de tokens do agente realista e divida trabalhos muito longos em vários turnos sempre que possível.
Cartões de confirmação. As confirmações de ação exigem uma UI capaz de renderizar um cartão. Em canais somente assíncronos (recebimento de e-mail, execuções orientadas por Fluxo, integrações de mensageria), ative Auto Execute Actions (Execução automática de ações) no agente ou restrinja o conjunto de ferramentas a ferramentas que não exigem confirmação. Veja Confirmação de Ação.
Boas práticas
Ramifique com base em isAsync nos chamadores personalizados. Tratar a resposta como síncrona quando isAsync é true deixará os chamadores esperando por uma resposta que nunca chega naquela chamada.
Use um Fluxo acionado por registro no objeto Solicitação assíncrona para os desdobramentos. É a forma mais limpa de reagir quando uma execução assíncrona é concluída — disparando um callback, publicando uma resposta por outro canal ou atualizando um campo de status.
Não espere que as novas tentativas corrijam toda falha. A maioria das falhas assíncronas não é transitória. Se uma solicitação ficar em Error, a entrada no Registro de incidentes de IA é o lugar certo para começar a investigar — cadeias longas de novas tentativas raramente transformam uma falha real em sucesso.
Monitore a profundidade da fila. Um acúmulo de registros em Em fila significa que o trabalho assíncrono está chegando mais rápido do que pode ser processado. Ajuste o design do agente (conjuntos de ferramentas mais enxutos, orçamentos de tokens menores) antes de aumentar a concorrência.
Automação e confiabilidade
Invocações em massa pelo Flow podem retornar IDs de solicitações adiadas em vez de respostas imediatas. Revise elementos seguintes que esperam resposta, créditos ou resultados na mesma transação. Ações automáticas preservam canal e modo configurados e registram resultados reais no contexto, sem garantir uma narração adicional. Deslocamentos horários explícitos são preservados nos caminhos compatíveis de eventos, agendamentos, gravação de campos e CSV. Sem deslocamento, permanece a interpretação do usuário executor. O modo Sistema não gera avisos apenas por ser usado; registros e notificações de nível ERROR permanecem. Extração respeita o limite de saída, cores funcionam nos temas Salesforce compatíveis e testes empacotados evitam referências estáticas que bloqueavam instalação sem tipos de registro de Conta.
Perguntas frequentes
O gatilho mais comum é um payload de arquivo grande demais para caber dentro dos limites de processamento síncrono do Salesforce. A plataforma detecta essa condição antes de chamar o modelo e roteia a solicitação para um job em segundo plano.
O roteamento assíncrono é decidido pela plataforma com base no formato da solicitação, e não é acionado pelo chamador. Para estruturar o trabalho como assíncrono por design — por exemplo, uma execução em segundo plano acionada por Fluxo sem nenhum usuário aguardando a resposta — roteie por meio da ação invocável do Fluxo e deixe a plataforma decidir se executa em linha ou transfere para segundo plano.
A chamada ao modelo em si custa o mesmo; o assíncrono só muda onde o trabalho roda. A única diferença de crédito vem das novas tentativas em caso de falha — cada nova tentativa que chama o modelo novamente consome créditos da forma normal.
O widget de chat exibe um estado de espera enquanto a solicitação assíncrona está em andamento. Para canais não interativos, projete a integração para expor o status — para integrações de mensageria, um indicador de digitação; para e-mail, uma resposta provisória; para chamadores via Fluxo, um campo de status no registro pai.
A solicitação assíncrona fica com status Error, com a mensagem de erro registrada. Um registro de Registro de incidentes de IA também é criado. A conversa contém a mensagem do usuário, mas nenhuma resposta do agente — as integrações devem detectar o status Error e tentar novamente com o usuário ou exibir a falha de forma clara.
Sim. O caminho assíncrono executa o mesmo loop agêntico do caminho síncrono; as ferramentas são executadas da mesma forma. Observe que os cartões de confirmação exigem uma UI para serem renderizados; em canais somente assíncronos, configure o agente para Auto Execute Actions (Execução automática de ações) ou restrinja o conjunto de ferramentas a ferramentas de leitura e ações que não exigem confirmação.
No Conversation Debugger dessa conversa. O Debugger mostra a montagem do prompt, cada chamada de ferramenta, as respostas do modelo e os créditos consumidos — de forma idêntica à inspeção de uma execução síncrona.
Próximos passos
Leia Integração do canal de mensageria para um padrão completo que usa o processamento assíncrono, ou Invocando a REDA AI a partir de Fluxos para o lado do contrato que cabe ao chamador via Fluxo.