Subprocesso de Agentes

A etapa Chamar Agente: um agente dispara outro agente publicado como subprocesso, passa parâmetros, espera o retorno e recebe de volta variáveis, status e erro.

Em resumo

• Chamar Agente dispara um agente publicado, com os parâmetros que você escolher, como um subprocesso: ele roda inteiro, do começo ao fim, com log e créditos próprios.
• O agente chamado roda sempre a versão publicada, no ambiente dele, como uma execução normal: aparece no Control Room, tem log, consome 1 crédito por execução.
• O centro do mecanismo é o Comportamento a cada disparo, escolhido a cada chamada: ficar até o agente terminar, ficar até um prazo, seguir assim que ele responder pelo Webhook Response, ou disparar e seguir. Sem esperar, o retorno chega em segundo plano: status, erro, etapa em que falhou e os dados que você pedir, para uma decisão mais à frente. A etapa Aguardar Agentes, opcional, espera essas execuções terminarem e funciona com uma chamada só. Detalhes: Aguardar Agentes com uma chamada só.
• De volta ao pai chegam só as variáveis que você pediu, mais o status da execução. Falha no agente chamado vira erro na etapa do pai, tratado pela Gestão de Erros.
• Para disparar vários agentes de uma vez, ou várias execuções do mesmo agente a partir de uma lista, veja Paralelizar Agentes. Para espalhar essas execuções entre runtimes, veja Balancear Carga dos Agentes. Paralelizar Agentes e a distribuição entre runtimes existem a partir do plano Professional; Chamar Agente, com ou sem lista, e Aguardar Agentes existem em todos os planos.

As etapas de agentes

No + do fluxo, o grupo Orquestração de Agentes tem quatro etapas. Parâmetros de entrada, comportamento a cada disparo, retorno, créditos e dado sensível são comuns a Chamar Agente, Paralelizar Agentes e Aguardar Agentes e estão documentados nesta página. A página de Paralelizar Agentes descreve só o que é específico das outras duas.

A seção Distribuição do processamento aparece no painel quando uma etapa dispara mais de uma execução ao mesmo tempo. Detalhes: Balancear Carga dos Agentes.

Para que serve

Um agente que consulta um CNPJ, outro que emite uma nota, outro que avisa o cliente. Cada um resolve uma coisa e pode ser testado, versionado e compartilhado por conta própria. Chamar Agente é o que deixa um fluxo maior usar esses agentes como peças, sem copiar as etapas deles para dentro: o pai passa o que o filho precisa e escolhe como esperar por ele. Fica até ele terminar, fica até um prazo, segue assim que ele responder, ou dispara e segue, lendo o desfecho mais à frente.

Três situações em que isso é a forma certa de montar:

• Reaproveitar. O mesmo agente de consulta serve a dez fluxos diferentes. Uma correção nele vale para todos na próxima publicação.
• Dividir responsabilidade. O agente de emissão é de outro time. Ele compartilha o agente com permissão de executar, e o seu fluxo o chama sem enxergar como ele foi feito.
• Isolar o que é frágil. O portal que cai toda semana fica num agente pequeno, com a sua própria Gestão de Erros e as suas tentativas. O fluxo principal só recebe o resultado ou o erro, e decide.

Como se cria

1. Publique o agente que será chamado. Só a versão publicada pode ser chamada. Um agente que ainda está em desenvolvimento aparece na lista, mas desabilitado, com o motivo.
2. No fluxo do pai, clique no + (no fim do fluxo, ou no + de uma seta para inserir no meio) e, no grupo Orquestração de Agentes, escolha Chamar Agente.
3. Abra a etapa e escolha o agente. A lista traz os agentes do dono deste processo e os que foram compartilhados com ele com permissão de executar (é o dono que o sistema confere ao disparar, mesmo quando outra pessoa edita o fluxo). Um agente não pode chamar a si mesmo.

Outro jeito de criar: arrastar o agente do painel Agentes para o Processo, e a etapa já nasce chamando ele. Detalhes: O painel Agentes.

A etapa nasce como etapa de Execução com a ação já definida: ela não troca de tipo depois. O que se configura é a chamada em si. A opção Clonar do mesmo menu não lista as etapas de agentes: uma chamada se cria de novo, escolhendo o agente, e não por cópia.

Ela não tem nome próprio. No fluxo, no log e nos seletores de variáveis, a etapa Chamar Agente aparece com o nome do agente chamado.

O painel Agentes

O ícone Agentes, na segunda fileira do cabeçalho do Agent Builder, ao lado do Conectores, abre um painel lateral com os agentes que o processo pode chamar. É a mesma lista do botão Escolher agente: os agentes do dono do processo e os compartilhados com ele com permissão de executar. O campo Buscar agente filtra pelo nick, pelo nome do processo e pela descrição.

• Cada card mostra o avatar, o nick do agente em destaque e, embaixo, o nome do processo. O agente de outra pessoa traz a marca COMPARTILHADO.
• O agente que está aberto no editor e o agente sem versão publicada aparecem bloqueados, com o motivo no lugar do nome do processo. Não podem ser arrastados, e clicar neles mostra o motivo.
• Sem nenhum agente disponível, o painel mostra Nenhum agente para chamar ainda: publique um agente, ou peça que compartilhem um com você.

Arrastar um agente para o fluxo

Arraste o card do agente para o canvas. O que acontece depende de onde ele é solto:

O soltar só vale com uma versão de desenvolvimento aberta. O agente precisa ser um que o dono do processo também alcança, porque a execução roda com o acesso dele; fora disso o soltar é recusado com o motivo. Enquanto o card é arrastado sobre uma etapa de agente, uma pílula acima dele diz a ação. Detalhes do arrastar e soltar de agentes e conectores: Agent Builder → Criar ou configurar uma etapa arrastando do painel.

No fluxo visual

• O card de Chamar Agente é maior que os outros e não tem nome próprio: mostra o avatar e o nick do agente chamado e, embaixo, menor, o nome do processo dele, lidos do cadastro. Agente sem nick aparece pelo nome do processo, com o propósito embaixo. No canto, o chip diz como o pai espera: ampulheta com "aguarda o fim", relógio com "aguarda até N s", raio com "antecipada" e avião de papel com "dispara e segue". O ícone de repetição aparece quando a etapa dispara por item de uma lista.
• Passar o mouse no avatar abre o resumo: o nick do agente no título e, abaixo, o processo, a descrição, o que ele recebe, o que devolve e como o pai espera.
• O card só tem o botão Configurar: não existem Objetos nem Mapeamentos nessa etapa. O que entra, o que volta e o que se espera se configura no painel.
• Um agente arrastado do painel Agentes para o card define ou troca o agente chamado, e um conector solto no card é recusado. Detalhes: Arrastar um agente para o fluxo.
• Etapa incompleta (sem agente escolhido, retorno sem variável, agente que sumiu ou ainda não publicado, disparo em lotes com Não esperar sem um Aguardar Agentes mais à frente que o aguarde) entra na lista de pendências e impede a publicação, como um script com erro.

A espera: o mecanismo central

Chamar um agente não é "chamar e ficar parado até ele terminar". O que dá forma à chamada é o Comportamento a cada disparo: a cada chamada, o pai escolhe se fica, por quanto tempo fica, se segue assim que o agente responder, ou se dispara e segue sem esperar, lendo o desfecho mais à frente. É essa escolha que faz o mesmo recurso servir para uma consulta rápida no meio do fluxo, para um trabalho longo que roda enquanto o pai faz outra coisa, e para um aviso que ninguém precisa esperar. O chip no canto do card, no fluxo, diz o modo escolhido.

O prazo é sempre da etapa do pai, não do agente chamado nem do Webhook Response dele: é quanto o pai aceita esperar. Cada chamada pode esperar um tempo diferente do mesmo agente.

Qual modo usar

Como se configura

Tudo fica no painel da etapa, na seção Agente chamado. O botão Escolher agente abre a lista dos agentes que o dono do processo pode chamar (os dele e os compartilhados com permissão de executar), e o agente escolhido aparece no alto, com o avatar, o nick do agente em destaque e, embaixo, o nome do processo dele. Trocar agente abre a mesma lista de novo. O agente em edição e os que ainda não foram publicados aparecem na lista, mas bloqueados, com o motivo. Arrastar um agente do painel Agentes para o card da etapa também o escolhe. Detalhes: Arrastar um agente para o fluxo.

Parâmetros de entrada do agente chamado

Aparecem os parâmetros que o agente chamado recebe (a Matrix dele), pelo nome que o dono deu. Cada linha lê no sentido do fluxo: à esquerda o valor no pai (um texto, uma variável {variavel}, ou os dois misturados), à direita o parâmetro no agente que o recebe. O que ficar em branco chega vazio.

O agente chamado lê cada valor pelo tipo do parâmetro dele: uma Moeda aceita tanto a Moeda do pai quanto um texto raspado como R$ 1.234,90, e um Verdadeiro/Falso aceita sim. Detalhes: Como o tipo é aplicado.

Um parâmetro do tipo Secreto aparece marcado. O valor que você mandar para ele é tratado como sensível na execução do agente chamado, do mesmo jeito que se tivesse vindo por API.

Comportamento a cada disparo

Os quatro modos, o prazo e o guia de qual usar estão na seção A espera: o mecanismo central, acima. A escolha é por chamada: a mesma etapa pode trocar de modo a qualquer momento, e o chip no card do fluxo acompanha.

Retorno do agente chamado

Cada linha diz o que pegar do agente chamado e em qual variável do pai guardar, também no sentido do fluxo: na primeira fileira, o que sai do agente; na segunda, a variável do pai que recebe, com a marca de sensível ao lado:

• Variável do agente: uma variável criada no fluxo do agente chamado (por uma etapa dele, um conector, um script) ou um parâmetro dele, que aparece como matrix.nome_do_parametro. Digite só o nome: a tela o mostra como variável, entre chaves. A lista das variáveis dele aparece para escolher: é a lista da versão publicada do agente, refeita a cada publicação. É o valor que a variável tem quando o agente termina. Se ela é uma lista no agente chamado, a variável do pai que a recebe também é lista, com a marca de lista nos seletores. Se ela é dado sensível no agente chamado, aparece com a marca SENSÍVEL, a linha já fica marcada como Sensível e a tela diz se o dono a liberou para quem chama; sem a liberação, ela não volta (Detalhes: Dado sensível entre agentes).
• Corpo do Webhook Response: o corpo inteiro que o agente chamado respondeu, ou um campo dele. Informe o caminho no JSON, como dados.protocolo, ou cole um exemplo da resposta e clique no campo. Só existe quando o agente chamado tem uma etapa Webhook Response.
• Status da execução: FINALIZED, ERROR, STOPPED e os demais status que o Webhook Response já usa.
• Mensagem de erro: vazia quando não houve erro.
• Etapa em que falhou: o nome da etapa do agente chamado em que a execução parou; vazia quando terminou bem. É o "em qual parte quebrou".

A variável do pai se digita do mesmo jeito, só o nome. Sem nenhuma linha de retorno, nada é gravado no pai: o status só decide se a etapa falha. As variáveis criadas aqui aparecem nos seletores das etapas seguintes, como as de qualquer outra etapa.

Disparar por cada item de uma lista e Distribuição do processamento

O painel tem ainda a seção que liga Disparar por cada item de uma lista: em vez de uma execução, a etapa dispara uma por item de uma lista (uma variável do tipo Lista, uma variável gravada por script ou os itens digitados), todas ao mesmo tempo, e o retorno passa a ser uma lista de registros. Uma execução que falha não interrompe as outras: a lista roda até o fim, e cada registro diz como o seu item terminou. 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. Detalhes: Paralelizar Agentes → O segundo nível: Disparar por cada item de uma lista. Com ela ligada aparecem também as seções Modo de enfileiramento do disparo e Distribuição do processamento. Detalhes: Balancear Carga dos Agentes.

Onde se altera depois

Sempre no painel da etapa do pai. O nick, o nome do processo, o avatar e a descrição que o card mostra vêm do cadastro do agente chamado: renomear o agente lá muda o card aqui na próxima abertura do fluxo. Os parâmetros também: se o dono do agente criar um parâmetro novo, ele aparece nos Parâmetros de entrada da sua etapa na próxima vez que você a abrir.

O que volta ao pai

Só o que você pediu na seção Retorno do agente chamado, mais o status. Nunca voltam variáveis do sistema, arquivos e imagens (o conteúdo de um download, uma evidência), nem valores do Cofre. Uma variável que passa do tamanho permitido também fica de fora. O que ficou retido é dito no log do pai, com o motivo, para não parecer que a variável nunca existiu.

A variável do pai que recebe cada retorno tem o nome que você escolher, menos o de uma variável de sistema: a tela recusa esse nome ao salvar a etapa.

O caminho do retorno depende de onde os dois rodam. No mesmo runtime, ele passa direto na memória: nada é gravado. Em runtimes diferentes, ele viaja cifrado com uma chave que existe só na memória do runtime do pai, e é apagado assim que é lido. Se o runtime do pai reiniciar no meio, a chave some com ele e o retorno é descartado: a etapa falha, sem expor nada.

Disparar e seguir, consultando depois

Em Não esperar, a etapa do pai termina na hora, mas o retorno que você pedir continua valendo: quando o agente chamado terminar, o status, a mensagem de erro, a etapa em que falhou e as variáveis pedidas são gravados no pai em segundo plano, sem segurar nenhuma etapa. No disparo, a variável do status recebe RUNNING; as demais só existem quando o retorno chega.

É assim que se deixa um agente trabalhando de verdade em paralelo com o fluxo: dispare no começo, faça o resto e, mais à frente, leia as variáveis. Uma Decisão de Rota sobre {crm_status} separa o que terminou bem (FINALIZED), o que falhou (ERROR e os demais status) e o que ainda roda (RUNNING); terminou bem, use {crm_protocolo}; falhou, {crm_erro} e {crm_etapa} dizem o quê e onde. As variáveis mudam por evento, no momento em que o retorno chega, não por uma etapa do pai.

Nada obriga o pai a esperar depois: o retorno chega sozinho. Para garantir, num ponto do fluxo, que a execução terminou, ou conferir como terminou, use a etapa opcional Aguardar Agentes. Detalhes: Aguardar Agentes com uma chamada só.

Dois limites a conhecer: o pai que termina antes do agente chamado não recebe mais nada (o retorno que chegar depois é descartado, com aviso no log do runtime); e uma nova tentativa da etapa, pela Gestão de Erros, dispara o agente de novo.

Aguardar Agentes com uma chamada só

O Aguardar Agentes espera as execuções disparadas em Não esperar antes dele no fluxo, venham de um Chamar Agente ou de um Paralelizar Agentes. Uma etapa Chamar Agente sozinha, em Não esperar, já pode ser aguardada: não é preciso um Paralelizar Agentes.

1. Deixe a chamada em Não esperar e, no Retorno do agente chamado, peça ao menos o status da execução e a mensagem de erro. Sem retorno pedido, o Aguardar sabe que a execução terminou, mas não como.
2. Crie o Aguardar Agentes no ponto do fluxo em que a execução precisa ter terminado, pelo +, grupo Orquestração de Agentes. Ele só enxerga o que foi disparado antes dele.
3. Em "O que aguardar", escolha Todos os agentes disparados sem esperar antes desta etapa ou Só estes agentes, marcando a chamada. Cada chamada aparece com o nome do agente chamado e a variável onde o desfecho dela fica.
4. Preencha o campo Prefixo Identificador desta Etapa. Ele identifica a etapa nas variáveis que ela grava: {agentWaiter.<prefixo>.status} (FINALIZED, ERROR ou TIMEOUT), .total, .failed, .pending e as demais.

• Com Disparar por cada item de uma lista, cada execução da lista conta como um aguardado.
• Se nenhum disparo aconteceu antes do Aguardar (um caminho do fluxo que contorna a chamada, por exemplo), ele avisa no log, grava total zero e o fluxo segue.

Detalhes do Aguardar Agentes (teto de espera, o que fazer quando ele estoura ou quando um aguardado falha, e todas as variáveis da espera): Paralelizar Agentes → Aguardar Agentes.

Dado sensível entre agentes

Uma variável marcada como dado sensível no agente chamado não é devolvida ao pai por padrão, mesmo que o pai a peça: o log do pai diz que ela foi retida por isso. Quem decide liberar é o dono do agente chamado, nas Configurações do Agente dele, no campo de variáveis sensíveis liberadas para quem o chama.

Uma variável liberada chega ao pai com a marca: ela continua sensível na execução do pai, não aparece no log dele nem nas exportações, e o pai não a desmarca. O mesmo vale para o corpo do Webhook Response quando ele carrega um valor sensível: o dono libera o corpo por inteiro, e tudo o que o pai tirar dele nasce marcado.

No sentido contrário, do pai para o agente chamado, um valor sensível só entra num parâmetro do tipo Secreto. Se a entrada leva dado sensível a um parâmetro comum, nada é disparado e a etapa falha dizendo isso.

Ciclo de vida, créditos e limites

• Créditos. Cada execução do agente chamado consome 1 crédito da empresa, além do crédito do pai. Antes de disparar, o sistema confere o saldo para todas as execuções da etapa: se ele não cobrir, nenhuma é disparada e a etapa falha dizendo quantos créditos faltam.
• Parar e pausar. Parar o pai enquanto ele espera para também o que ele está esperando. Pausar pausa, retomar retoma. Uma execução disparada em Não esperar não é alcançada por nada disso.
• Debug. No ▶ do pai a chamada é real: o agente chamado roda em produção, cobrado. Para não chamar de verdade durante um teste, fixe a saída da etapa (📌) com valores de exemplo, ou ignore a etapa (🚫). Enquanto a etapa espera, o card mostra quantas execuções já voltaram (por exemplo 2/3).
• Abrir o agente chamado. Clicar no avatar dele, no card, leva ao editor daquele agente, na mesma janela. Na faixa de contexto do alto da tela aparece o nome do agente que fez a chamada: clique nele para voltar ao fluxo de onde você veio. Numa cadeia de chamadas, a volta percorre a cadeia inteira, um agente por vez.
• Fila do runtime. A execução do agente chamado entra na fila e no teto do runtime dele como qualquer outra, com duas regras próprias: passa na frente das execuções de sempre que esperavam, e o pai, enquanto espera por ela, solta a vaga dele e a pede de volta quando o retorno chega. Por isso funciona mesmo com teto 1. Detalhes: Paralelizar Agentes → Runtime em modo fila. Soltar uma lista de itens aos poucos: Enfileirar Agentes. Teto do próprio agente chamado: Configurações de Execução.
• Profundidade. Um agente chamado pode chamar outro, até cinco níveis. Um agente que, pela cadeia, chegaria a chamar a si mesmo é recusado antes de disparar.
• Compartilhamento. Chamar um agente de outra pessoa exige que ele tenha sido compartilhado com você com permissão de executar, e que o plano da empresa dona ainda comporte compartilhamento. Se o compartilhamento for retirado, a chamada passa a ser recusada. Receber um agente que chama outros não dá acesso aos agentes chamados: executar funciona, porque a chamada é feita com o acesso do dono do agente que chama; abrir um agente chamado pelo card exige que ele também tenha sido compartilhado com você, e sem isso o card avisa. Detalhes: Compartilhamento.
• Sandbox. Um agente com essas etapas não roda na Sandbox: o teste é no seu Ambiente Runtime, como acontece com conectores e cofre.
• Ambientes Runtime desatualizados. Um runtime antigo não sabe chamar agentes. A execução do pai é recusada antes de começar, com a mensagem de que o runtime precisa ser atualizado. O agente chamado também precisa de um runtime atualizado: um runtime antigo o rodaria como uma execução comum e nunca devolveria o retorno, então o disparo é recusado na hora, dizendo qual ambiente atualizar. Na distribuição entre runtimes, um runtime desatualizado fica de fora e os outros recebem o lote. A conferência vale para o runtime ligado: um runtime desligado com Manter fluxo offline não pode ser julgado (ao se desligar ele deixa de declarar o que sabe fazer), então a execução espera na fila dele.
• Exportar e importar. A etapa guarda a referência ao agente chamado. Ao exportar, os agentes chamados vão junto no mesmo arquivo; ao importar em outra conta, eles são criados e religados à etapa.

Limites e tetos

Quando algo dá errado

Quando o runtime do agente chamado sai do ar

Quem avisa que uma execução terminou é o runtime que a executou. Se ele sai do ar no meio, esse aviso não chega, e o agente que espera ficaria parado: com Esperar finalizar não há prazo escolhido, e o Aguardar Agentes pode ser configurado sem teto. A plataforma cobre isso sozinha, porque ela enxerga os dois runtimes, o de quem chama e o de quem é chamado.

De tempos em tempos, cada chamada em aberto é conferida. O desfecho depende do que se encontra:

A falha chega ao pai como qualquer outro retorno, cifrada em trânsito, e vale como resposta do agente chamado: o status fica CRASHED, a mensagem explica o que houve, e a etapa entra na Gestão de Erros com nova tentativa, contorno ou parada, como você configurou. Num disparo Não esperar que tem retorno mapeado, ou que é aguardado mais à frente, a mesma falha aparece nas variáveis daquele disparo e no Aguardar Agentes.

Nada disso muda a promessa do modo fila: uma execução que ninguém espera continua guardada até o runtime voltar. A intervenção existe só onde há alguém parado esperando, e é por isso que ela nunca alcança um disparo do tipo dispara e segue sem retorno.

Tudo isso fica no log do pai, na linguagem de sempre: "Chamando agente X", "Aguardando o retorno de X", "Agente X terminou", com o que foi recebido e o que foi retido. Os valores em si não aparecem no log.