Etapa Agêntica

Etapa em que um modelo de IA de chat decide, a cada volta, quais ferramentas chamar entre as autorizadas (agentes da plataforma e conectores configurados), até entregar um resultado na forma declarada na Saída.

Para que serve

A Etapa Agêntica é um ponto do fluxo em que um modelo de IA decide, de forma dinâmica e probabilística, quais ações executar para atingir determinado objetivo do processo.

Para isso, o modelo utiliza como ferramentas os próprios Agentes de Processo da plataforma e todos os conectores disponíveis, podendo escolher, combinar e executar diferentes recursos conforme a necessidade de cada situação.

Estrutura Básica:

• Modelo: um conector de IA de chat já configurado (Claude, OpenAI, Mistral, Grok ou Groq). Credencial, modelo, Max Tokens e System Prompt são os do conector.
• Ferramentas: agentes publicados da plataforma e conectores configurados, autorizados um a um na etapa. O modelo chama só o que está na lista.
• Saída: os campos que o modelo entrega ao terminar. Cada um vira uma variável do fluxo, no tipo declarado. Objeto e Lista têm forma declarada (atributos do Objeto, tipo dos itens), e o que o modelo entrega é validado até o fundo.
• Custo: a etapa cobra o crédito da execução em que está e cada agente chamado como ferramenta cobra o dele. Os tokens do modelo são cobrados na conta do provedor, configurada no conector. Vale em todos os planos.
• Onde executa: no Ambiente Runtime. A Sandbox não executa a Etapa Agêntica.

O card no fluxo

No núcleo fica o modelo, com o ícone do conector e o rótulo. Na órbita ficam as ferramentas: agente com o avatar, conector com o ícone do catálogo. Um raio no canto marca a ferramenta que tem efeito. Acima de sete ferramentas, a última vaga vira um contador (+N). No topo, o título e a marca da etapa; no rodapé, o prefixo das variáveis (agentic.<prefixo>) e o teto de voltas.

• Balão: ao passar o mouse sobre o card, mostra o modelo, cada ferramenta (com o modo de espera e a marca de efeito), a Saída com a forma de cada Objeto e Lista (cliente (Objeto: nome, cnpj), itens (Lista de Objeto)), as variáveis e os limites. Sobre o núcleo ou sobre uma ferramenta da órbita, o balão se fecha e aparece só o nome daquele item; ao voltar para o card, o balão reabre.
• Barra do card: ao passar o mouse, aparecem Configurar, Excluir e Grupo de etapas.
• Anel vermelho: a etapa tem pendência (seção Pendências e Salvar) e publicar fica bloqueado.

Clicar no modelo e nas ferramentas

O núcleo e cada item da órbita respondem ao clique. O cursor indica o que abre e o que não abre.

Como uma execução acontece

1. A etapa resolve as {variáveis} das Instruções, da Tarefa e da Conversa anterior com os valores do fluxo naquele momento.
2. Envia ao modelo: o System Prompt do conector, as Instruções, as regras fixas da plataforma, a conversa anterior (quando há) e a Tarefa. Junto vão a lista das ferramentas (nome, Quando usar e os campos que a IA preenche) e a ferramenta de entrega.
3. O modelo responde com texto, pede uma ou mais ferramentas, ou chama a entrega. Cada resposta é uma volta.
4. Para cada pedido de ferramenta, a etapa executa e devolve o retorno ao modelo, que abre a volta seguinte. Conectores pedidos na mesma volta rodam juntos; agentes rodam um de cada vez. Um agente em Não esperar só é disparado e a volta segue.
5. Quando o modelo chama a entrega, a etapa valida cada campo e converte pelo tipo declarado. Um resultado que não cabe na Saída volta ao modelo uma vez para correção.
6. A etapa grava as variáveis agentic.<prefixo>.* e o fluxo segue.

As regras fixas da plataforma são: usar só as ferramentas oferecidas e só quando a Tarefa pedir, terminar chamando a entrega, não inventar o que uma ferramenta poderia buscar e responder em português.

Campos do painel da etapa

O painel abre pelo botão Configurar do card. As seções, na ordem: Prefixo Identificador desta Etapa, Modelo, Instruções, Tarefa, Ferramentas, Conversa anterior, Saída, Dado sensível e Limites. Depois delas, o painel traz as seções comuns a todas as etapas (Descrição da etapa, Gestão de Erros e Exceções, Condições de rotas e execuções e Mensageria). A etapa é numerada pela ordem no fluxo: Etapa Agêntica 1, 2 e assim por diante.

Prefixo Identificador desta Etapa

Modelo

Da conta do conector a etapa lê a credencial (chave e, na OpenAI, a organização), a versão do modelo, o Max Tokens, o System Prompt e a URL base. Os campos da ação do conector (prompt, estrutura de saída, classes, temperatura e afins) não são lidos: a Tarefa, as Instruções e a Saída da etapa é que definem o pedido e o formato do resultado. Detalhes do que vale entre conector e etapa: O que vem do conector e o que vem da etapa.

Instruções e Tarefa

As {variáveis} dos dois campos são resolvidas antes da primeira consulta; uma variável do tipo Lista ou Objeto entra como JSON. O System Prompt do conector é sempre texto fixo. A regra de dado sensível vale para os dois campos (seção Dado sensível).

Ferramentas

Cada ferramenta autorizada é um bloco na seção. Até 20 por etapa.

Conversa anterior

Saída

Um bloco por campo que o modelo deve entregar. Até 30 campos na Saída e 150 no total, contando os atributos dos objetos. Ao menos um é obrigatório para a etapa ficar completa.

Dado sensível

Limites

Os limites acompanham as ferramentas. Ao autorizar uma ferramenta, no painel ou soltando no card, Voltas (máx.) sobe para 2 se estava em 1, e Chamadas de agente sobe até o número de agentes autorizados. Valor acima do mínimo fica como está, e 0 em Chamadas de agente também.

Ao sair de um limite, o campo em branco volta ao padrão (acompanhando as ferramentas), o número com decimal vira inteiro e o fora da faixa vai ao mínimo ou ao máximo dela. É esse valor que o Salvar grava.

Limite que contradiz as ferramentas aparece com um aviso em destaque embaixo do campo, e o Salvar continua liberado:

Quantas voltas reservar para as ferramentas da etapa: seção Voltas e ferramentas.

Ações

Controles que decidem a execução

Os controles abaixo mudam o que o modelo pode fazer, o que chega a ele ou se a etapa roda. Cada linha diz o que o controle faz, por que existe e o que acontece em cada estado.

As ferramentas

Em + Adicionar agente, o catálogo lista os agentes da sua conta e os compartilhados com você com permissão de executar. Quando o agente aberto é compartilhado, a lista traz só os que também são alcançados pelo dono dele, porque a execução roda com o acesso do dono. Em + Adicionar conector, a lista traz os conectores configurados na sua conta e os publicados para a empresa. Num agente compartilhado com você, os conectores que o dono dele não alcança (nem dele, nem publicados para a empresa) aparecem bloqueados, com o motivo, tanto para o modelo quanto para as ferramentas: a execução roda com os conectores do dono, e um conector seu que ele não alcança não seria encontrado. Soltar um desses no card é recusado com o mesmo aviso. Para usá-lo, configure-o na conta do dono ou publique-o para a empresa.

Agente como ferramenta

• O agente chamado roda sempre a versão publicada, no ambiente dele, como uma execução normal: aparece no Control Room, tem log e cobra 1 crédito.
• Nos modos que esperam, o modelo recebe o status e as variáveis que o agente publica, no fim da execução (as mesmas que a etapa Chamar Agente oferece).
• Não esperar: o agente roda em segundo plano como uma execução normal (Control Room, log, 1 crédito) e a etapa segue sem esperar. O modelo recebe só a confirmação do disparo ({"status":"DISPARADO"}) ou, se o disparo for recusado (agente sem versão publicada, sem crédito, ambiente indisponível), o erro. Não há variáveis de retorno, e nenhum Aguardar Agentes do fluxo espera essa execução. A descrição da ferramenta e as regras do pedido dizem ao modelo que ela só dispara, que não se espera resultado dela e que não se chama de novo para conferir.
• Agentes são chamados um de cada vez, e cada chamada conta em Chamadas de agente. Prazo estourado volta ao modelo como erro e a execução do agente segue.
• A Etapa Agêntica conta na profundidade de agentes chamando agentes (até 5 níveis) e no bloqueio de ciclo. Detalhes de Chamar Agente: Chamar Agente.

Conector como ferramenta

• A ação é a gravada no conector. O modelo não escolhe a ação, só os campos marcados como a IA preenche. O valor de cada campo na chamada: O que vem do conector e o que vem da etapa.
• O retorno vai ao modelo pelo mapeamento de saída do conector. Sem mapeamento, vai a resposta como veio.
• Conectores pedidos na mesma volta rodam juntos. Conector não cobra crédito. Detalhes de conectores: Conectores.

Retorno ao modelo

O retorno de qualquer ferramenta é cortado em 32 KB antes de ir ao modelo. Ferramenta que falha (conector fora do ar, agente com erro, prazo estourado, disparo recusado) devolve o erro ao modelo, que decide se tenta de outro jeito ou entrega.

O que vem do conector e o que vem da etapa

O conector é lido a cada execução: o que muda nele vale na execução seguinte, sem abrir a etapa. O que a etapa define (Instruções, Tarefa, Saída e os campos de cada ferramenta) fica gravado na própria etapa.

No modelo

Num conector como ferramenta

A ação e a credencial são as gravadas no conector, lidas a cada chamada. Os campos da ação entram na ferramenta quando ela é adicionada (pelo painel ou soltando o conector no card): campo com valor no conector entra em Valor fixo do fluxo, com uma cópia desse valor; campo em branco entra em A IA preenche. Na chamada, cada campo vai assim:

A cópia do valor fixo não acompanha o conector. Depois de um valor alterado no conector, o campo fixo da ferramenta fica diferente dele, e na chamada vai o valor da etapa. Para a ferramenta usar o valor novo, atualize o campo no bloco da ferramenta ou deixe-o em branco.

Num agente como ferramenta

O agente chamado roda a versão publicada no momento da chamada. A lista de parâmetros, as variáveis que voltam ao modelo (a linha Devolve ao modelo) e o texto inicial de Quando usar (a Descrição do Agente) são copiados do agente quando a ferramenta é adicionada.

Parâmetro ou variável de retorno criados no agente depois de a ferramenta ser adicionada não entram nela. Para trazê-los, remova a ferramenta e adicione o agente de novo.

Ferramenta com efeito

Ferramenta que envia, grava ou paga é marcada como Tem efeito. A marca aparece como um raio no card e como uma indicação na descrição que o modelo lê.

A marca pode ser trocada no bloco da ferramenta. O que ela faz:

A conferência é a confirmação, por quem desenha a etapa, de que revisou o que fica fixo e o que o modelo preenche naquela ferramenta. Ela vale para a configuração revisada: mudar um campo da ferramenta (quem preenche, valor fixo, descrição para a IA) ou desligar Tem efeito desmarca a conferência, e a etapa volta a ficar pendente até conferir de novo. Mudar o Quando usar ou o modo de espera do agente não desmarca. Destinatário, valor e conta costumam ficar fixos; aí o modelo decide só se e quando chamar, e o que vai nos demais campos.

O que o modelo lê nas ferramentas (um e-mail, uma página) pode conter texto que tenta levá-lo a agir. O que limita o que ele consegue fazer são as ferramentas autorizadas, os campos fixos e a marca de efeito.

A Saída e as variáveis

A Saída define a forma do resultado: o modelo termina chamando a ferramenta de entrega, cujos campos são os da Saída. Texto solto não encerra a etapa. Cada campo é validado e convertido pelo tipo; um resultado que não cabe volta ao modelo uma vez para correção, e na segunda a etapa falha.

A etapa grava, com o prefixo agentic.<prefixo>:

Os nomes aparecem nos seletores de variáveis das demais etapas (Decisão de Rota, Regra Customizada, Conector) assim que você sai do campo Prefixo Identificador desta Etapa, com o tipo de cada um. Detalhes de Decisão de Rota: Decisão de Rota.

A descrição de um campo da Saída

Quem preenche a Saída é o modelo, e a Descrição para a IA é a instrução de como preencher. O modelo termina chamando a ferramenta de entrega, e o esquema dessa ferramenta traz, para cada campo e cada atributo, o nome, o tipo, se é obrigatório e a descrição. O nome sozinho costuma ser ambíguo; a descrição diz o significado, os valores aceitos e a regra de escolha.

A descrição orienta; quem garante o formato é o tipo, que a etapa confere ao receber a entrega. Um campo cujo nome já diz tudo (cnpj, email) dispensa a descrição.

A forma de um Objeto e de uma Lista

O modelo lê a forma declarada como esquema da ferramenta de entrega, e a etapa confere o resultado campo a campo, até o fundo. Um Objeto sem atributos e uma Lista sem tipo dos itens deixam a etapa pendente: sem a forma, o resultado teria uma estrutura diferente a cada execução.

Exemplo: a Saída cliente (Objeto com nome, cnpj e endereco, um Objeto com cidade e cep opcional) e a Saída itens (Lista de Objeto com sku e preco, este em Moeda).

{
  "cliente": {
    "nome": "Ana Souza",
    "cnpj": "12.345.678/0001-90",
    "endereco": { "cidade": "São Paulo" }
  },
  "itens": [
    { "sku": "A1", "preco": "1.234,50" },
    { "sku": "B2", "preco": 10 }
  ]
}

Variáveis gravadas (prefixo triagem): agentic.triagem.cliente (o objeto), agentic.triagem.cliente.nome, agentic.triagem.cliente.cnpj, agentic.triagem.cliente.endereco, agentic.triagem.cliente.endereco.cidade, agentic.triagem.cliente.endereco.cep (vazio, porque é opcional e não veio) e agentic.triagem.itens, com o valor [{"sku": "A1", "preco": 1234.5}, {"sku": "B2", "preco": 10}]. Uma Decisão de Rota logo depois escolhe agentic.triagem.cliente.cnpj no seletor, sem abrir o objeto.

A conferência do resultado segue estas regras:

Limites da forma: 3 níveis de Objeto dentro de Objeto (a Saída pedido é o nível 1, a lista itens dentro dela o 2 e o imposto de cada item o 3), 30 atributos por objeto e 150 no total, somando campos e atributos. Uma Lista de Texto, Número, Moeda ou Verdadeiro/Falso pode estar em qualquer nível.

Montar a partir de um exemplo em JSON

Em uma Saída do tipo Objeto ou Lista, Montar a partir de um exemplo em JSON abre um campo para colar um exemplo do que o modelo deve entregar. O JSON é conferido enquanto se escreve (também no editor em tela cheia, ⤢), e Montar os atributos troca a forma atual pela do exemplo. Cancelar fecha o campo do exemplo sem alterar nada. Um Objeto aceita um JSON entre chaves; uma Lista, um JSON entre colchetes.

• Sai obrigatório o atributo que vem preenchido em todos os itens do exemplo. O atributo que falta, vem null ou vem em branco em algum item sai opcional, e o tipo vem dos itens em que ele está preenchido (sem nenhum preenchido, Texto).
• Nomes de atributo só têm letras, números e _: acento e traço da chave são trocados (data-nasc vira data_nasc), e uma chave que começa por número ganha um _ na frente.
• A Descrição para a IA sai vazia em todos os atributos: escreva onde o nome não bastar.
• O exemplo é recusado, com o motivo, quando não é JSON, quando é do tipo errado (lista no Objeto, objeto na Lista), quando não traz atributos, quando o mesmo atributo tem tipos diferentes no exemplo (número em um item e texto em outro), quando há uma lista dentro de uma lista, um objeto vazio ou um item vazio numa lista de objetos, quando passa de 3 níveis de objeto dentro de objeto, de 30 atributos em um objeto ou de 150 no total, e quando duas chaves viram o mesmo nome.

Exemplo colado em uma Saída do tipo Lista:

[
  { "sku": "A1", "qtd": 2, "preco": 10.5 },
  { "sku": "B2", "qtd": 1 }
]

Resultado: a Lista passa a ter itens do tipo Objeto com os atributos sku (Texto, obrigatório), qtd (Número, obrigatório) e preco (Número, opcional, porque falta no segundo item).

Conversa anterior

Cada execução começa sem histórico. Para continuar uma conversa, guarde agentic.<prefixo>.messages onde quiser (planilha, banco, Redis, por um conector) e, na execução seguinte, traga a variável em Conversa anterior. A etapa envia essas mensagens antes da Tarefa e grava a conversa atualizada em .messages. Só as falas de usuário e de assistente entram. Se as mensagens trazem dado sensível, vale a regra da seção Dado sensível.

Dado sensível

Dado marcado como sensível e segredo do Cofre não vão ao provedor do modelo, salvo liberação. Onde cada um pode passar:

• A marca vem da origem: a saída marcada no conector, a variável marcada no agente ou no fluxo. A liberação só decide se o modelo pode receber; ela não cria nem tira a marca.
• As duas liberações são independentes: a da etapa não abre a das ferramentas, e a das ferramentas não abre a da etapa.
• Com dado sensível enviado ao modelo por liberação, todas as variáveis que a etapa grava saem marcadas como sensíveis, inclusive os atributos de um Objeto, e o log da execução registra a linha dado sensível foi enviado ao modelo por liberação.
• Agente importado de um arquivo chega sem as liberações e sem Conferi os campos desta ferramenta: quem importa decide de novo, na própria conta. A forma da Saída (os atributos de cada Objeto e o tipo dos itens de cada Lista) segue inteira no arquivo. Detalhes de importação e exportação: Importar e Exportar Agentes.

Detalhes de dado sensível no provedor do modelo: Dados Sensíveis, Etapa Agêntica e o provedor do modelo. Detalhes da LGPD no envio ao provedor: Dado sensível e a LGPD.

Limites e créditos

• Os limites (Voltas, Chamadas de agente, Minutos, Tokens) estão na tabela da seção Campos do painel da etapa. O tempo restante da etapa também limita a espera de um agente com Esperar terminar.
• A etapa cobra o crédito da execução em que está. Cada agente chamado cobra 1 crédito. Conector não cobra crédito. Os tokens do modelo são cobrados na conta do provedor, no conector. Detalhes de créditos: Créditos.

Voltas e ferramentas

Uma volta é uma consulta ao modelo e a resposta dele. Na mesma resposta o modelo pode pedir várias ferramentas: os conectores rodam juntos e os agentes, um depois do outro. O retorno delas chega ao modelo na volta seguinte, e a entrega do resultado também é uma resposta do modelo. As voltas que a etapa consome dependem de quantas vezes o modelo precisa esperar um retorno para decidir o passo seguinte; o número de ferramentas autorizadas não entra na conta.

• Com Voltas (máx.) em 1, o modelo não chega a ler o retorno de nenhuma ferramenta: ou entrega na primeira resposta, ou a etapa falha pelo teto de voltas. Ferramenta pedida na mesma resposta da entrega roda, e o retorno dela é descartado. O painel mostra o aviso embaixo do campo.
• Com Chamadas de agente em 0, todo agente da etapa é recusado na hora da chamada e o modelo recebe o aviso do limite. Conectores seguem normais. O painel mostra o aviso embaixo do campo; o 0 serve para desligar os agentes sem tirá-los da etapa.
• O padrão de 10 voltas cobre uma cadeia de algumas consultas dependentes com folga para correção. Para uma etapa longa, conte a cadeia mais longa de consultas dependentes que a Tarefa exige e some a entrega e uma correção.

Arrastar para dentro do card

No menu superior do Agent Builder, Conectores e Agentes abrem o painel lateral com a lista de cada um. Arraste um item para dentro do card. Detalhes dos painéis: Conectores → Arrastar e soltar no Processo ou na Etapa Agêntica e Subprocesso de Agentes → O painel Agentes.

O conector solto precisa estar ao alcance do dono do agente (na conta dele ou publicado para a empresa), porque é o runtime dele que o lê; fora disso o soltar é recusado com o motivo.

O soltar só vale com uma versão de desenvolvimento aberta. Também é recusado, com o motivo: o conector que já é o modelo ou já é ferramenta da etapa, o agente que já é ferramenta dela, o agente sem versão publicada, o próprio agente aberto no editor e qualquer ferramenta nova numa etapa que já tem 20 ferramentas. Com 20, um conector de IA de chat solto no núcleo ainda troca o modelo.

Enquanto arrasta, o card mostra o que vai acontecer: o núcleo acende para o modelo, a órbita acende com a vaga para a ferramenta, e o anel fica vermelho quando a etapa recusa o item. Uma pílula acima do card diz a ação. Tudo que o soltar grava é editável depois no painel da etapa. No Paralelizar Agentes, o card acende em âmbar e mostra a vaga do agente novo; no Aguardar Agentes, que não recebe agente, o anel fica vermelho.

O que o soltar grava

Soltar no card cria a mesma ferramenta que + Adicionar agente e + Adicionar conector criam no painel.

Os limites acompanham a ferramenta nova como no painel: Voltas (máx.) sobe para 2 se estava em 1, e Chamadas de agente sobe até o número de agentes autorizados. Com a ferramenta nova em Tem efeito, o aviso do soltar acrescenta Tem efeito: confira os campos no painel da etapa (pendência até conferir). O que vale entre o conector e a etapa na hora da chamada: O que vem do conector e o que vem da etapa.

Pendências e Salvar

Salvar grava a etapa mesmo incompleta; ela fica como pendência no fluxo e publicar fica bloqueado até resolver. O Salvar só é recusado quando o nome da etapa está vazio, quando o prefixo já é o de outra Etapa Agêntica do fluxo (a mensagem diz qual) ou quando um campo da Saída ou um atributo de um Objeto está sem nome ou tem nome inválido, repetido ou reservado.

No ▶ debug

O card mostra o modelo pensando (um arco gira no núcleo), o feixe até cada ferramenta chamada e a marca em quem foi usada; o contador diz a volta. Ao terminar, a marca e o contador ficam até a etapa rodar de novo. O terminal traz, volta a volta, o mesmo registro que o log da execução em produção: o texto do modelo, cada ferramenta pedida com os argumentos que o modelo mandou, quanto ela levou e o tamanho do retorno, a entrega e os tokens. Texto e argumentos passam pela máscara (variável marcada como sensível, parâmetro Secreto e segredo do Cofre aparecem como «•••») e são cortados; o retorno das ferramentas não é registrado, só o tamanho.

O ▶ debug chama o modelo e as ferramentas de verdade, inclusive agentes em produção. Para testar o resto do fluxo sem isso, fixe a etapa (📌): as variáveis da última execução são injetadas e a etapa não roda. Detalhes de debug: Debug.

Quando algo dá errado

A falha entra na Gestão de Erros da etapa, com as mesmas opções das outras etapas.

Exemplo de configuração

Variáveis gravadas: agentic.triagem.categoria, agentic.triagem.responsavel, agentic.triagem.urgente, agentic.triagem.cliente, agentic.triagem.cliente.nome, agentic.triagem.cliente.cnpj, agentic.triagem.status, agentic.triagem.turns, agentic.triagem.toolCalls, agentic.triagem.tokens e agentic.triagem.messages. Uma Decisão de Rota logo depois pode testar {agentic.triagem.urgente}.

Dicionário