Enfileirar Agentes
A seção Modo de enfileiramento do disparo das etapas de agentes: quando uma lista vira muitas execuções, escolher quantas ficam de pé ao mesmo tempo, em vez de soltar todas de uma vez.
Em resumo
- A seção Modo de enfileiramento do disparo aparece quando a etapa gera mais de uma execução do mesmo agente, ou seja, quando Disparar por cada item de uma lista está ligado. Ela decide quantas dessas execuções ficam de pé ao mesmo tempo.
- Todos ao mesmo tempo é o padrão e é o comportamento de sempre: duzentos itens viram duzentas execuções saindo juntas. No plano Free o Ambiente Runtime roda uma execução por vez: as execuções saem juntas e rodam uma depois da outra, na fila do runtime.
- Uma quantidade específica por vez, com o valor 1, faz a lista andar em ordem: a segunda execução só começa quando a primeira termina. Um valor maior, como 3 ou 5, mantém essa quantidade de pé e vai repondo conforme cada uma acaba.
- Serve a dois casos: o sistema de destino que não aceita vários acessos ao mesmo tempo, e a máquina que não aguenta muitos navegadores juntos.
- A fila não morre com uma falha. Uma execução que falha não para a lista: as seguintes continuam saindo, e a etapa só falha no fim, listando as que falharam. A lista para em três casos: um prazo estourado, um disparo recusado (crédito que acabou, nenhum runtime ligado) ou o agente principal parado. O que não chegou a sair fica no registro como "não foi disparada".
- Não é a mesma coisa que o teto do Ambiente Runtime (Enfileirar Jobs, com o número de execuções ao mesmo tempo) nem que o teto do agente (Execuções ao mesmo tempo, nas configurações do agente). São três tetos, com donos diferentes, que valem ao mesmo tempo. Comparação: Os três tetos.
- A lista só anda enquanto o agente que disparou está no ar. Por isso, com a espera em Não esperar, a quantidade específica por vez precisa de uma etapa Aguardar Agentes mais à frente no fluxo que aguarde esse disparo. Sem ela a etapa salva, mas entra na lista de pendências e a publicação fica bloqueada. Detalhes: Com Não esperar.
Para que serve
Uma etapa que dispara por item de uma lista multiplica o agente chamado pelo tamanho da lista. Duzentos pedidos são duzentas execuções, e cada uma abre o próprio navegador. Por padrão o lote inteiro sai junto, e o tempo total é o da execução mais demorada, não a soma de todas.
Em dois casos não é:
- O sistema de destino não aceita. Exemplos: um portal que aceita um acesso por usuário e derruba a sessão anterior quando a segunda entra; um ERP que trava o registro enquanto alguém o edita; uma API que corta quem passa de algumas chamadas por minuto. O limite está no outro lado, não na máquina.
- A máquina não aguenta. Um runtime em um servidor modesto com duzentos navegadores abertos ao mesmo tempo fica lento, estoura o tempo de carregamento de página e derruba execuções.
Nos dois casos, a saída é a mesma: soltar a lista aos poucos, em vez de toda de uma vez.
Se a ordem dos itens não importa, o sistema de destino aguenta e a máquina tem folga, deixe todos ao mesmo tempo. É mais rápido, e uma lista enfileirada leva a soma do tempo de todas as execuções.
Onde a seção aparece
A seção Modo de enfileiramento do disparo entra no painel quando o agente gera mais de uma execução:
- numa etapa Chamar Agente, ao ligar Disparar por cada item de uma lista;
- num Paralelizar Agentes, em cada bloco de agente que tenha a repetição por item ligada. Cada agente escolhe por conta própria: um pode soltar a lista dele de uma vez e o outro ir de uma em uma.
Sem a repetição por item, a etapa dispara uma execução só daquele agente e não há o que escalonar: a seção não aparece. Desligar a repetição tira a seção do painel e a etapa volta a disparar essa única execução na hora.
A quantidade por vez vale para a lista de um agente, não para a etapa inteira. Num Paralelizar Agentes com quatro agentes, os quatro continuam saindo juntos; o que um deles escalona é a lista dele. É o segundo nível: paralelo entre agentes, escalonado dentro de cada um. Paralelizar Agentes existe a partir do plano Professional (Planos).
Como se configura
Todos ao mesmo tempo
O padrão, e o que sempre existiu. Cada item da lista vira uma execução e todas são disparadas de uma vez. A etapa termina de disparar em segundos, e o que decide o tempo total é a execução mais demorada.
Uma quantidade específica por vez
Você escolhe, no campo lote(s) por disparo, quantas execuções daquela lista ficam de pé ao mesmo tempo. O valor 1 é o caso mais comum: uma execução de cada vez, na ordem dos itens da lista, e a próxima só começa quando a anterior termina. Um valor maior mantém essa quantidade trabalhando e repõe conforme cada uma acaba: com 3, saem as três primeiras, e a quarta entra quando uma das três terminar.
A ordem é sempre a da lista. Com 1 por vez, a ordem de execução é exatamente a ordem dos itens; com um valor maior, os itens entram nessa ordem, mas terminam na ordem em que cada um acabar. A lista em que cada retorno é armazenado continua sempre na ordem dos itens, independentemente disso.
Enquanto a lista anda, o log do agente principal diz o que está acontecendo: quantas execuções já terminaram, quantas faltam e qual item está rodando agora.
Com Não esperar
No disparo sai só a primeira leva. O resto da lista quem solta é o agente principal, a cada execução que termina, e só enquanto ele estiver no ar. Por isso a etapa precisa de um Aguardar Agentes mais à frente no fluxo que aguarde esse disparo: com todos os disparados sem esperar, ou com esta etapa marcada. É ele que segura o agente principal até a lista acabar.
Sem esse Aguardar a etapa salva normalmente. O painel mostra em vermelho, e a lista de pendências repete, a frase Disparos em lotes precisam de uma etapa Aguardar Agentes na continuação do fluxo, aguardando este disparo, e a publicação fica bloqueada até o Aguardar existir. A pendência volta se o Aguardar for apagado, for movido para antes da etapa ou passar a aguardar só outra etapa.
Onde se altera depois
No mesmo painel, e vale a partir da próxima execução do agente principal. Mudar a quantidade não alcança um lote que já está andando.
Os três tetos: ambiente, agente e etapa
A plataforma tem três lugares onde se limita quantas execuções ficam de pé ao mesmo tempo, e eles não se substituem: cada um responde a uma pergunta diferente e tem um dono diferente. Os três valem ao mesmo tempo, e uma execução só começa quando cabe nos três.
| Teto do ambiente | Teto do agente | Modo de enfileiramento do disparo: uma quantidade específica por vez | |
|---|---|---|---|
| Onde se liga | No cadastro do Ambiente Runtime: Enfileirar Jobs com o número de Execuções ao mesmo tempo (1 é uma por vez). No plano Free é sempre 1. | Nas configurações do agente, Execuções ao mesmo tempo (0 é sem teto). | No painel da etapa, em cada agente que dispara por item de uma lista. |
| Quem decide | Quem cuida da máquina. | Quem cuida do agente e do sistema que ele acessa. | Quem monta o fluxo. |
| A pergunta que responde | Quantas execuções, de qualquer agente, esta máquina aguenta ao mesmo tempo? | Quantas vezes este agente pode estar rodando ao mesmo tempo numa máquina? | Quantos itens desta lista saem de uma vez? |
| O que ele segura | Tudo que chega naquela máquina: API, agendamento, webhook, Control Room, execução manual e agentes chamados por outro agente. | As execuções daquele agente, venham de onde vierem, naquela máquina. | As execuções que aquela etapa dispara por item da lista. |
| Quem espera, onde espera | Na fila do ambiente, em ordem de chegada. Um agente chamado por outro entra na frente das execuções de sempre. | Na fila do ambiente, sem tomar a vez dos outros agentes: a vaga que ele não pode usar vai para o próximo. | Ainda não saiu: fica com o agente principal, que a solta quando uma vaga da lista abre. |
| Alcance | Uma máquina. | Uma máquina por vez: com a Distribuição do processamento, cada runtime aplica o teto na dele. | Aquele agente, naquela etapa, naquela execução do agente principal, somando todas as máquinas. |
Onde os três se encontram
Na mesma máquina, ao mesmo tempo. Uma execução só começa quando cabe nos três, e as regras de convivência são estas:
- O agente principal que espera não ocupa vaga. Enquanto ele espera um agente chamado (nesta etapa, ou num Aguardar Agentes), ele solta a vaga dele no teto do ambiente e a pede de volta quando o retorno chega, com prioridade sobre tudo que espera na fila. É isso que evita o impasse de um teto de 1 com o agente chamado esperando atrás de quem o chamou. O navegador do agente principal continua aberto nesse meio-tempo, e ele continua contando no teto do próprio agente dele.
- O agente chamado entra na frente. Na fila do ambiente, a execução de um agente chamado por outro passa na frente das execuções de sempre que esperavam: ela é parte de um trabalho que já está de pé, e terminar o que está de pé libera a máquina mais cedo.
- Uma quantidade específica por vez conta com os outros dois. Com 3 por vez numa máquina de teto 2, saem três da lista, mas só duas começam; a terceira espera vaga na fila do ambiente. Com o agente chamado limitado a 1 execução ao mesmo tempo, uma quantidade por vez maior que 1 não muda nada: o teto do agente segura o resto. O log do agente principal diz "iniciada" quando o Router entregou a execução ao runtime; ela pode estar esperando vaga lá.
- Não esperar com uma quantidade específica por vez, na mesma máquina, com teto 1. O agente principal segue o fluxo dele ocupando a única vaga, e a lista só anda enquanto ele espera, no Aguardar Agentes mais à frente: até lá, a primeira execução da lista fica na fila. Numa máquina com mais vagas, ou em outra máquina, a lista anda desde o começo.
- Anular fila por exceção, do ambiente, vale só para as execuções de sempre. Um item da sua lista que falha não cancela a fila da máquina, e uma execução de sempre que falha não cancela agente chamado.
Resumo: o teto do ambiente limita a máquina, o teto do agente limita o sistema de destino, e a quantidade por vez controla a lista. Repartir um lote grande entre várias máquinas (seção Distribuição do processamento): Balancear Carga dos Agentes.
O que muda na espera e no tempo
A escolha da seção Comportamento a cada disparo continua valendo, e é ela que diz até onde o agente principal acompanha a lista:
| Comportamento a cada disparo | Com uma quantidade específica por vez |
|---|---|
| Esperar finalizar | O agente principal espera a lista inteira terminar. O tempo dele passa a ser a soma das execuções, não a mais demorada: uma lista de duzentos itens de um minuto cada segura o agente principal por mais de três horas. Não há prazo escolhido, mas há um teto: 24 horas por execução; passou, a etapa falha como um prazo estourado. Ele fica no ar do começo ao fim. Se o runtime do agente chamado sair do ar no meio de uma execução, a plataforma devolve a falha dela ao agente principal (em 5 ou 30 minutos; detalhes: Quando o runtime do agente chamado sai do ar) e a lista segue para a próxima. |
| Esperar até um prazo | O prazo vale para cada execução da vez, não para a lista inteira. Uma execução que estoura o prazo faz a etapa falhar, como sempre, e o que ainda não saiu não é disparado. |
| Esperar a resposta antecipada | Mesma regra: o prazo é o da execução da vez. A vaga é liberada quando a resposta antecipada chega, e a próxima execução da lista entra nesse momento, mesmo que a anterior siga trabalhando. |
| Não esperar | O fluxo segue na hora, mas alguém precisa ir soltando o resto da lista, e quem faz isso é o agente principal enquanto ele estiver no ar. Se ele terminar antes da lista acabar, o que faltava não é disparado. Por isso essa combinação precisa de um Aguardar Agentes mais à frente que aguarde esse disparo, que é o que garante que o agente principal ainda estará lá. Detalhes: Com Não esperar. |
Enquanto espera, o agente principal solta a vaga dele no teto do ambiente e a pede de volta quando o retorno chega (veja Os três tetos). Se a máquina estiver cheia nessa hora, ele espera uma vaga abrir para seguir o fluxo.
Uma lista longa em Esperar finalizar não tem prazo escolhido: só o teto de 24 horas por execução. A plataforma cobre o runtime que cai ou fica desligado, mas não tem como saber que uma execução viva vai demorar mais do que deveria, e 24 horas é tempo demais para um agente parado em produção. Prefira Não esperar com um Aguardar Agentes com teto mais à frente, ou Esperar até um prazo quando cada execução é curta, e mantenha o Limitador de Ações do agente chamado no tamanho real do trabalho. Detalhes: Quando o runtime do agente chamado sai do ar.
Parar o agente principal no meio de uma lista enfileirada cancela o que ainda não foi disparado e alcança o que está rodando, como em qualquer espera. Pausar segura a lista onde ela está e pausa a execução da vez, como em qualquer espera; retomar solta as duas, e a próxima só entra quando uma vaga abrir.
Com a Distribuição do processamento e com o fluxo offline
Com a Distribuição do processamento. As duas coisas se somam e respondem a perguntas diferentes: a quantidade por vez diz quantas execuções ficam de pé, e a Distribuição do processamento diz em qual máquina cada uma roda. Com 6 por vez e três runtimes na distribuição, são seis execuções de pé, repartidas entre as três máquinas conforme a carga de cada uma no momento em que cada execução sai. Com 1 por vez, distribuir deixa de fazer diferença: há sempre uma só rodando, e ela vai para a máquina mais livre do momento. O teto do próprio agente chamado vale por máquina: com ele limitado a 1 e três runtimes na distribuição, podem rodar três, uma em cada.
Com o fluxo offline. Se o runtime do agente chamado está desligado e o ambiente dele tem Manter fluxo offline ligado, a execução da vez fica guardada até o runtime voltar, e a lista para ali: a próxima só sai quando essa terminar. Se o runtime não voltar em 30 minutos, a plataforma cancela essa execução e devolve a falha ao agente principal, e a lista segue para a próxima, que espera do mesmo jeito. Sem o fluxo offline, a primeira execução é recusada na hora e a etapa falha, sem disparar o resto.
Créditos e limites
- Escalonar não muda o preço: cada execução do agente chamado consome 1 crédito da empresa dona dele, além do crédito do agente principal.
- O saldo é conferido para a lista inteira antes da primeira execução sair. Se ele não cobrir, nada é disparado e a etapa falha dizendo quantos créditos faltam.
- Como uma lista enfileirada acontece ao longo do tempo, outro consumo da empresa no meio do caminho pode esgotar o saldo depois que a lista começou. Nesse caso as execuções seguintes são recusadas e a etapa falha dizendo em qual item ela parou. As que já rodaram ficam como estão.
- O teto de 5000 execuções por etapa, somando todos os agentes dela, continua valendo do mesmo jeito.
- No ▶ do editor a chamada é real e cobrada. Uma lista longa em 1 por vez mantém o editor esperando do primeiro ao último item: para testar o fluxo sem isso, use uma lista curta, fixe a saída da etapa (📌) ou ignore a etapa (🚫).
Limites e tetos
Tudo que tem número nesta funcionalidade, o que acontece ao passar dele e como contornar quando a necessidade é maior:
| Limite | Valor | O que acontece ao passar | Contorno |
|---|---|---|---|
| Itens por lista no disparo por item | 5000 | Nada é disparado; a etapa falha dizendo quantos itens a lista tem. | Quebre a lista em pedaços de até 5000: uma Regra Customizada que fatia a lista e um laço que volta à etapa a cada pedaço (Loop), ou dispare por partes a partir de quem gera a lista. |
| Execuções por etapa, somando todos os agentes e itens | 5000 | Nada é disparado; a etapa falha dizendo quantas dispararia. | Mesmo contorno: pedaços menores, ou uma etapa por agente em vez de um Paralelizar com todos. |
| Quantidade específica por vez (lote(s) por disparo) | Sem teto: qualquer valor a partir de 1 | Um valor igual ou maior que a lista é o mesmo que todos ao mesmo tempo. | Não precisa: escolha "Todos ao mesmo tempo". |
| Prazo de espera por execução (Esperar até um prazo, resposta antecipada) | 1 a 120 segundos | Estourou: a etapa falha e, com uma quantidade específica por vez, o que ainda não saiu não é disparado. | Para execuções longas, use Esperar finalizar (sem prazo), ou Não esperar com um Aguardar Agentes mais à frente, que aceita teto de até 24 horas. |
| Esperar finalizar (sem prazo escolhido) | Teto de 24 horas por execução | Passou: a etapa falha como um prazo estourado e, com uma quantidade específica por vez, o que ainda não saiu não é disparado. | Uma execução que leva mais de um dia é sinal de que o trabalho deve ser fatiado; o log avisa desde o começo que a plataforma desiste em 24 h. |
| Teto do Aguardar Agentes | Até 24 horas; "sem teto" também desiste em 24 horas | Estourou: o status da espera vale TIMEOUT e o fluxo segue ou a etapa falha, como configurado. | Uma lista que leva mais de um dia é sinal de que o lote deve ser fatiado em execuções separadas do agente principal, por agendamento. |
| Agentes numa etapa Paralelizar Agentes | 6 | A etapa não aceita o sétimo. | Duas etapas Paralelizar em sequência, ou um Aguardar Agentes reunindo as duas. |
| Profundidade de chamadas (agente que chama agente que chama agente) | 5 níveis | O disparo é recusado antes de sair, e a etapa falha. | Achatar a cadeia: o agente do nível de cima chama os de baixo diretamente. |
| Runtimes numa distribuição (Distribuição do processamento) | 20, e pelo menos 2 ligados | Só os vinte primeiros marcados contam; com menos de 2 ligados o disparo é recusado. | Vários ambientes equivalentes marcados; se todos podem cair, deixe Fluxo offline no ambiente do próprio agente e use "Ambiente do próprio agente". |
| Teto do ambiente (Enfileirar Jobs com número) | 1 ou mais, no cadastro do ambiente | A execução que não cabe espera na fila do ambiente; o agente principal que espera agente chamado solta a vaga dele. | Aumente o número se a máquina aguenta, ou reparta entre máquinas com a Distribuição do processamento. |
| Teto do agente (Execuções ao mesmo tempo) | 0 é sem teto; 1 ou mais, nas configurações do agente | A execução que não cabe espera na fila do ambiente sem tomar a vez dos outros agentes. | Se o sistema de destino aceita mais acessos, suba o número; se não aceita, é ele quem manda. |
| Créditos | 1 por execução do agente chamado, além do crédito do agente principal | Sem saldo para a lista inteira, nada é disparado; saldo que acaba no meio para a lista no item em que faltou. | Confira o saldo em Meus Agentes antes de um lote grande, ou fatie o lote por dia. |
Quando algo dá errado
| Situação | O que acontece |
|---|---|
| A máquina do agente chamado está no teto (Enfileirar Jobs com número, ou o teto do próprio agente) | A execução espera vaga na fila do ambiente, na frente das execuções de sempre. O log do agente principal diz "iniciada" porque o Router a entregou, e a espera conta no prazo, se houver. Com uma quantidade específica por vez, a próxima só sai quando essa terminar. |
| Uma execução da lista falha | A lista continua: as execuções seguintes são disparadas normalmente. No fim, a etapa falha listando as que falharam e entra na Gestão de Erros, como já acontece com a lista disparada de uma vez. O registro de cada item diz o status dela e em que etapa do agente chamado ela parou. |
| Uma execução estoura o prazo | A etapa falha nesse ponto e o que ainda não saiu não é disparado. A execução que estourou o prazo continua rodando até o fim dela, e o log avisa. |
| Não esperar com uma quantidade específica por vez, sem Aguardar Agentes no fluxo | O painel não aceita a combinação e diz por quê: sem alguém esperando, o agente principal pode terminar antes da lista e o resto não seria disparado. Escolha outra espera ou ponha um Aguardar Agentes. |
| O agente principal é parado no meio da lista | O que ainda não foi disparado é cancelado e nada dele é cobrado. A execução da vez é parada junto, como em qualquer espera. |
| O runtime do agente principal cai no meio da lista | O que já rodou fica registrado. O que ainda não tinha saído não sai, porque era ele quem soltava a lista. A execução que estava rodando segue até o fim dela, sem ninguém para receber o retorno, e a plataforma desfaz o vínculo entre os dois. |
| O runtime do agente chamado está desligado | Sem Manter fluxo offline, a primeira execução é recusada e a etapa falha sem disparar o resto. Com ela ligada, a execução da vez espera o runtime voltar e a lista fica parada nesse ponto. Se o runtime não voltar em 30 minutos, a plataforma cancela essa execução, devolve a falha ao agente principal, e a lista segue para a próxima, que espera do mesmo jeito. Para não deixar a lista se arrastar assim, pare o agente principal. |
| O runtime do agente chamado cai no meio de uma execução | A plataforma percebe e devolve a falha daquela execução ao agente principal: em 5 minutos com o runtime desligado, em 30 com ele ligado (detalhes: Quando o runtime do agente chamado sai do ar). Ela entra no registro com status CRASHED e a lista segue para a próxima. |
| Os créditos acabam no meio da lista | As execuções seguintes são recusadas e a etapa falha dizendo em qual item parou. As que já rodaram ficam como estão. |
| A lista está vazia, ou a variável dela não existe na execução | Nenhuma execução é disparada e a etapa falha dizendo que a lista está vazia, ou que a variável não existe nesta execução, do mesmo jeito que na lista disparada de uma vez. |