Analisar com IA

Analisar com IA executa uma instrução em um modelo e devolve um objeto com os campos que você definiu. O passo é headless: não conversa com o cliente, não publica uma mensagem e não aciona ferramentas. Use-o para classificar, extrair ou normalizar dados antes de uma Condição ou de uma Ação.

O modelo não recebe a conversa automaticamente. Ele recebe apenas o texto montado em Instrução, depois que o SquadOS substitui as variáveis. Para analisar um atendimento, inclua uma variável de conversa disponível naquele ponto, normalmente conversation.transcript.

Adicionar e configurar o passo

No editor da automação:

1. adicione Analisar com IA pela seção de IA da paleta;
2. escolha o Modelo, ou mantenha o padrão;
3. escreva a Instrução e insira as variáveis necessárias;
4. abra Campos de saída e adicione pelo menos um campo;
5. ligue o passo aos próximos nós e clique em Salvar.

Salvar publica uma nova versão do grafo. A publicação recusa um schema de saída vazio, nome de campo vazio, inválido ou repetido, tipo desconhecido, enumeração com menos de duas entradas e variável indisponível naquele caminho.

O editor chama a opção sem escolha explícita de Modelo padrão da organização, mas o runtime atual usa o modelo padrão global ativo da plataforma. Se a escolha do modelo precisa permanecer estável, selecione-o explicitamente. Essa divergência está registrada na auditoria do produto.

Escrever a instrução

A instrução aceita as variáveis disponíveis acima desse passo. Uma instrução útil declara o material de entrada, a decisão e os critérios de cada saída. Por exemplo:

Leia a transcrição abaixo.
Classifique a intenção como compra, suporte ou outro.
Marque urgência somente quando o cliente indicar prazo de até 24 horas.

Transcrição:
{{conversation.transcript}}

Nem todo gatilho fornece uma conversa. Em fluxos de Lista, Agenda ou Audiência, use apenas os grupos que aparecem no seletor, como contato, lista ou payload do gatilho. Se conversation.transcript não estiver disponível, crie ou obtenha o contexto necessário antes da análise.

Não deixe Instrução vazia. A publicação atual não impede isso: o modelo ainda pode ser chamado, consumir créditos e devolver valores sem contexto útil. Também não peça à análise para consultar uma base, enviar mensagens ou executar ações. O nó não oferece ferramentas; o grafo deve tomar a decisão e executar a ação em passos separados.

Definir os campos de saída

Cada item de Campos de saída tem:

• Nome: a chave do resultado e o sufixo da variável. Use somente letras sem acento, números e _, sem espaços;
• Tipo: Texto, Número, Sim ou não ou Uma das opções;
• Opções: aparece em Uma das opções e recebe valores separados por vírgula;
• Descrição: explica ao modelo o significado e o critério do campo.

Use nomes estáveis, como intencao, urgente e valor_estimado. Para uma enumeração, informe pelo menos duas opções distintas e sem ambiguidade, como compra, suporte, outro. O produto hoje aceita duas entradas iguais como se fossem duas opções; não dependa desse comportamento.

Descreva cada campo como uma regra verificável. Por exemplo:

• intencao, Uma das opções: “Use compra quando houver intenção explícita de contratar; suporte para problema com uso atual; outro nos demais casos.”
• urgente, Sim ou não: “Verdadeiro somente quando o cliente mencionar prazo de até 24 horas.”
• resumo, Texto: “Uma frase factual, sem instruções ou dados que não estejam na entrada.”

O SquadOS exige que a resposta respeite esses tipos. Se o modelo devolver JSON truncado ou inválido, o passo pode tentar novamente até duas vezes. Erros de rede, autenticação ou provedor não recebem a mesma repetição automática.

Usar o resultado

Depois de uma execução bem-sucedida, cada campo vira uma variável com o identificador do nó. Se o passo for n5 e o campo se chamar intencao, use {{n5.intencao}}.

O seletor só oferece a saída em nós a jusante e em caminhos que realmente passam pela análise. Um ramo paralelo não recebe esse resultado. O padrão mais comum é:

1. Analisar com IA devolve os campos;
2. Condição compara uma saída, como {{n5.intencao}};
3. cada ramo aplica tags, grava metadados, envia conteúdo ou encerra o fluxo.

Não trate a classificação como autorização para uma ação irreversível sem uma regra adicional. A transcrição é conteúdo escrito pelo cliente e pode conter instruções maliciosas ou enganosas; o schema limita a forma da resposta, mas não garante que a classificação esteja correta.

Créditos, falhas e teste

Este é o passo de automação que chama um modelo e consome créditos. Com chave própria do OpenRouter, o SquadOS registra 1 crédito fixo e a chamada usa essa chave. Sem chave própria, usa a chave da plataforma e converte o custo informado pelo provedor em créditos.

Uma tentativa que o provedor já processou pode ter custo mesmo quando a etapa termina em erro. Em resposta estruturada inválida, até três chamadas podem ocorrer. O ledger atual usa o mesmo identificador para essas retentativas e pode mostrar somente a primeira cobrança, embora o provedor tenha processado as demais; confira também o painel do seu provedor quando usar BYOK. A divergência está registrada no dossiê e não foi corrigida pela documentação.

Se a cobrança no SquadOS falhar depois de uma resposta válida, o passo falha e os próximos nós não devem avançar. Consulte o resultado e o custo da execução em Execuções e testes.

O modo Testar simula ações de envio e escrita, mas Analisar com IA executa de verdade e consome créditos. Use uma conversa representativa, confira os valores e tipos devolvidos e repita casos-limite antes de ativar. Em automações com reentrada Sempre, cada novo evento pode executar e cobrar a análise novamente.