Runbook - Assistentes IA do Sagazchat

Manual operacional para uma IA ou pessoa criar, configurar e explicar Criação Assistentes IA no Sagazchat.

8 min de leitura Atualizado em 30 de ago. de 2026

Manual operacional para uma IA ou pessoa criar, configurar e explicar Criação > Assistentes IA no Sagazchat.

Status: validado live em 2026-08-30 — app v4.24.1. O histórico de laboratório permanece abaixo; não editar o assistente real Assistente Exemplo sem ordem explícita.

1. Onde fica

Sidebar: Criação > Assistentes IA
URL: https://app.sagazchat.com/manager-ia
Rota interna observada para abrir um assistente: a URL permanece /manager-ia, mas a tela chama GET /assistents/{uuid} e abre um modal/editor sobre a lista.

2. Estrutura da lista

A tela tem:

titulo Assistentes IA;
contador Tokens no topo (used/limit, exemplo validado 0/infinito);
botao Configurar;
botao Criar agente;
busca Encontre um agente;
botoes de visualizacao em lista/grade;
cards de assistentes.

Cada card mostra:

nome do assistente;
data de criacao;
canais vinculados, quando existirem;
contexto/tokens aproximados quando houver conteudo configurado.

Exemplo real:

Assistente Exemplo
criado em 17/04/26
Nenhum canal vinculado
Contexto: ~5.378 tokens

3. Criar assistente

Fluxo validado:

Clicar Criar agente.
Modal Novo assistente abre.
Preencher Nome do assistente.
Clicar Adicionar ou usar Ctrl + Enter.

API observada:

POST /assistents
Content-Type: application/json

{ "name": "LAB - Assistente Flowbuilder" }

Resposta real do laboratorio:

{
  "id": 42,
  "uuid": "9bde6b6e-f9af-4336-b0fc-8c4823fcf220",
  "name": "LAB - Assistente Flowbuilder",
  "companyId": 39,
  "companyName": null,
  "businessType": null,
  "language": null,
  "address": null,
  "schedules": null,
  "services": null,
  "questions": null,
  "departamentId": null
}

Regra importante: o modal de criacao so pede nome. A configuracao completa vem depois, clicando no card criado.

4. Abrir e configurar um assistente

Para abrir o editor:

Ir para /manager-ia.
Clicar no card do assistente.
Um modal grande abre sobre a lista.

Chamadas observadas ao abrir o laboratorio:

GET /assistents/9bde6b6e-f9af-4336-b0fc-8c4823fcf220
GET /assistents/qtd
GET /queue
GET /assistents/42/kbs

O GET /queue alimenta o campo Encaminhar para setor.

Departamentos reais carregados na conta:

id	Nome
77	Comercial - Atendente 1
78	Comercial - Atendente 2
79	Financeiro/RH

5. Campos do editor

Configuracoes

Campo	Valor/API	Observacao
Tom de voz	`language`	Opcoes confirmadas no bundle: `informal` (Informal) e `formal` (Formal).
Encaminhar para setor	`departamentId`	Define para qual departamento o assistente encaminha quando o cliente pede humano.

Opcoes do encaminhamento:

vazio: Selecione um setor;
null: Apenas abrir;
ids de departamento vindos de GET /queue.

Bases de conhecimento

Componente interno observado: nce.

Endpoints:

GET /assistents/{assistantId}/kbs
GET /kb/configs
POST /assistents/{assistantId}/kbs
DELETE /assistents/{assistantId}/kbs/{kbConfigId}
POST /kb/reindex?kbId={kbConfigId}

Para associar:

{ "kbConfigId": 123 }

Estados exibidos para bases associadas:

Pronta para uso
Processando…
Falha no processamento
Sem artigos
Aguardando

No laboratorio validado, nao havia base disponivel: a UI mostrou Nenhuma base disponivel e Nenhuma base associada ainda.

Informacao empresa

Campos salvos no assistente:

Campo UI	Campo API
Nome da empresa	`companyName`
Tipo do seu negocio	`businessType`
Endereco	`address`
Horario de funcionamento	`schedules`

Instrucoes para o assistente

Campo UI	Campo API	Uso
Coleta de informacoes	`questions`	Instrui quais dados coletar do cliente; a UI informa que os dados serao salvos como variaveis.
Informacoes importantes	`services`	Base principal de comportamento, produtos, servicos, politicas e instrucoes.

Regras do campo Informacoes importantes:

minimo observado no codigo: 50 caracteres;
se o limite do plano vier como 999, o teto passa a 10.000 caracteres;
caso contrario, a tela mostra limite infinito;
a UI calcula caracteres e estimativa de tokens.

Endpoint de salvamento identificado no bundle:

PUT /assistents/{id}
Content-Type: application/json

{
  "companyName": "Sagazchat LAB",
  "businessType": "Clinica de estetica",
  "language": "informal",
  "address": "Rua Laboratorio, 123",
  "schedules": "Segunda a sexta, 09:00 as 18:00.",
  "services": "Texto com pelo menos 50 caracteres...",
  "questions": "Colete nome, procedimento de interesse...",
  "departamentId": null
}

Observacao: uma tentativa automatizada de preencher via evaluate nao disparou estado React suficiente para salvar. Para automacao via UI, usar locator.fill(...)/interacao real nos campos ou chamar a API com o payload correto. Nao confiar em setar input.value manualmente.

6. Botao Configurar

O botao Configurar abre um modal global com:

Transcrever audio
texto: a transcricao consome de 100 a 1500 tokens de IA.

Endpoint identificado no bundle:

PUT /setting/translate-audio
Content-Type: application/json

{ "state": true }

Regra de seguranca: nao alternar essa chave sem autorizacao explicita, porque afeta consumo global de tokens da conta.

7. Vincular assistente a canais

O editor do assistente cria/treina o agente. O vinculo com canais (ativar o atendimento via IA) e feito na pagina de Configuracoes > Conexoes, no kebab da linha de cada canal.

7.1 Passo a passo via UI — validado em 2026-05-11

Cenario validado: vincular LAB - Assistente Flowbuilder ao canal WhatsApp exemplo (+55 11 90000-0000), com Boas-vindas marcado.

Acessar https://app.sagazchat.com/connections/unoficial (canais WhatsApp QR). A linha do canal mostra coluna Agente IA com badge desativado ou ativado.
Clicar no kebab ⋮ da linha do canal (ultimo IconButton da row). Menu abre com:
- Desconectar
- Reiniciar instância
- Assistente IA ← clicar aqui
- Copiar token
- Editar
- Excluir
Modal Configurar Assistente IA abre com:
- combobox Selecione o assistente (vazio por padrao);
- secao Ativação com 3 checkboxes (todos desmarcados por padrao):
  - Boas-vindas — IA responde a primeira mensagem do cliente novo;
  - Resposta padrão — IA responde fora do horario / sem atendente disponivel;
  - Conversa finalizada — IA reabre conversa ja encerrada se cliente voltar.
- botoes Cancelar e Aplicar.
Clicar no combobox e escolher o assistente. As opcoes vem da lista de /manager-ia. Exemplo da conta exemplo:
- LAB - Assistente Flowbuilder
- Assistente Exemplo
Marcar somente os checkboxes desejados (cada um e independente).
Clicar em Aplicar.
Esperado em conta com tokens disponiveis: modal fecha + badge na coluna Agente IA muda para ativado.

7.2 Erros observados na UI

Você não tem token para utilizar a IA — toast vermelho no canto superior direito, modal permanece aberto, badge segue desativado. Ocorre quando a conta nao tem saldo de tokens de IA. Pre-requisito: garantir saldo no botao Configurar em /manager-ia (ou plano com tokens incluidos) antes de tentar vincular.
IA used in whatsapp. — o mesmo assistente ja esta vinculado em outro numero/canal. Desvincular do anterior antes.

7.3 Quirks da automacao

O combobox Selecione o assistente e MUI Autocomplete. input.click() via evaluate nao abre o listbox; usar page.mouse.click(x, y) com coordenadas reais.
Os 3 checkboxes da secao Ativação NAO usam <label>. Estrutura real: input[type="checkbox"] dentro de <span class="MuiCheckbox-root"> dentro de <div class="MuiBox-root css-u4p24i"> que contem o texto do label. Para identificar, subir 2 niveis a partir do input e checar innerText.
Ordem fixa observada dos checkboxes: idx=0 Boas-vindas, idx=1 Resposta padrao, idx=2 Conversa finalizada.

7.4 Endpoints (via API)

Endpoints identificados no bundle:

PUT /assistents/config/whatsapp
PUT /assistents/config/waoficial
PUT /assistents/config/instagram
PUT /assistents/config/email
PUT /assistents/config/widget

Payload padrao por canal:

{
  "whatsappId": 1,
  "assistentIaId": 42,
  "assistentFirstContact": false,
  "assistentReopen": false,
  "assistentTimeout": false
}

Mapeamento UI → API dos checkboxes:

Checkbox UI	Campo API
Boas-vindas	`assistentFirstContact`
Resposta padrão	`assistentTimeout`
Conversa finalizada	`assistentReopen`

Mapeamento inferido a partir do nome dos campos no bundle. firstContact casa com “primeira mensagem” (Boas-vindas), timeout casa com “sem resposta no prazo” (Resposta padrao), reopen casa com “conversa reaberta” (Conversa finalizada). Confirmar com payload real quando a conta tiver tokens.

O nome da chave de canal muda conforme canal:

Canal	Chave
WhatsApp QR/API antiga	`whatsappId`
WhatsApp Oficial	`waOficialId`
Instagram	`instagramId`
E-mail	`emailAccountId`
Widget	`widgetId`

7.5 Scripts validados

node scripts/sagaz-conexoes-listar.mjs       # mapeia /connections, /connections/{oficial,unoficial,api}
node scripts/sagaz-conexao-kebab.mjs         # abre kebab + lista opcoes
node scripts/sagaz-vincular-assistente.mjs   # abre modal Configurar Assistente IA (so inspeciona)
node scripts/sagaz-ativar-lab.mjs            # fluxo completo: kebab > Assistente IA > LAB > Boas-vindas > Aplicar

8. Relação com Fluxos de Conversa

No Flowbuilder, o subtipo Assistente IA fica dentro do bloco Acao.

Regra operacional:

Criar o assistente em Criação > Assistentes IA.
Configurar dados/instrucoes/bases.
So depois abrir o Flowbuilder e selecionar esse assistente no bloco Acao > Assistente IA.

Se nenhum assistente existir, o bloco nao tem agente util para selecionar. O laboratorio LAB - Assistente Flowbuilder foi criado exatamente para permitir testes futuros sem tocar no assistente comercial real.

8.1 Atualizações de IA validadas live (v4.24.1)

O editor atual organiza as seções Configurações, Agendamento (agenda e “oferecer sempre”), Etiquetas, Biblioteca de mídias, Bases de conhecimento, Informação empresa e Instruções.

Biblioteca de mídias: o vínculo é feito no editor; consulte o runbook sagazchat-biblioteca-midias. API: GET/PUT /assistents/{id}/library.
Payload do vínculo: { libMediaEnabled, libMediaMode: "on_request"|"proactive", libMediaMaxPerReply: 1..3, categoryIds }.
A IA envia o texto e depois a mídia. Funciona em WhatsApp, WhatsApp Oficial e Instagram; no Instagram, somente imagens e vídeos.
Etiquetas: a IA pode aplicar/remover etiquetas; APIs GET/POST/PUT/DELETE /assistents/{id}/tags, com POST { tagId, instruction }.
Contexto: lê as últimas 20 mensagens e os dados salvos do contato. Não documentar como memória da conversa inteira.
Antes de responder que não sabe, consulta a base de conhecimento e os dados do assistente. Consulte o runbook sagazchat-base-conhecimento.
O bloco Conteúdo do Flow pode usar fonte Biblioteca, reaproveitando mídia sem novo upload.

9. Acoes seguras e perigosas

Acao	Impacto	Regra
Abrir lista	Leitura	Seguro.
Buscar agente	Leitura	Seguro.
Criar agente LAB	Cria registro	Permitido quando nomeado como laboratorio.
Editar `Assistente Exemplo`	Pode afetar atendimento real	Nao fazer sem ordem explicita.
Salvar configuracao do LAB	Afeta so laboratorio	Seguro se conteudo for claramente de teste.
Associar base de conhecimento	Muda respostas do assistente	Fazer so em LAB ou com confirmacao.
Ativar transcricao de audio	Pode consumir tokens globalmente	Nunca alternar sem autorizacao.
Vincular IA a canal	Pode colocar IA em atendimento real	Nunca fazer sem autorizacao.

10. Imagens capturadas

Imagens publicadas na Central:

public/media/nova-ui/assistentes-ia-lista.png
public/media/nova-ui/assistentes-ia-criacao.png
public/media/nova-ui/assistentes-ia-editor.png
public/media/nova-ui/assistentes-ia-configurar.png

Imagens auxiliares:

public/media/nova-ui/assistentes-ia-lista-com-lab.png
public/media/nova-ui/assistentes-ia-opcoes-linguagem.png
public/media/nova-ui/assistentes-ia-opcoes-setor.png
public/media/nova-ui/assistentes-ia-associar-base.png

Vinculacao a canal (secao 7.1):

public/media/nova-ui/conexoes-assistente-ia-lista.png
public/media/nova-ui/conexoes-assistente-ia-menu.png
public/media/nova-ui/conexoes-assistente-ia-dialog.png
public/media/nova-ui/conexoes-assistente-ia-config.png
public/media/nova-ui/conexoes-assistente-ia-sem-token.png

Scripts usados:

node scripts/sagaz-assistentes-ia-inspect.mjs
node scripts/sagaz-assistentes-ia-create-lab.mjs
node scripts/sagaz-assistentes-ia-detail-inspect.mjs
node scripts/sagaz-assistentes-ia-options-inspect.mjs
node scripts/sagaz-fetch-current-assets.mjs index-C6g3yDjv.js

Arquivos de saida:

scripts/_out/assistentes-ia/*.json
scripts/_out/assistentes-ia/*.png
scripts/_out/index-C6g3yDjv.js.txt

Apendice A — Plugar agente IA dentro de fluxo (descoberto 2026-05-25)

Aprendizado de produção, sessão de exemplo (treino de 2 agentes na conta pessoal antes de migrar pra conta do cliente).

Padrão de criação em 2 passos

Validado: POST /assistents aceita payload completo (com businessType, language, services etc), retorna 200, mas grava só o campo name. Os outros vêm null. Pra preencher de verdade:

// 1. registro básico
const { id } = await POST('/assistents', { name: 'Agente X' });

// 2. PUT com payload completo
await PUT(`/assistents/${id}`, {
  name:         'Agente X',
  businessType: 'Loja de Películas',
  language:     'informal',
  address:      'Rua...',
  schedules:    'Seg-Sex 8h-18h',
  services:     '... prompt completo (markdown aceito) ...',
  questions:    '',
});

Cache 3-4s no GET após PUT

GET /assistents ou GET /assistents/{id} logo após o PUT retornam estado anterior. O body da resposta do PUT já tem o estado novo — confiar nele pra validação imediata. Pra GET fresh, esperar ~4s.

Schema do subaction `transfertoAI` (action node do flow builder)

Pra plugar um agente IA dentro de um fluxo, o tipo correto é transfertoAI dentro do actions de um action node. O schema do data NÃO é plano — precisa do objeto assistant aninhado:

// ✓ CORRETO — agente aparece selecionado no card do painel
{
  type: 'transfertoAI',
  data: {
    assistant: { id: 44, name: 'Agente X' },
  },
}

// ✗ ERRADO — backend aceita o POST (200 ok) mas o seletor do painel mostra vazio
{
  type: 'transfertoAI',
  data: { assistentId: 44, assistentName: 'Agente X' },
}

Confirmação via JS bundle do app: const e = t?.assistant ?? t, o = e?.name || e?.label || '' — o renderizador lê data.assistant.{name,id} primeiro, e a UI de seleção valida especificamente esse caminho.

Padrão usado no auto-center-exemplo (2026-05-25)

Estrutura no fim de cada ramo comercial do flow:

[action de coleta com tag + queue + ticket]
   ↓
stopFlow "Tem alguma dúvida ou gostaria de adicionar mais alguma informação sobre o seu projeto?"
   (variável info_adicional, timeout 1h)
   ├ resposta (handle a) → action transfertoAI Agente do ramo
   └ timeout  (handle b) → singleBlock encerramento (humano da fila assume)

Por ramo: Loja → Agente-Loja; Oficina → Agente-Oficina; demais ramos → encerramento sem IA. Cliente que responder qualquer coisa vai pra IA já com a resposta no histórico — atende, esclarece, mantém engajamento até o humano da fila pegar.

Erros 500 esperados em conta nova

GET /users/me e POST /outOfHours retornam 500 enquanto a conta não tem canal WhatsApp conectado. PUT /users/{id} também retorna 500 mas aplica a mudança (validar via GET, não pelo status do PUT). Conectar canal primeiro pra esses endpoints estabilizarem.

Endpoints completos `/assistents`

Método	Rota	Uso
`GET`	`/assistents`	Lista (array, schema completo de cada agente)
`GET`	`/assistents/qtd`	`{ used, limit }` — quota de tokens IA
`GET`	`/assistents/value`	(retornou `null` na conta validada — não usar sem investigar)
`POST`	`/assistents`	Cria registro básico (só com `{ name }` — ignora resto)
`PUT`	`/assistents/{id}`	Preenche config completa do agente
`DELETE`	`/assistents/{id}`	Remove agente
`POST`	`/assistents/{id}/kbs`	Upload de knowledge base (multipart)
`POST`	`/assistents/stop`	Para o agente em um ticket
`PUT`	`/assistents/stop/{ticketId}`	Idem, com ticketId na URL

Nota: endpoint usa typo assistents (sem o a). Não corrigir — é como o backend espera.

Apêndice B — Formatação WhatsApp no prompt do agente (regra durável)

Descoberto 2026-05-26 com os agentes de exemplo do auto center.

WhatsApp NÃO renderiza markdown padrão. Quando o prompt do agente IA usa **texto** (negrito markdown), o cliente recebe os asteriscos LITERAIS na mensagem — vira “olá texto” feio em vez de negrito.

Formatação nativa do WhatsApp

Estilo	Sintaxe	Exemplo
Negrito	`texto` (UM asterisco)	`Importante:`
Itálico	`_texto_`	`_falando baixo_`
Riscado	`~texto~`	`~promoção antiga~`
Monoespaçado	três crases	```código```

Quando criar prompt de agente IA pra Sagazchat (ou qualquer integração WhatsApp)

Adicionar no TOPO do prompt (services do /assistents):

# FORMATAÇÃO WHATSAPP — REGRA OBRIGATÓRIA

WhatsApp NÃO entende markdown. Use a formatação nativa do WhatsApp:

- Negrito: UM asterisco em cada lado → `*texto em negrito*` (NÃO `**texto**`)
- Itálico: UM underline em cada lado → `_texto em itálico_`
- Riscado: UM til em cada lado → `~texto~`
- Monoespaçado: três crases

Erro comum a EVITAR: usar `**` (markdown). No WhatsApp isso aparece literal
como dois asteriscos pro cliente, não vira negrito. SEMPRE um asterisco só.

E redigir os exemplos do prompt já em *sintaxe correta*. Não confiar que a IA vai “traduzir” — ela imita o que você escreve no prompt.

Caso real

Agente-Loja (id 44) e Agente-Oficina (id 45) foram criados com 92 e 105 ocorrências de **bold** markdown nos prompts (eu redigi imitando markdown por hábito). Cliente teste viu os asteriscos. Fix: regex global trocando **X** → *X* + injetar a seção acima no topo.

Scripts da migração: central_de_ajuda/scripts/sagaz-exemplo-agents-fix-whatsapp-bold.mjs + sagaz-exemplo-agents-bold-cleanup.mjs.