Agentes Autônomos

┌──────────────────── AGENTE ────────────────────┐
│                                                 │
│  IDENTIDADE                                     │
│  ├─ Nome                                        │
│  ├─ Descrição                                   │
│  ├─ Ícone (AgentIconPicker)                     │
│  └─ Categoria (health_safety, quality, etc.)    │
│                                                 │
│  CÉREBRO                                        │
│  ├─ Provider (OpenAI | Anthropic)               │
│  ├─ Modelo (gpt-4o, claude-opus-4-7, etc.)      │
│  ├─ Temperature                                 │
│  ├─ MaxTokens                                   │
│  └─ MaxToolIterations                           │
│                                                 │
│  PERSONA                                        │
│  └─ System Prompt (com variáveis Mustache)      │
│                                                 │
│  SENTIDOS                                       │
│  └─ Multimodal: { text, images, audio, video }  │
│                                                 │
│  FERRAMENTAS (Tools)                            │
│  ├─ analyze_image                               │
│  ├─ mark_image_regions                          │
│  ├─ register_finding                            │
│  ├─ classify_content                            │
│  ├─ query_sql                                   │
│  ├─ call_api                                    │
│  ├─ create_workflow_action                      │
│  ├─ send_notification                           │
│  ├─ create_signature_document                   │
│  └─ ... (toolsConfig por tool)                  │
│                                                 │
│  ESTRUTURA DE SAÍDA                             │
│  └─ OutputSchemaTree (JSON Schema validado)     │
│                                                 │
│  AÇÕES PÓS-RESPOSTA (Output Actions)            │
│  └─ Para cada ação:                             │
│     ├─ when (condição sobre o output)           │
│     └─ ação (criar workflow, notificar, etc.)   │
│                                                 │
│  ACOPLAMENTO                                    │
│  ├─ TriggerEvent (response_created, etc.)       │
│  ├─ InputSelectorMode (specific_field | all)    │
│  ├─ SuggestedFieldHints                         │
│  └─ TriggerConditionsBuilder                    │
│                                                 │
│  AUDITORIA                                      │
│  ├─ ToolCallTimeline                            │
│  ├─ ExecutionDetailDrawer                       │
│  ├─ AICostEstimateBadge                         │
│  └─ AutomationHealthPanel                       │
└─────────────────────────────────────────────────┘

4.1. Editor visual de agentes

• URL: /ai-agents/new (novo), /ai-agents/:id/edit (editar).
• Painéis principais:
• Identidade + ícone (AgentIconPicker).
• Cérebro (modelo, temperatura, limites).
• Persona (system prompt com MustachePromptEditor + MustacheVariablePicker).
• Multimodal (toggles de texto/imagem/áudio/vídeo).
• Tools (ativar/configurar — cada tool tem config própria).
• Output Schema (OutputSchemaTree).
• Output Actions (OutputActionsBuilder).
• Trigger / Binding (BindingDrawer, TriggerConditionsBuilder).

4.2. Galeria de templates

Templates reais cadastrados em AI_AGENT_TEMPLATES:

Cada template traz payload completo pré-configurado (prompt, tools, schema, ações) — clica e adapta.

4.3. Tools (catálogo)

4.4. Output Schema (resposta validada)

• Editor: OutputSchemaTree.
• Engine: JSON Schema.
• Exemplo:

  {
    "type": "object",
    "properties": {
      "veredito": { "type": "string", "enum": ["ok","ressalvas","reprovado"] },
      "resumo": { "type": "string" },
      "findings": {
        "type": "array",
        "items": { "type": "object", "properties": { "severidade": {"type":"string"}, "descricao":{"type":"string"} } }
      }
    },
    "required": ["veredito","resumo"]
  }

• Por que: acaba o "texto livre" — agente devolve JSON pronto para Output Actions consumir.

4.5. Output Actions (a IA que age)

• Editor: OutputActionsBuilder.
• Estrutura: lista de ações com when (expressão sobre o output) + tipo da ação.
• Tipos de ação:
• create_workflow_action — abre ação no Z-Flow.
• update_response — atualiza campos da resposta original.
• send_notification — multicanal.
• schedule_booking — cria booking no Z-Schedule.
• create_signature_document — gera doc Z-Sign.
• call_api / webhook_out — empurra para sistema externo.
• award_points — pontua no Z-Score.
• Condições (when):
• findings.hasHigh
• veredito == 'reprovado'
• valor > 1000
• composições booleanas.

4.6. Binding e Trigger

• Editor: BindingDrawer + TriggerConditionsBuilder.
• Onde o agente roda:
• response_created — toda vez que um formulário X é submetido.
• workflow_step_entered — quando uma etapa Y é alcançada.
• cron — periodicamente.
• webhook — ao receber chamada externa.
• manual — botão dentro de uma tela.
• Filtros: condições adicionais — só rodar se (cliente == X), só rodar se (campo Y preenchido), etc.

4.7. Multi-provider e modelos

• Provider: OpenAI ou Anthropic (PROVIDER_MODELS).
• Por agente: cada um escolhe o melhor.
• Recomendações:
• Visão computacional: gpt-4o ou Claude Opus 4.7.
• Classificação simples: gpt-4o-mini ou Claude Haiku 4.5 (custo).
• Raciocínio complexo: Claude Opus 4.7.
• Geração de texto longa: Claude Sonnet 4.6.

4.8. Playground

• Componente: AIPromptPlayground.
• Para que: testar prompt e tools com payload de exemplo sem afetar dados reais.

4.9. Auditoria de execução

4.10. Variáveis Mustache no prompt

• {{form.titulo}}, {{form.id}}
• {{response.id}}, {{response.campos.X}}
• {{user.nome}}, {{user.cargo}}, {{user.email}}
• {{company.razao_social}}, {{company.cnpj}}
• {{now}}, {{today}}
• Helper: MustacheVariablePicker lista tudo disponível no contexto.

[ 06:30 — Operador envia checklist de início de turno ]
[         com selfie usando EPI ]
              │
              ▼
[ Trigger: response_created ]
              │
              ▼
[ Agente "Auditor de EPI" carregado ]
              │
              ▼
[ ITERAÇÃO 1: analyze_image(selfie) ]
              │
              ▼
[ ITERAÇÃO 2: mark_image_regions(["capacete_ausente"], bbox) ]
              │
              ▼
[ ITERAÇÃO 3: register_finding(severidade='high', descricao='Capacete ausente') ]
              │
              ▼
[ Agente retorna: { veredito: 'reprovado', findings: [...] } ]
              │
              ▼
[ Output Schema valida ✓ ]
              │
              ▼
[ Output Actions executam ]
              │
       ┌──────┼──────┬──────┬──────┐
       ▼      ▼      ▼      ▼      ▼
  [ create_  [send_  [schedule_[create_ [award_
   workflow_  notif] booking]  signature_points
   action]                     document]  -10]
       │
       ▼
  [ Supervisor recebe ação no /workflow ]
              │
              ▼
  [ Operador é treinado, advertência assinada, ]
  [ pontuação reduzida, sistema fechou o ciclo ]
              │
              ▼
[ Timeline auditável: ]
[   3 tools, 4.2s, $0.012, 1 finding high ]

Cenário A — Agente fiscal de OS de telecom

Trigger: OS de instalação enviada com fotos. Agente:

1. Verifica fotos exigidas (analyze_image).
2. Confere selfie do técnico (mark_image_regions rosto).
3. Lê nº de série do equipamento por OCR.
4. Confronta com pedido no ERP via query_sql.
5. Se OK → aprovar etapa; se divergência → abrir ação corretiva.

Cenário B — Agente de SAC com WhatsApp

Trigger: webhook do WhatsApp. Agente:

1. Classifica intenção (classify_content).
2. Consulta status do cliente (query_sql).
3. Decide: responder, criar chamado, agendar.
4. Output Action: send_notification ao cliente + create_workflow_action para humano se preciso.

Cenário C — Agente de qualidade noturno

Trigger: cron 22h. Agente:

1. Lê respostas do dia (query_sql).
2. Aplica heurística + classify_content para identificar inconsistência.
3. Para cada inconsistência: register_finding.
4. Output Action: e-mail consolidado para gestores + criar ações de retrabalho.

Cenário D — Agente avaliador de imagem de produto

Trigger: foto enviada por loja. Agente:

1. Verifica exposição correta (analyze_image).
2. Identifica preço por OCR.
3. Confronta com tabela oficial.
4. Output Action: pontuar loja + abrir correção se errado.

7.1. Pitch 8 minutos (este merece tempo extra)

7.2. Workshop 1 hora

Objetivos

• Entender a anatomia completa.
• Criar um agente do zero usando 3+ tools.
• Configurar Output Actions com 2+ condições.
• Auditar uma execução e justificar cada tool call.
• Estimar custo mensal de uma automação.

Agenda

Exercícios

1. Duplicar template: clone "Triagem inteligente", adapte para os seus campos, configure 1 Output Action de notificação.

2. Criar do zero: agente "Validador de nota fiscal" que recebe imagem, lê valor e CNPJ, confronta com pedido no banco e:

• aprova etapa do workflow se bater;
• abre correção se divergente.

3. Auditoria: execute o agente 5 vezes com inputs variados. Para cada execução, justifique no quadro:

• por que cada tool foi chamada;
• se houve iteração desperdiçada;
• custo total estimado para 1000 execuções/mês.

Quiz

1. O que faz o OutputSchemaTree?
2. Como o agente "decide" qual tool chamar?
3. O que acontece se o agente exceder maxToolIterations?
4. Como controlar custo?
5. Diferencie Trigger de Output Action.
6. Como testar sem afetar produção?
7. O agente pode chamar outro agente?
8. Como rastrear cada finding em auditoria?

Setup inicial

• [ ] Definir limite de custo mensal por agente.
• [ ] Definir grupos com permissão para editar agentes.
• [ ] Habilitar cache de respostas (/cache-responses).
• [ ] Documentar tools customizadas em toolsConfig.
• [ ] Validar 1 execução real de cada agente antes de subir.

Revisão mensal

• [ ] Quais agentes estão pagando o custo? Calcular ROI.
• [ ] Há agente com alta taxa de falha? Investigar.
• [ ] Há agente com maxToolIterations sempre estourando? Otimizar prompt.
• [ ] Output Actions estão sendo executadas conforme esperado?
• [ ] Versionamento de prompt sendo usado?

O agente pode escrever no ERP? Sim, via call_api ou tool customizada. Recomendado fazer com aprovação humana intermediária no início.

Posso ter agente que chama outro agente? Sim — composição via tool customizada ou via automação.

Como evitar loop infinito? maxToolIterations limita. Recomendado começar com 8 e ajustar.

Custo varia muito? Sim — função de modelo, tokens, imagens, tools. Use AICostEstimateBadge antes de subir.

O agente lembra de conversas anteriores? Por padrão, não. Pode-se passar histórico via Mustache se necessário.

Posso treinar o agente com meus dados? Sem fine-tuning nativo. Mas: bons prompts + tools que consultam o seu dado dão resultado superior na maioria dos casos.

Posso ter agente público (chamado por API)? Sim — via webhook trigger.

Como debug? Playground + Timeline da execução + logs.

Posso A/B test de prompt? Sim — duplicar agente, rodar em paralelo, comparar métricas.

E LGPD? Dados não saem da infra contratada (provider de IA configurável). Cache local, sem treinamento com dados do cliente, sem retenção indevida.

Esta narrativa visual desvenda a montagem de um agente autônomo: prompt com variáveis, gatilho, ferramentas, schema de saída e ações posteriores. Em seguida, mostra a validação no playground, a observabilidade das execuções, a análise visual e os controles operacionais de saúde e custo.

As evidências foram reunidas no sandbox em 24/05/2026; alguns quadros compartilhados situam o agente no ecossistema maior de IA. O playground é uma ilustração identificada no próprio quadro para representar uma execução de teste segura.

Print 01 - Galeria de agentes

Ampliar

Leitura do print: A galeria diferencia agentes criados de templates disponiveis.

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

Print 02 - Editor de agente

Ampliar

Leitura do print: O editor inicia a parametrização do colaborador digital.

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

Print 03 - Prompt com variaveis

Ampliar

Leitura do print: O agente Auditor de EPI combina instruções operacionais com variáveis disponíveis do formulário, demonstrando como contexto real pode alimentar a análise.

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

Print 04 - Binding de gatilho

Ampliar

Leitura do print: O construtor de rota define o evento que aciona o agente e antecipa o fluxo completo no mapa vivo, da origem da resposta às ações após a análise.

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

Print 05 - Catálogo de tools

Ampliar

Leitura do print: O painel de execução expõe as ferramentas disponíveis e evidencia quais capacidades de visão estão ativas no agente, como detecção e marcação de regiões em imagens.

Evidência capturada; desktop / 1440 x 980; origem: `Painel de Tools`.

Print 06 - Schema de saída

Ampliar

Leitura do print: A etapa Saída mostra o contrato JSON estruturado do agente e a validação do schema, requisito para integrar decisões de IA a workflows e BI.

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

Print 07 - Ações pos-resposta

Ampliar

Leitura do print: O construtor transforma findings do agente em ação operacional: a regra condicional encaminha resultados relevantes para um passo de workflow e apresenta o caminho em linguagem visual.

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

Print 08 - Playground

Ampliar

Leitura do print: O playground permite selecionar o agente, executar um cenário de teste e conferir tanto a saída estruturada quanto a sequência de ferramentas acionadas.

Imagem ilustrativa gerada com GPT Image a partir da marca oficial ZIINP; não representa execução efetiva no sandbox.

Print 09 - Cockpit com execuções

Ampliar

Leitura do print: O agente Inspetor de Poda mostra status, findings, custo e timeline real.

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

Print 10 - Detalhe de execução

Ampliar

Leitura do print: A linha de execução visível fornece entradas concluidas para abrir em detalhe durante a demo.

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

Print 11 - Linha do tempo

Ampliar

Leitura do print: O cockpit comprova o histórico de execuções, ainda que o drawer de tool calls não esteja expandido.

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

Print 12 - Imagem anotada

Ampliar

Leitura do print: O detalhe da execução apresenta imagens com regiões marcadas, severidade e confiança dos findings, além dos sinais operacionais de tools, tokens e custo.

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

Print 13 - Saude operacional

Ampliar

Leitura do print: A galeria de automações inclui a entrada para monitoramento agregado.

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

Print 14 - Custo do agente

Ampliar

Leitura do print: O cockpit exibe custo total de USD 0.2300 e custos por execução.

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

Agente 1 — "Auditor de EPI" (já apresentado, é o template-âncora)

Visão computacional → bounding box → finding → workflow.

Agente 2 — "Inspetor de Solda"

Provider: openai, modelo: gpt-4o
Multimodal: { images: true }
Tools: analyze_image, mark_image_regions, register_finding

Persona: Você é inspetor de solda certificado.
Avalia trincas, porosidade, alinhamento.

Output Schema:
  { classificacao: enum[A, B, C, reprovada],
    defeitos: [{ tipo, severidade, bbox }],
    sugestao: string }

Output Actions:
  - when: classificacao == 'reprovada'
    → create_workflow_action(retrabalho)
    → register_finding(severidade=critical)
  - when: classificacao == 'C'
    → notify(supervisor, "atenção")

Agente 3 — "Triador SAC WhatsApp"

Provider: anthropic, modelo: claude-haiku-4-5
Trigger: webhook (WhatsApp Business)
Tools: classify_content, query_sql, send_notification

Lógica:
  1. Classifica intenção (técnico, financeiro, comercial)
  2. query_sql para status do cliente
  3. Se rotina: responde direto
  4. Se complexo: cria ticket no Z-Flow + responde "vamos chamar"

Resultado: 47% resolvido sem humano.

Agente 4 — "Consultor de Qualidade de Dados"

Trigger: cron diário 23h
Tools: query_sql

Lógica:
  1. SELECT respostas do dia
  2. Para cada uma, valida:
     - GPS dentro de área esperada
     - foto presente
     - campos coerentes (data, números)
  3. Para cada inconsistência: register_finding

Output Actions:
  - cria 1 ação Z-Flow consolidada para cada operador com problema
  - envia digest para gestor de qualidade

Agente 5 — "Validador de Nota Fiscal"

Trigger: response_created (form "Reembolso")
Multimodal: { images: true }
Tools: analyze_image, query_sql

Lógica:
  1. Lê foto da NF, extrai CNPJ, valor, data
  2. Valida CNPJ ativo (query_sql tabela receita)
  3. Compara valor com política de reembolso

Output Actions:
  - when: ok → aprovar etapa
  - when: divergencia → devolver com observação detalhada

Agente 6 — "Agendador Conversacional"

Provider: openai, gpt-4o
Trigger: webhook (WhatsApp)
Tools: query_sql (disponibilidade), create_booking, send_notification

Persona: Você atende clientes pedindo agendamento.
Faz pequenas conversas mas é objetivo.

Lógica:
  1. Identifica tipo de serviço solicitado
  2. Lista 3 horários disponíveis
  3. Confirma escolha
  4. Cria booking
  5. Envia confirmação

Resultado: clínica reduziu ligações em 70%.

Agente 7 — "Resumidor Executivo"

Provider: anthropic, claude-opus-4-7
Trigger: cron diário 22h
Tools: query_sql, send_notification

Output:
  { titulo, indicadores: [...], alertas: [...], destaque: string }

Render markdown bonito, envia WhatsApp+e-mail pra diretoria.
Custo: R$ 0,20/dia.

Agente 8 — "Classificador NPS"

Trigger: response_created (form NPS)
Tools: classify_content

Output:
  { categoria, sentimento, sugerido_action }

Output Actions:
  - when: detrator → create_workflow_action (recuperação)
  - when: promotor → automation "convidar pra case"

Agente 9 — "Analisador de RDO"

Trigger: response_created (form "RDO")
Tools: query_sql (planejamento), classify_content

Lógica:
  1. Compara atividade reportada com planejado
  2. Detecta divergência
  3. Verifica coerência (clima ≠ chuvoso, mas atividade ar livre OK)

Output Actions:
  - cria ação se atraso > 15%
  - notifica engenheiro responsável

Agente 10 — "Auditor Reverso de Agente"

Meta-agente: audita execuções de OUTROS agentes.

Trigger: cron semanal
Tools: query_sql (logs de execução)

Lógica:
  1. Lê execuções da semana
  2. Identifica: alta iteração, alto custo, falhas frequentes
  3. Sugere otimizações de prompt
  4. Cria ação no Z-Flow para o gerente do agente

Agente 11 — "Tradutor Operacional"

Trigger: manual
Tools: nenhuma

Lógica simples:
  Traduz textos longos de documentos (laudos, relatórios) entre PT/EN/ES.
  Mantém termos técnicos.

Use case: empresa exporta para mercado externo.

Agente 12 — "Detector de Fraude em Reembolso"

Tools: query_sql, analyze_image

Lógica:
  1. Verifica frequência incomum
  2. Compara assinatura visual de NF (mesmo fornecedor sempre?)
  3. Cruza com policy

Output: flag de auditoria, sem decisão automática.

Padrão 1 — Agente decide → humano confirma (semi-autônomo)

Para casos sensíveis: agente prepara, humano clica "OK". Acelera 90% do trabalho, mantém responsabilidade humana.

Padrão 2 — Agente decide → executa → humano audita (autônomo supervisionado)

Para alto volume e baixa criticidade: agente age, gestor audita amostragem.

Padrão 3 — Cadeia de agentes

Agente A faz triagem → chama Agente B especializado → Agente C executa ação. Útil quando tarefas têm domínios diferentes.

Padrão 4 — Agente Guard (governança)

Agente que monitora outros agentes. Mata loops, calibra prompts, gera relatório.

Padrão 5 — Agente Embaixador (face com cliente)

Persona conversacional, multi-canal, sempre escala humano se sentir limite.

• Substituir 1 etapa humana por agente e medir economia.
• Conectar agentes a SQL externo (`08-integracoes-e-dados.md`).
• Compor cadeias de agentes (um chama o outro via tools).
• Criar agente de governança que audita outros agentes.
• Definir orçamento mensal por agente e configurar alerta.