Conteúdo: Análise por IA

O bloco de IA delega a geração da mensagem a um agente que consulta seus dados, valida dimensões e (opcionalmente) gera gráficos. Diferente do bloco de Texto com variáveis fixas, aqui você dá um briefing e a IA decide o que buscar, como interpretar e como redigir.

TIP

IA é a opção certa quando você quer interpretação ("vendas caíram 12% porque...") em vez de números frios ("vendas: R$ X"). É também o caminho quando o conjunto de dados muda muito e seria impraticável definir variável por variável.

---

Como Funciona

A IA trabalha em ciclo: pensa, busca dados, vê resultados, pensa mais, até produzir a resposta consolidada. Cada busca é executada nas aplicações autorizadas com os filtros que a IA decidiu.

---

Configuração

1. Aplicações (até 3)

A IA só pode consultar dados das aplicações selecionadas. Quanto menos apps, mais foco (e menos custo de processamento).

WARNING

Mais de 3 aplicações por bloco de IA bloqueia o save. Para análises com mais apps, use múltiplos blocos de IA no mesmo alerta, cada um focado em 1-3 aplicações.

2. Briefing do Analista

Texto livre (50 a 4000 caracteres) descrevendo:

• Objetivo: o que queremos descobrir/comunicar
• Público-alvo: executivo, técnico, comercial
• Métricas-chave: quais números priorizar
• Tom: formal, urgente, didático

Exemplo:

Briefing:
Analise as vendas das últimas 24h comparando com a média dos últimos
7 dias. Foque em anomalias por filial (queda maior que 10% ou pico
acima de 30%). Tom executivo, mensagem curta, recomende ação imediata
se houver queda crítica.

TIP

O botão "Sugerir Briefings" gera 3 templates pré-prontos baseados nas aplicações selecionadas. Bom ponto de partida quando você não sabe como começar.

3. Relatórios de Exemplo (até 5)

Você fornece exemplos de relatórios que servem como referência para a IA aprender o estilo de análise. Para cada exemplo você define:

Campo	Descrição
Nome	Como você se refere ao exemplo (ex.: "Vendas SP Janeiro")
Aplicação	Aplicação de onde puxar os dados
Campos	Colunas (mesma escolha do bloco de Relatório)
Filtros	Editor visual de filtros
Ordenação	Coluna + direção
Contexto (opcional)	Texto livre explicando o propósito do exemplo

"Criar do zero" vs "Importar de bookmark"

Dois caminhos para adicionar um exemplo:

• Criar do zero: abre um editor vazio, você monta o exemplo do nada (escolhe aplicação, campos, filtros, etc.)
• Importar de bookmark: seleciona um bookmark salvo da aplicação. Os campos/filtros/ordenação são copiados como ponto de partida. Você edita à vontade depois, o exemplo fica desacoplado do bookmark original. Se o bookmark for editado ou deletado, seu alerta segue funcionando.

TIP

O caso clássico de "importar e editar": você tem um bookmark "Vendas do Mês" e quer usar como exemplo dois períodos diferentes (mês atual e mês passado). Importe duas vezes, edite o filtro de data em cada uma, dê nomes distintos.

Campo de Contexto

Texto livre por exemplo. Vai pro briefing da IA como contexto daquele relatório específico. Útil quando o exemplo não é auto-explicativo:

Exemplo 1
  nome: "Vendas Mensal Comparativo"
  contexto: "Use como referência para análise sazonal. Métrica primária
            é Valor de Venda, não Ticket Médio."

A IA lê esse contexto e sabe interpretar o exemplo do jeito certo. Bookmarks puros não permitem esse tipo de anotação.

4. Formato de Saída

Define o que será entregue como conteúdo do alerta.

Modo	Comportamento	Padrão
Somente texto	Entrega só a mensagem final consolidada. Sem cards de gráfico, sem links.	✅ Default
Texto + gráficos e links	Além da mensagem, inclui gráficos gerados pela IA e links como cards/anexos separados.

TIP

"Somente texto" é o que a maioria dos casos quer: mensagem única, limpa, direta. Marque "Texto + gráficos" só se o destinatário se beneficia dos artefatos extras (ex.: dashboard executivo que vai ler com pressa e prefere ver gráfico).

5. Modo do Modelo

Modo	Custo	Velocidade	Uso
Rápido	1×	10-30s	Digests diários, briefings simples
Raciocínio profundo	4-5×	60-120s	Detecção de anomalia, análise causa-raiz, comparativos complexos

6. Memória

Quantas entregas anteriores do mesmo alerta a IA recebe como contexto.

Valor	Comportamento
0	Sem memória. Cada disparo é independente.
3 (padrão)	IA vê as 3 últimas mensagens entregues.
10 (máx)	IA vê até 10 entregas passadas.

Usa-se memória pra a IA comparar com o histórico recente ("vendas caíram 15% vs a análise de ontem"). Memória bem dimensionada vira o "fio condutor" do alerta dia após dia.

WARNING

Memória alta significa mais processamento consumido a cada disparo. Para alertas diários ativos, 3 costuma ser o ponto de equilíbrio. Suba para 7-10 só se a análise depende muito de contexto longitudinal.

---

Ferramentas Disponíveis para o Agente

Internamente, a IA tem ferramentas que decide quando chamar:

• Consultar dados: roda uma busca sobre uma das aplicações autorizadas (com campos, filtros, agrupamento e ordenação que a IA define). Opcionalmente gera gráfico.
• Validar valores: resolve um nome aproximado para o valor exato no banco (ex.: "filial cgr" para "Filial Centro Grande SP").

WARNING

Cada busca do agente traz no máximo ~30 linhas. Para um número global (um total, um consolidado da carteira), peça um valor agregado — uma consulta que já devolve a soma. Detalhar muitas entidades (centenas de clientes, produtos, filiais) e contar que a IA some essa lista é arriscado: ela chega truncada e o total pode oscilar entre disparos.

Em "Somente texto", a IA é orientada a não gerar gráficos. Mesmo que tente, eles são ignorados na entrega.

---

Roteiro Fixo vs Exploração Livre

Esta é provavelmente a parte mais importante de entender pra usar a IA bem. A IA tem dois modos de trabalho, e quem escolhe é você (pelo jeito que escreve o briefing e os relatórios de exemplo).

Modo Exploratório (padrão)

Quando você só dá o briefing e poucos (ou nenhum) relatórios de exemplo, a IA explora os dados livremente. Ela decide:

• Quais consultas fazer
• Quais colunas usar
• Que filtros aplicar
• Como agregar (por dia? por mês? por filial?)
• Em que ordem investigar

Esse modo é poderoso pra descoberta, ruim pra consistência. A cada disparo a IA pode tomar caminhos diferentes, porque pode haver mais de um caminho razoável para o briefing.

Quando usar:

• Detecção de anomalias (você não sabe de antemão o que vai aparecer)
• Investigação aberta ("descubra o que mudou na última semana")
• Análise causa-raiz onde o problema pode estar em qualquer dimensão

O sintoma de quem está nesse modo sem perceber:

"A mensagem de hoje veio totalmente diferente da de ontem. Antes ela falava de filiais, hoje ela falou de produtos. Como faço pra ela sempre falar de filiais?"

Isso é a IA explorando. Não é bug, é o comportamento padrão quando o briefing deixa em aberto.

Modo Roteiro Fixo

Quando você quer a mesma análise todo dia, com as mesmas consultas, no mesmo formato, faça o seguinte:

1. Crie os relatórios de exemplo com as consultas prontas. Cada um já é a consulta exata que você quer que a IA rode (campos, filtros, agrupamento, ordenação). Pense neles como "queries prontas pra rodar como-são".

2. No briefing, instrua explicitamente a IA a executar essas consultas como-são (sem inventar variações) e descrever os resultados num formato fixo.

Exemplo de briefing pra roteiro fixo:

Você é o analista comercial. Sua função é executar os relatórios de
exemplo abaixo COMO ESTÃO, sem improvisar variações.

Para cada relatório:
1. Execute exatamente como definido (campos, filtros, ordenação)
2. Reporte os top 3 resultados em uma frase curta
3. NÃO faça comparações adicionais não solicitadas
4. NÃO investigue dimensões além das que estão nos relatórios

Formato da mensagem:
📊 [Nome do relatório 1]
[3 linhas resumindo top 3]

📊 [Nome do relatório 2]
[3 linhas resumindo top 3]

Tom: direto, sem floreio.

3. Use o campo "Contexto" de cada relatório de exemplo para dar instruções específicas daquele exemplo:

Relatório: "Vendas por Filial"
  contexto: "Sempre cite VALOR LÍQUIDO, nunca bruto. Lista as 5 filiais
            com maior queda vs ontem. Não comente filiais estáveis."

Resultado: mensagem com formato previsível, mesmos cortes, mesmas dimensões, todo dia. A IA continua "interpretando" os números (variação, ranking, contexto), mas dentro do roteiro que você definiu.

Híbrido (o mais comum na prática)

A maioria dos alertas funciona melhor com mistura: 1-2 relatórios de exemplo definindo o "esqueleto" da análise + briefing dando margem pra IA destacar anomalias.

Briefing:
"Use os relatórios de exemplo como base obrigatória da análise. Sempre
reporte os números dos relatórios. ALÉM disso, se notar algo
genuinamente anômalo (variação >30% inesperada, padrão que rompe o
histórico), mencione no final como 'Observação adicional'."

Aqui a IA sabe o que é esperado (os relatórios) mas tem licença pra apontar algo fora do script. Útil pra digests "padrão + alertas embutidos".

Comparação Rápida

	Exploratório	Roteiro fixo	Híbrido
Relatórios de exemplo	0-1	3-5 com queries prontas	1-3 com queries prontas
Briefing	"Analise X"	"Execute os exemplos como-são"	"Use exemplos + destaque anomalias"
Consistência	Baixa	Alta	Média
Descobertas	Alta	Baixa	Média
Uso ideal	Investigação	Digest fixo	Operação do dia a dia

Memória + Roteiro Fixo

A memória combina muito bem com roteiro fixo. Como o formato da mensagem é consistente, a IA consegue facilmente comparar "hoje vs ontem" usando as últimas N entregas como referência:

Briefing (roteiro fixo + memória):
"Execute os relatórios como-são. Para cada métrica, compare com a
entrega de ontem (use a memória). Destaque com 🔼/🔽 a direção e
% de variação."

Com memória 0, cada disparo é independente. Com memória 3+, a IA tem "ontem, anteontem e três dias atrás" como contexto fresco.

---

Texto Final

A IA produz uma mensagem consolidada no último turno. Se a IA "pensa em voz alta" entre buscas ("vou buscar os dados..."), esse texto não é incluído na entrega, só a versão final consolidada.

Formato

A IA é orientada a produzir um texto que renderiza bem em todos os canais. Negrito, itálico, emojis em moderação. O canal de destino (WhatsApp/Email/Telegram) cuida da conversão do formato apropriado, você não precisa se preocupar.

---

Cenários Comuns

Digest Diário Comercial

Apps: [Vendas]
Briefing: "Resumo executivo de vendas de ontem vs média móvel de 7 dias.
          Destaque variações maiores que 10%. Tom direto, 3-4 frases."
Modo: Rápido
Memória: 3
Formato de saída: Somente texto

Detecção de Anomalia

Apps: [Vendas, Logística]
Briefing: "Investigue picos ou quedas anômalas em vendas, cruzando
          com tempo de entrega e ruptura de estoque. Apresente causa
          provável."
Modo: Raciocínio profundo
Memória: 7
Formato de saída: Texto + gráficos e links

Análise Comparativa com Bookmark

Apps: [Vendas]
Briefing: "Compare a performance da última semana com os relatórios
          de referência. Foque no que mudou e por quê."
Relatórios de exemplo:
  - Vendas Semana Passada (importado de bookmark)
  - Vendas Mesma Semana Ano Passado (importado, filtro editado)
Modo: Raciocínio profundo
Memória: 0
Formato de saída: Somente texto

Digest de Formato Fixo (Roteiro)

Para quando você quer exatamente o mesmo formato todo dia, sem variação:

Apps: [Vendas]
Briefing:
"Você é o analista comercial. Execute os relatórios abaixo COMO ESTÃO,
sem variar. Para cada um, reporte os 3 primeiros resultados em uma
linha, no formato:

📊 [Nome do relatório]
1. [valor 1] - [dimensão]
2. [valor 2] - [dimensão]
3. [valor 3] - [dimensão]

Compare com a entrega de ontem (memória) e marque 🔼/🔽 na linha
de cada item. Sem texto adicional fora do formato."

Relatórios de exemplo:
  - Top 3 Vendedores do Dia (com filtro data=Ontem)
  - Top 3 Filiais do Dia (com filtro data=Ontem)
  - Top 3 Produtos do Dia (com filtro data=Ontem)

Modo: Rápido (não precisa de raciocínio profundo se é "execute o roteiro")
Memória: 3
Formato de saída: Somente texto

A mensagem que chega é previsível dia após dia, com os mesmos cortes, mesmas dimensões. O destinatário sabe o que esperar.

---

Boas Práticas

✅ Briefing direto, exemplos eloquentes

A IA segue o que você pede e imita o estilo dos exemplos. Briefing prolixo + exemplos esparsos resulta em saída inconsistente.

✅ "Análise diária de vendas. 3 frases. Destaque variação % vs ontem."
❌ "Faça uma análise abrangente e detalhada considerando múltiplos
   aspectos das vendas, incluindo mas não se limitando a..."

✅ Contextualize exemplos importantes

Quando o exemplo tem nuance (métrica secundária, regra de negócio), use o campo "Contexto":

Exemplo: "Vendas Líquidas"
  contexto: "ATENÇÃO: é Valor Líquido, não Valor Bruto. Já desconta
            estornos e devoluções."

✅ Inconsistência na saída? Provavelmente está exploratório demais

Se você reclama "a mensagem de hoje veio diferente da de ontem", você está no modo exploratório. A solução é migrar pra roteiro fixo: defina as consultas como relatórios de exemplo e instrua a IA no briefing a executá-las "como-são".

✅ Pré-valide acessos do criador

Se o criador do alerta perder acesso a uma aplicação, ela é silenciosamente removida do contexto. Se sobrar nenhuma aplicação válida, o alerta entrega uma mensagem de erro. Verifique acessos depois de mudanças de permissão.

✅ Use o botão "Pré-visualizar" antes de ativar

A IA pode rodar dezenas de variações sutis dependendo do briefing. Sempre pré-visualize 2-3 vezes antes de ativar pra produção. Se a saída variar muito entre execuções e isso é problema, ajuste pra roteiro fixo.

❌ Não confunda "memória" com "histórico de dados"

A memória é só das mensagens entregues anteriormente, não dos dados do banco. Para a IA comparar dados históricos, ela mesma faz a consulta com filtros de data (ex.: "Últimos 30 dias").

❌ Não force "Texto + gráficos" se a maioria dos destinatários é WhatsApp

Gráficos como assets separados ficam visualmente confusos no chat móvel. Para WhatsApp, prefira somente texto com um Relatório PDF anexo se precisar de visualização.

❌ Não use IA pra tarefas que variável dá conta

Se a mensagem é "Vendas de hoje: R$ X", não use IA. Use Texto com variável. É mais rápido, mais barato, e 100% consistente. IA é pra quando há interpretação, comparação, ranking dinâmico ou narrativa que se ajusta aos dados.

---

Limites

Limite	Valor
Tempo máximo de geração	90 segundos. Acima disso, retorna mensagem de timeout.
Briefing	50 a 4000 caracteres
Aplicações por bloco	1 a 3
Relatórios de exemplo	5 (criados do zero + importados de bookmark, combinados)
Memória	0 a 10
Linhas por consulta do agente	~30 por busca. Para totais exatos, prefira uma consulta agregada (um número), não a soma da lista.
Destinatários por alerta com IA	50 (cap específico do bloco de IA)

O custo de processamento conta no consumo de IA do tenant. Modo Rápido consome aproximadamente 1×, Raciocínio Profundo 4-5×. Veja HEC > Tenants > Consumo IA para o detalhamento.

---

Próximos Passos

• Combine com Texto e Relatório para mensagens híbridas
• Configure os canais de entrega
• Para regras "quando dispara?", veja Condicional ou Agendamento