Z-IA

┌──────────────── Z-IA ─────────────────┐
│                                        │
│  🧠 Agentes (cadastrados em /ai-agents)│
│      ├─ Persona + Prompt + Tools       │
│      ├─ Multimodal: texto/img/áudio/vid│
│      ├─ Output Schema + Actions        │
│      └─ Provider: OpenAI / Anthropic   │
│                                        │
│  💬 Assistentes contextuais            │
│      ├─ Form Agent (/forms/:id/agent)  │
│      ├─ Scheduling Agent               │
│      ├─ Signature Agent                │
│      └─ Agente Geral (/agentes)        │
│                                        │
│  ⚙️ Automations                        │
│      ├─ Cron / Webhook / Evento        │
│      └─ Manual (ManualAutomationButton)│
│                                        │
│  🎙️ Preenchimento por voz / foto       │
│  🧪 Playground (AIPromptPlayground)    │
│  📊 Insights automáticos                │
│  💰 Estimativa de custo                 │
└────────────────────────────────────────┘

4.1. Agentes de IA cadastrados

• Onde: /ai-agents (lista), /ai-agents/new (editor), /ai-agents/:id (detalhe e execuções).
• O que faz: cada agente é uma configuração persistente com persona, tools, modelo, schema de saída, ações pós-resposta, gatilhos.
• Por que importa: centraliza tudo o que a empresa "ensinou" sobre si para a IA. Cada agente é um colaborador digital com função clara.

4.2. Assistentes contextuais

4.3. Preenchimento por voz e por imagem

• Componente: AIFormFillButtons (no preenchimento de formulários).
• Voz: botão de microfone → aiResponseService.fillFormWithAudio → IA transcreve, interpreta e preenche os campos certos.
• Imagem: botão de câmera → captura foto → IA aplica visão computacional → preenche campos.
• Onde aparece: /forms/:id/fill (quando o formulário tem respondWithAudio / respondWithImage habilitado).

4.4. Automations (/automation)

• Trigger types:
• Cron ("toda segunda às 7h gerar resumo de pendências").
• Webhook ("quando ERP me chamar, processar e abrir ação").
• Evento (form_submission, workflow_step_completed, signature_signed, booking_started).
• Manual (ManualAutomationButton aparece em outras telas).
• Galeria de templates (AUTOMATION_TEMPLATES):
• Triagem inteligente de chamados.
• Classificação multi-rótulo (NPS, sentimento).
• Resumo executivo noturno.
• Varredura de qualidade.
• Painel de saúde (AutomationHealthPanel): sucesso, falha, latência, custo.

4.5. Catálogo de tools que o agente pode chamar

Exemplos reais do código:

4.6. Output Actions

• Componente: OutputActionsBuilder.
• O que faz: quando o agente termina, executa ações conforme condições (when: 'findings.hasHigh'):
• criar ação de workflow;
• escalar para grupo;
• notificar;
• agendar;
• gerar documento;
• gravar em banco externo.
• Por que é diferencial: o agente não só responde — ele muda o estado do sistema.

4.7. Output Schema

• Componente: OutputSchemaTree.
• O que faz: força a resposta do agente a ser JSON validado segundo schema. Acaba o "texto livre".
• Exemplo: { veredito: 'ok|ressalvas|reprovado', resumo: string, findings: array }.

4.8. Editor de prompt com variáveis Mustache

• Componente: MustachePromptEditor.
• Variáveis disponíveis: {{form.titulo}}, {{user.nome}}, {{user.cargo}}, {{response.id}}, {{company.nome}}, etc.
• Helper: MustacheVariablePicker mostra todas as variáveis disponíveis no contexto.

4.9. Multi-provider

• OpenAI (gpt-4o, gpt-4o-mini, etc.) e Anthropic (Claude Opus, Sonnet, Haiku).
• Selecionável por agente — escolha o modelo certo para a tarefa/custo.

4.10. Estimativa de custo e auditoria

• `AICostEstimateBadge`: mostra custo médio por execução antes de subir o agente.
• `ToolCallTimeline`: linha do tempo de cada tool chamada, com input/output.
• `ExecutionDetailDrawer`: detalhe da execução, reproduzível.
• `AutomationHealthPanel`: custo agregado.

4.11. Playground

• Componente: AIPromptPlayground.
• O que faz: testa o prompt antes de subir para produção. Sem afetar dados reais.

4.12. Cache de respostas

• URL: /cache-responses.
• O que faz: reaproveita respostas equivalentes para baixar custo de inferência.

4.13. Insights automáticos

• Componente: AiInsightsSection.
• O que faz: agentes que rodam em background, identificam anomalia ou padrão, e empurram cards para o dashboard.

4.14. Conexões SQL externas para IA

• URL: /companies/:id/database-connections.
• O que faz: o agente pode consultar o ERP do cliente com query_sql, respondendo perguntas que dependem do dado real do cliente.
• Detalhamento: `08-integracoes-e-dados.md`.

4.15. Conteúdo gerado por IA

• O Z-IA assiste na criação de formulários, fluxos, documentos, queries SQL e dashboards a partir de descrição em linguagem natural.

[ Gestor digita: "Quantos checklists foram reprovados ]
[ na unidade Norte nos últimos 7 dias?" ]
              │
              ▼
[ Agente do formulário recebe a pergunta ]
              │
              ▼
[ Decide: precisa de query_sql ]
              │
              ▼
[ Executa: SELECT COUNT(*) FROM respostas WHERE ... ]
              │
              ▼
[ Recebe 17 ]
              │
              ▼
[ Decide: gerar resposta com contexto ]
              │
              ▼
[ "Foram 17 reprovações na unidade Norte nos últimos 7 dias. ]
[  3 foram por EPI ausente, 8 por equipamento sem leitura,    ]
[  6 por ausência do operador." ]
              │
              ▼
[ Timeline mostra: 1 tool chamada, 1.2s, custo $0.0008 ]

Cenário A — Auditor de EPI em tempo real

Operador envia checklist com selfie. Agente "Auditor de EPI":

• analisa a foto;
• desenha bounding box em capacete ausente;
• registra finding high;
• abre ação corretiva no Z-Flow para o supervisor;
• gera termo de advertência no Z-Sign.

Sem operador humano no meio.

Cenário B — Resumo executivo noturno

Automation cron diária 22h: agente lê todas as respostas e workflows do dia, gera resumo executivo em markdown, envia por e-mail e WhatsApp para a diretoria. Custo médio: R$ 0,20 por execução.

Cenário C — Pergunta em linguagem natural

Gerente abre /forms/auditoria-2026/agent, pergunta "Quais lojas tiveram mais não-conformidades em maio?". Em 4 segundos, recebe ranking com top 5 e principais causas.

Cenário D — Triagem inteligente de chamados

Formulário público de chamado. Agente "Triagem":

• classifica em Crítico/Alto/Médio/Baixo;
• abre ação de workflow no SLA correspondente;
• se Crítico, notifica plantão por WhatsApp.

7.1. Pitch 5 minutos

7.2. Apresentação 15 minutos

Objetivos

• Usar os 4 assistentes contextuais.
• Criar um agente do zero a partir de template.
• Configurar 1 automation com cron.
• Interpretar timeline e custo.

Agenda

Exercício 1 — Usar

• Faça 3 perguntas em linguagem natural ao agente do formulário.
• Marque um horário de visita pelo agente de agendamento.

Exercício 2 — Criar

• Duplicate o template "Triagem inteligente".
• Adapte para o seu fluxo de atendimento.
• Configure 1 Output Action (criar workflow).
• Teste no Playground antes de subir.

Exercício 3 — Automation

• Crie automation cron "diariamente 18h enviar resumo do dia".
• Inclua link para /workflow no e-mail.

Exercício 4 — Auditoria

• Abra 1 execução do agente criado.
• Identifique tempo total, número de tools chamadas e custo.

Setup inicial

• [ ] Conectar 1 base SQL externa para o agente consumir.
• [ ] Configurar limite de custo mensal por agente.
• [ ] Definir grupos que podem editar agentes.
• [ ] Testar cada agente no Playground antes de produção.
• [ ] Configurar cache de respostas para reduzir custo.

Revisão mensal

• [ ] Qual agente tem maior custo? Vale o ROI?
• [ ] Há agente com muitas iterações? Otimizar prompt.
• [ ] Há agente subutilizado? Ajustar trigger ou descontinuar.
• [ ] Os Output Actions estão sendo executados como esperado?

O agente "alucina"? Mitigado por: Output Schema (resposta validada), tools com dados reais, timeline auditável, Playground antes de subir.

Quanto custa? Depende de modelo + tokens + tools. AICostEstimateBadge mostra antes de rodar.

Posso usar Claude e GPT? Sim — multi-provider. Selecionável por agente.

Como saber se o agente está funcionando bem? AutomationHealthPanel mostra sucesso/falha/latência. ExecutionHistoryDrawer mostra histórico.

O agente tem permissão? Sim — papel, grupos, tools liberadas. Tudo configurável.

Posso desligar um agente? Sim — pausa por toggle. Sem afetar histórico.

O agente entende português? Sim — funciona nativamente.

Posso versionar o prompt? Sim — o editor mantém histórico de versões.

Os quadros a seguir apresentam a IA como capacidade operacional, não apenas conversacional. A jornada começa na criação do agente, passa pelo cockpit de execução, ações e custo, e chega à automação acompanhada, aos webhooks e ao trabalho com dados em campo.

As imagens foram documentadas no sandbox em 24/05/2026; alguns quadros reaparecem deliberadamente porque a mesma interface comprova mais de uma capacidade integrada da plataforma.

Print 01 - Galeria de agentes

Ampliar

Leitura do print: A galeria expõe agentes ativos e templates para criação guiada.

Evidência capturada; desktop / 1440 x 980; origem: `/ai-agents`.

Print 02 - Editor de agente

Ampliar

Leitura do print: O editor inicia a definição de identidade, modelo e configuração operacional.

Evidência capturada; desktop / 1440 x 980; origem: `/ai-agents/new`.

Print 03 - Cockpit do agente

Ampliar

Leitura do print: O cockpit real mostra status, tools, findings, custo e execuções do agente Inspetor de Poda.

Evidência capturada; desktop / 1440 x 980; origem: `/ai-agents/:id`.

Print 04 - Linha de execução

Ampliar

Leitura do print: A mesma tela inclui registros recentes de execução, duracao e custo por rodada.

Evidência reutilizada; desktop / 1440 x 980; origem: `/ai-agents/:id - execuções`.

Print 05 - Output Actions

Ampliar

Leitura do print: A configuração exemplifica como a IA deixa de apenas responder: findings acima do limiar acionam o encaminhamento para uma etapa de workflow.

Evidência reutilizada; desktop / 1440 x 980; origem: `OutputActionsBuilder`.

Print 06 - Indicador de custo

Ampliar

Leitura do print: O cockpit exibe custo acumulado e custo das execuções no contexto real do agente.

Evidência reutilizada; desktop / 1440 x 980; origem: `AICostEstimateBadge`.

Print 07 - Pergunta em linguagem natural

Ampliar

Leitura do print: O agente contextual de formulário demonstra a interface de consulta sobre dados coletados.

Evidência reutilizada; desktop / 1440 x 980; origem: `/forms/:id/agent`.

Print 08 - IA por voz

AmpliarMobile

Leitura do print: O bloco Preencher com IA permite iniciar áudio no próprio formulário e acompanhar a gravação antes de processar o conteúdo coletado.

Evidência reutilizada; mobile / iPhone 14 + composição editorial; origem real: `/forms/:id/fill - microfone`.

Print 09 - Galeria de automações

Ampliar

Leitura do print: A área de automações lista gatilhos e operações conectadas a IA.

Evidência capturada; desktop / 1440 x 980; origem: `/automation`.

Print 10 - Saude das automações

Ampliar

Leitura do print: O painel da listagem concentra a entrada para indicadores agregados de execução.

Evidência capturada; desktop / 1440 x 980; origem: `AutomationHealthPanel`.

Print 11 - Exemplo de webhook

Ampliar

Leitura do print: A configuração do gatilho webhook apresenta método, autenticação e um exemplo de chamada em cURL, tornando explícito como uma automação pode ser acionada por integração externa.

Evidência capturada; desktop / 1440 x 980; origem: `WebhookExampleCard`.

Print 12 - Cache de respostas

Ampliar

Leitura do print: A fila demonstra resiliencia e sincronização para entradas assistidas.

Evidência reutilizada; desktop / 1440 x 980; origem: `/cache-responses`.

🏭 Indústria — Inspeção visual de solda

Operador envia foto da solda. Agente "Inspetor de Solda":

• analisa porosidade, trincas, alinhamento via visão computacional;
• registra finding com severidade;
• abre ação corretiva se severidade ≥ high.

Resultado: inspeção 100% das soldas (antes era amostragem).

⚡ Telecom — Triagem de chamado via WhatsApp

Cliente abre chamado pelo WhatsApp. Webhook → agente:

• classifica intenção (suporte técnico, financeiro, comercial);
• consulta status do contrato (SQL no ERP);
• responde automaticamente OU cria chamado no Z-Flow.

Resultado: 47% dos chamados resolvidos sem humano.

🏥 Saúde — Pré-triagem clínica

Paciente preenche formulário de sintomas. Agente:

• classifica gravidade (verde/amarelo/vermelho);
• sugere especialidade;
• agenda direto se rotina;
• escala se urgência.

🛒 Varejo — Conferência de exposição em loja

Foto da gôndola. Agente:

• identifica produtos esperados via visão;
• confere planograma;
• aponta divergências;
• pontua a loja.

🏗️ Construção — Validação de RDO

Diário de obra preenchido. Agente:

• valida coerência entre atividades, mão de obra e clima;
• aponta inconsistências (atividade impossível com a equipe relatada);
• cruza com previsão de avanço.

💰 Financeiro — Análise de nota fiscal

NF anexada. Agente:

• extrai CNPJ, valor, itens, datas;
• confronta com pedido no ERP;
• aprova ou marca divergência;
• agenda pagamento ou abre disputa.

📊 Executivo — Resumo diário 22h

Cron 22h. Agente lê tudo do dia, gera resumo executivo (markdown), envia por WhatsApp pra diretoria. Custo: R$ 0,20/dia.

🎓 RH — Análise de currículo

Currículos chegam via formulário público. Agente:

• extrai dados, formação, experiência;
• classifica fit com vaga;
• gera resumo + nota;
• cria ação no Z-Flow só para os top 10.

Receita 1 — Agente "Auditor de EPI"

Provider: openai
Modelo: gpt-4o
Temperatura: 0.1
Multimodal: { images: true }

System prompt:
  Você é um auditor de SST.
  Recebe foto do colaborador no início de turno (formulário {{form.titulo}}).
  Objetivos:
    1. Identificar EPIs visíveis (capacete, óculos, luvas, colete, botina).
    2. Para cada ausente OU incorreto, chamar mark_image_regions(bbox) e register_finding.
       - critical: ausência de capacete em altura
       - high: ausência de capacete OU colete
       - medium: uso incorreto
       - low: pequenas inconformidades
  Retornar JSON { veredito, resumo }.

Tools: analyze_image, mark_image_regions, register_finding

Output schema:
  { veredito: enum[ok, ressalvas, reprovado], resumo: string }

Output Actions:
  - when: findings.hasHigh
    → create_workflow_action(acao=rejeitar, grupo=supervisao)
    → send_notification(canal=whatsapp, destinatario=supervisor)
  - when: veredito == 'reprovado'
    → create_signature_document(template=advertencia_epi)

Trigger: response_created
Filtro: formulário "Checklist início de turno"

Receita 2 — Agente "Triagem de Chamado SAC"

Provider: anthropic
Modelo: claude-haiku-4-5
Temperatura: 0.2

Persona: Você triaga chamados de SAC. Devolve criticidade e categoria.

Tools: classify_content, query_sql

Output schema:
  { categoria: enum[técnico, financeiro, comercial],
    criticidade: enum[baixa, média, alta, crítica],
    resumo: string }

Output Actions:
  - when: criticidade == 'crítica'
    → send_notification(canal=whatsapp, destinatario=grupo_plantao)
    → create_workflow_action(SLA=1h)
  - otherwise:
    → create_workflow_action(SLA=24h)

Trigger: response_created (formulário "Abrir chamado")

Receita 3 — Agente "Consultor SQL"

Provider: openai
Modelo: gpt-4o
Tools: query_sql

Persona: Você responde perguntas dos gestores consultando o banco de dados X.
Schema disponível: [colar schema da empresa]

Output schema:
  { sql_executado: string, resultado: any, explicacao_em_pt: string }

Trigger: manual (botão "Pergunte ao agente")

Receita 4 — Agente "Validador de NF"

Provider: openai
Modelo: gpt-4o (visão)
Tools: analyze_image, query_sql, create_workflow_action

Persona:
  Você valida nota fiscal anexa contra pedido no ERP.

Lógica:
  1. analyze_image(nf) → extrai CNPJ, valor, série
  2. query_sql(SELECT * FROM pedidos WHERE id = {{response.pedido_id}})
  3. compara
  4. retorna { ok: bool, divergencias: [...] }

Output Actions:
  - when: ok == true
    → aprovar etapa do workflow
  - when: ok == false
    → create_workflow_action(devolver, observacao=divergencias)

Receita 5 — Automation "Resumo executivo noturno"

Trigger: cron daily 22:00
Action: chamar agente "Resumidor Executivo"

Agente:
  Provider: anthropic, modelo: claude-opus-4-7
  Tools: query_sql

  Lógica:
    1. consulta KPIs do dia (volumes, SLA, NCs)
    2. consulta variação WoW
    3. consulta top 3 alertas
    4. gera resumo em markdown

  Output: { markdown: string }

Pós-action:
  - send_notification(canal=whatsapp, destinatario=grupo_diretoria)
  - send_notification(canal=email, destinatario=ceo)

• Conectar 1 base SQL real do cliente e demonstrar perguntas sobre ERP.
• Substituir 1 etapa humana por agente IA e medir economia.
• Criar agente de qualidade que varre respostas e aponta inconsistências.
• Implantar agente de SAC com webhook de WhatsApp.
• Ver detalhamento técnico em `10-agentes-autonomos.md`.