Studio
Onde o squad é desenhado: quem conversa, o que ele pode fazer e para onde a conversa vai.
Studio · Construtor para cima
A tela

- Menu lateral — busca de squads, Meus squads, Do workspace (o cadeado indica squad privado) e Novo squad.
- Biblioteca — os blocos para arrastar ao canvas.
- Canvas — os blocos ligados. Zoom e ajuste no canto inferior esquerdo; no inferior direito, o verificador de coerência ("Nada impedindo este squad" ou a lista do que impede).
- Barra do topo — nome, número, Ativo/Inativo, Público/Privado, descrição; desfazer e refazer; Montar com IA; atalhos; tour; Testar; Salvar.
- Painel da direita — as propriedades do bloco selecionado.
O squad nasce desligado. Salvar não liga: ligar é o Ativo/Inativo ao lado do nome. E Ativo não quer dizer funcionando — confira o verificador.
Os blocos
| Bloco | O que faz |
|---|---|
| Agente | Quem conversa. O nome aparece para o cliente; o objetivo decide onde a conversa termina. |
| Tarefa | O passo a passo que o agente segue do início ao fim. Ligue no agente. |
| Roteador | Manda a conversa por caminhos diferentes conforme a opção tocada ou o que a pessoa escreveu. |
| Espera | Se o cliente não responder no prazo, manda a mensagem escrita. |
| Ação no CRM | Grava no HubSpot sem passar pela IA. |
| Coletar dados | Pergunta campos um a um, validando. A IA não participa. |
| Manual | Gatilho: só roda quando alguém aperta Executar. |
| Agendado (Cron) | Gatilho: roda em horário fixo. |
| Webhook / API | Gatilho: mensagem de fora, entregue por outro sistema num endereço nosso. É o que recebe o WhatsApp. |
As ligações

A linha entre dois blocos diz para onde a conversa vai. O bloco diz quando. Essa divisão explica quase tudo o que confunde no canvas: a condição nunca mora na linha, mora no painel do bloco de onde ela sai.
O que liga em quê
| De | Para | O que acontece |
|---|---|---|
| Gatilho | Agente, ou Roteador | Por onde a mensagem entra. |
| Roteador | Agente, Tarefa, Ação no CRM ou Coletar dados | Cada saída tem o seu ponto próprio à direita do bloco. A linha sai do ponto da saída, não do bloco inteiro. |
| Ação no CRM | Agente | Ela atravessa: grava e passa adiante. O agente fica depois dela. |
| Coletar dados | Agente | Também atravessa: pergunta os campos e entrega a conversa ao agente seguinte. |
| Agente | Tarefa | A tarefa fica pendurada no agente. O produto lê a ligação nos dois sentidos, então tanto faz a direção em que você a desenhou. |
| Agente | Outro agente | Só vale se a ferramenta Transferir para outro agente estiver marcada — a linha sozinha não transfere. |
Apontar uma saída do roteador para a tarefa de um agente funciona, e é um jeito natural de desenhar ("manda o financeiro para cá"). O produto descobre de qual agente aquela tarefa é e entrega a conversa a ele.
O que não é ligação
- O balão de ferramenta pendurado no agente é desenhado a partir do que você marcou no painel. Não se liga a nada e não se apaga pelo canvas — para tirá-lo, desmarque a ferramenta.
- A Espera não atende ninguém: ela adia. Uma saída de roteador que termina numa espera continua sendo um caminho que não leva a agente nenhum.
O canvas aceita; o verificador é que reclama
Você consegue ligar quase tudo em quase tudo — e um canvas mal ligado não dá erro. Ele responde com o agente errado, e o único sinal é uma linha de log. Foi o que aconteceu de verdade: a saída "Demais mensagens" ficou sem ligação, e toda mensagem fora das condições foi para o agente errado por semanas.
Por isso as regras moram no verificador de coerência, no canto inferior direito:
| O que ele acusa | Gravidade |
|---|---|
| Roteador sem nenhum caminho | Impede |
| Caminho do roteador que não leva a ninguém | Impede |
| Roteador sem a saída Demais mensagens | Impede |
| Ação no CRM que não leva a nenhum agente | Impede |
| Mais de um roteador no squad | Atenção — só o mais ao alto decide, os outros são ignorados |
| Ação no CRM que não grava nada | Atenção |
| Espera sem mensagem para enviar | Atenção |
Encadear roteadores não é suportado. Com dois no canvas, só o de cima decide. Para dois níveis de triagem, use um roteador com mais saídas.
Roteador

Cada caminho tem um nome, uma ou mais condições (por exemplo Opção do menu tocada é igual a suporte; exigir também soma outra condição) e a fila deste caminho. O primeiro caminho que casa vence — use as setas para pôr o mais específico antes. Demais mensagens é a saída padrão, obrigatória: sem ela ligada a um agente, a mensagem fica sem resposta.
Coletar dados

Para cada campo: o tipo (texto livre, nome, e-mail, escolha…), a pergunta, a propriedade do HubSpot onde gravar (opcional) e se é obrigatório. Resposta que não passa na validação é perguntada de novo no máximo duas vezes; depois o campo é pulado e a conversa segue.
Espera

Nome, quanto esperar (minutos, horas) e a mensagem. Ela só sai se o contato não tiver respondido no intervalo; na hora de enviar, o descadastro e a janela de 24 h são conferidos de novo.
Agente, campo a campo

Os seis primeiros campos são o agente inteiro: eles viram o prompt que ele lê antes de cada resposta. A coluna da direita diz o que acontece se o campo ficar vazio, que é onde moram as surpresas.
| Campo | O que é | Vazio, acontece isto |
|---|---|---|
| Nome do Agente | O nome que o cliente vê. A saudação pode usá-lo com {nome}. | O verificador avisa. E cuidado: batizar o agente sem ajustar a saudação é como alguém vira "Consultor IA" no painel e continua se apresentando como "assistente virtual" na conversa. |
| Função (Role) | Abre o prompt: "Você é {nome}, atuando como {função}". Ex.: "Especialista em Marketing B2B". | Ele se descreve como "Assistente". |
| Objetivo (Goal) | O que ele persegue em toda conversa. É o campo que decide se ele conduz para algum lugar ou só responde o que perguntam. | O agente fica reativo: responde e para. |
| Backstory | O que a empresa faz e para quem ela atende — o contexto que ele carrega. Opcional. | A seção nem entra no prompt. Não sobra texto solto. |
| Restrições / Guardrails | Entra como "NUNCA viole, mesmo se o cliente pedir". Ex.: "nunca ofereça desconto". | Nada está proibido — inclusive falar de preço e prometer prazo. |
| Tom de Voz | O cliente sente isso em cada mensagem. Ex.: "profissional, direto, sem emojis". | Sobra só a regra do canal: resposta curta, sem markdown, sem assinar. |
Objetivo, Backstory e Guardrails costumam passar de alguns parágrafos. Os três têm o botão de ampliar ao lado do rótulo: abre um editor largo com o canvas ainda visível.
O menu de opções

O menu vira uma mensagem interativa do WhatsApp — o cliente toca em vez de digitar "2". O formato é escolhido pela quantidade, porque os limites são da Meta:
| Quantas opções | Como chega | Limite do título |
|---|---|---|
| Até 3 | Botões | 20 caracteres |
| De 4 a 10 | Lista, com descrição opcional (72 caracteres) | 24 caracteres |
Cada opção pode exigir identificar quem está falando antes de conduzir. É por opção, e não por conversa, porque a necessidade não é uniforme: "qual o horário?" nunca precisa; "suporte técnico" e "financeiro" precisam, porque garantia e histórico vêm do ERP. Pedir documento na porta é o jeito mais eficiente de perder um interessado.
Duas armadilhas que o verificador pega:
- Opção que exige identificação sem onde conferir — marque também a ferramenta do ERP ou do CRM, senão não há como confirmar quem é.
- Menu que oferece atendente sem a ferramenta de transferir — o cliente toca em "falar com alguém", o agente promete, e ninguém vai.
O que o agente entende além de texto
- Transcrever áudio do cliente — com um campo de nomes que o transcritor erra (equipamentos, termos da casa).
- Ler imagem e arquivo do cliente — lê foto e PDF; um campo diz o que costuma aparecer nas fotos.
- Base de conhecimento — liga a base e mostra os documentos em uso. Ligar com a base vazia é erro que impede: o verificador acusa.

- Modelo LLM — "Usar padrão do fluxo" ou um modelo específico. Modelo sem chave cadastrada faz o agente parar de responder sem avisar o motivo.
- Ferramentas — o que o agente pode fazer além de escrever. Cada uma está descrita em As ferramentas, uma a uma.

- Servidores MCP — marque o servidor e escolha quais ferramentas liberar ("5 de 24 liberadas"). MCP é o jeito padrão de um sistema de fora oferecer ferramentas ao agente — o seu ERP, por exemplo — sem que a gente escreva uma integração para cada uma.
Tarefa, campo a campo

A tarefa é o passo a passo que o agente segue. Ela fica pendurada no agente pela ligação.
| Campo | O que é |
|---|---|
| Nome da Tarefa | Como ela aparece no canvas e no log da execução. |
| Descrição | O passo a passo em si. Use {chave} para as entradas do squad, declaradas no gatilho. |
| Output Esperado | O formato do que ela entrega — "um markdown com 3 parágrafos", "uma tabela". |
Output Esperado é ignorado no atendimento por WhatsApp, de propósito: conversa não tem entregável, e pedir um faria o agente escrever relatório em vez de conversar. Ele vale nas execuções (Rodar), que é onde existe entrega.
As ferramentas, uma a uma
Ferramenta é uma ação que o agente executa por conta própria: encerrar o atendimento, consultar o ERP, marcar na agenda, mandar um aviso para a equipe. O que ele diz é prompt; o que ele faz é ferramenta.
Ligar uma ferramenta
- Clique no agente no canvas.
- No painel da direita, role até Ferramentas.
- Marque a ferramenta. Um balão dela aparece pendurado no agente, no canvas.
- Se ela precisar de configuração, clique no balão — o painel passa a mostrar só os campos dela.
- Salvar.
Marcar é o que liga. Escrever "consulte o ERP" no objetivo ou na tarefa não dá a ferramenta ao agente: sem a marcação, ele não tem como obedecer, e o que acontece na prática é ele repetir o menu ou transferir. É o erro mais comum do Studio.
A lista é agrupada por categoria e cada ferramenta tem o seu ícone no balão — três planilhas marcadas no mesmo agente viram três balões distinguíveis no canvas, e não três iguais.
As duas que já vêm ligadas
Não aparecem para marcar porque o agente as tem sempre:
| Ferramenta | O que faz | Quando entra |
|---|---|---|
| Registrar contato | Guarda nome, telefone e e-mail que a pessoa disser, acumulando — quem der o nome agora e o telefone três mensagens depois não perde nenhum dos dois. | Sempre. |
| Mostrar menu | Reapresenta as opções do canvas quando a conversa se perde ou a pessoa pede para voltar ao início. | Quando o agente tem menu configurado. |
Atendimento
As ferramentas do agente que fala com o cliente. São as que mais mudam o comportamento do dia a dia.
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Transferir para Atendente Humano | Avisa o cliente, põe a conversa na fila do Inbox com um resumo e para de responder por IA. O agente escolhe entre as filas que o gatilho declara. | Sem ela o agente não consegue transferir: quem pedir atendente ouve que alguém vai atender, e ninguém vai. Declare as filas em Organização do atendimento. |
| Transferir para outro agente | Passa a conversa para outro agente deste squad, que continua o atendimento. Quem recebe lê o histórico; quem transfere sai da conversa. Uma transferência por mensagem, para não entrar em círculo. | Só aparece quando o squad tem mais de um agente. Não serve para pedir opinião — quem recebe assume. |
| Encerrar Atendimento | Manda a despedida e fecha a sessão, tirando-a da fila. | Sem ela, só o operador fecha — e conversa resolvida fica aberta para sempre. |
| Etiquetar Conversa | Classifica com as etiquetas cadastradas no gatilho. O agente escolhe de lista fechada, não inventa. O cliente não vê. | Cadastre as etiquetas em Organização do atendimento. |
| Registrar Descadastro (Opt-out) | Registra "me tira da lista". A partir daí todo disparo proativo para o número é recusado pelo próprio gateway; responder na conversa que o cliente abriu continua valendo. | Recomendada em qualquer agente que fale com o público. |
| Consultar Dados do Cliente | Consulta dados do cliente da conversa por consultas prontas, cadastradas no Studio. O agente não escreve SQL: escolhe entre as configuradas, e o filtro pelo telefone é aplicado pelo sistema. | Cadastre as consultas no balão. É a alternativa segura a Executar Query SQL em agente que fala com o público. |
| Agenda de Compromissos | Lista serviços, consulta horários livres, marca, mostra e cancela. Os horários saem do cruzamento de todos os recursos que o serviço exige com o horário de funcionamento — o agente nunca escolhe data por conta própria. | Cadastre serviços e recursos em Agenda, não no canvas. O cliente é sempre o da conversa. |
| Entregar Holerite | Entrega o holerite ao funcionário da conversa. São duas funções e a ordem importa: confirma a identidade pelo CPF, depois entrega. O destinatário sai da conversa, não da escolha do agente. | Exige o cadastro de pessoas e a folha do mês processada em Folha. |
| Enviar Mensagem no WhatsApp | Manda um aviso no meio do raciocínio, quando o agente vai demorar ("só um instante, estou verificando"). Sai pelo canal em que a pessoa está — WhatsApp ou chat do site, apesar do nome. | Não serve para a resposta normal, que já é entregue sozinha. Marcar sem precisar só dá ao modelo uma forma a mais de falar duas vezes. |
| Avisar no Telegram | Manda aviso para a equipe num grupo: chamar o comercial para um lead quente, o técnico para um equipamento parado. O cliente não vê. | Token do bot em Configurações › Telegram; os destinos são cadastrados no balão e o agente escolhe pelo nome. Não substitui responder ao cliente. |
ERP e CRM
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Consultar ERP Omie | Cadastro, pedidos, títulos em aberto e produtos. Uma ferramenta com cinco funções; as três de dado de cliente exigem identificação antes, e ela só passa se o telefone da conversa estiver no cadastro do Omie. | App Key e App Secret em Configurações › Omie. O agente nunca informa código de cliente: ele sai da sessão. |
| Consultar CRM HubSpot | Cadastro, chamados e negócios do contato desta conversa, localizado pelo telefone. Pode também gravar cadastro e mover estágio. | Token em Configurações › HubSpot. No balão, marque o que ele pode ler (negócios só aparece se marcado) e o que pode gravar — a escrita nasce desligada. Não abre nem fecha chamado. |
Fontes de dados
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Ler Google Sheets | Lê uma planilha compartilhada por link e devolve colunas e prévia. | A planilha precisa estar como "qualquer pessoa com o link pode ver". |
| Buscar Dados de API | GET ou POST numa API REST, com cabeçalhos e corpo JSON, e devolve a resposta resumida. | Bloqueada em agente de WhatsApp (veja abaixo). |
| Ler Arquivo de URL | Baixa CSV ou Excel de uma URL pública e devolve colunas e prévia. | Bloqueada em agente de WhatsApp. |
| Localizar Upload Mais Recente | Aponta o arquivo mais recente que o cliente enviou para a nuvem, para o agente processar em jobs agendados. | O cliente envia pela interface ou pelo connector. Leia o arquivo com Ler Planilha Excel. |
Banco de dados
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Executar Query SQL | Roda um SELECT no banco configurado e devolve tabela. | Configure a conexão no balão. Bloqueada em WhatsApp — use Consultar Dados do Cliente. |
| Listar Tabelas do Banco | Lista as tabelas disponíveis. | Bloqueada em WhatsApp. |
| Descrever Estrutura de Tabela | Colunas, tipos e restrições de uma tabela. | Bloqueada em WhatsApp. |
Planilhas e Power Query
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Ler Planilha Excel | Lê .xlsx ou CSV e devolve o conteúdo como texto. | Envie o arquivo pelo balão, ou receba o caminho de outra ferramenta. |
| Escrever em Planilha Excel | Escreve um valor numa célula. | Arquivo configurado no balão. |
| Adicionar Linha em Planilha Excel | Acrescenta uma linha no fim da planilha. | Arquivo configurado no balão. |
| Localizar Arquivo Excel Mais Recente | Acha o export mais recente numa pasta do servidor, conforme o padrão de nome configurado. | Exige o conector rodando na máquina com a pasta. |
| Atualizar Fontes de Dados Power Query | Localiza o export mais recente, copia para um nome fixo e roda RefreshAll + Save nos dashboards. | Exige Windows com Excel instalado e o conector local. A configuração (pasta, padrão de nome, destinos) fica no balão. |
Web
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Pesquisar na Internet | Busca um tópico e devolve título, trecho e URL. | — |
| Acessar Pagina Web | Abre uma URL e extrai o texto principal. | Bloqueada em WhatsApp. |
Código e análise
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Executar Codigo Python | Roda Python isolado, com tempo limitado. Gera gráficos (chart_builder) e dashboards com cross-filter (dashboard_builder). Tem pandas, numpy e sqlite3. | Bloqueada em WhatsApp. O tempo limite fica no balão. |
| Instalar Pacote Python | Instala um pacote no sandbox (matplotlib, scikit-learn, plotly…). | Bloqueada em WhatsApp. |
| Prever Serie Temporal | Projeta uma série por tendência linear e informa o R² do ajuste. Não modela sazonalidade, e diz isso. | Entrada é JSON de lista de objetos. |
| Detectar Anomalias | Sinaliza outliers por z-score acima do limite (padrão 3,0) e devolve média e desvio. | — |
| Comparar Periodos | Total antes e depois de uma data de corte, com delta absoluto e percentual. | Sem data de corte, usa a mediana das datas. |
| Alerta por Limiar | Compara um valor com um limiar e devolve ALERTA ou OK. | Não envia nada: quem manda o e-mail é o agente, chamando Enviar E-mail depois. |
Entrega
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Enviar E-mail | Manda e-mail por SMTP, com anexos pelo caminho do arquivo. O destinatário é parâmetro — o agente escreve o endereço. | SMTP em Configurações. Bloqueada em WhatsApp, porque o texto do cliente escolheria o destinatário. |
| Avisar a Equipe por E-mail | Avisa a equipe nos endereços cadastrados no balão — o agente escolhe pelo nome do destino, nunca escreve o endereço. | SMTP configurado. É a irmã de Avisar no Telegram: para avisar nos dois canais, marque as duas e peça as duas na tarefa. |
| Gerar Excel | Transforma dados tabulares num .xlsx e devolve o caminho, para anexar. | — |
| Gerar PDF | Monta um relatório em PDF com título e texto e devolve o caminho. | — |
Conteúdo e base
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Consultar Catálogo | Responde preço, modelo, marca e disponibilidade pelas linhas da planilha, e não de cabeça. | Envie o CSV do catálogo no balão. |
| Carregar Perfil da Marca | Traz posicionamento, público, dores, tom de voz e chamadas para ação. Perfil pela metade devolve o que falta, para o agente não inventar. | Preencha o perfil da marca. Chame antes de escrever. |
| Registrar Post Social | Grava o post pronto na fila de Posts, na rede escolhida, como Aguardando — não publica. | Instagram exige o caminho de uma imagem. |
| Salvar Post na Base de Conhecimento | Guarda o post final em markdown na base. | — |
| Carregar Posts Anteriores | Traz posts antigos como referência de estilo e formato. | — |
| Consultar Historico de Temas | Lista os temas já publicados, para não repetir pauta. | — |
| Listar Clientes Disponiveis | Lista os clientes com perfil cadastrado. | — |
| Analisar Performance de Posts | Traz os posts com melhor desempenho, por score de engajamento (comentários×3 + compartilhamentos×2 + curtidas). | — |
Conciliação fiscal
| Ferramenta | O que faz | Antes de marcar |
|---|---|---|
| Conciliacao de NF-e | Executa uma etapa determinística da conciliação de número de série com NF-e: listar notas no Omie, baixar XML, extrair serial, conciliar com o parque instalado, herdar por referência fiscal, diagnosticar lacuna, auditar, gerar relatório. O agente escolhe a etapa e o parâmetro; a lógica de dentro é fixa. | Omie configurado. Nome de etapa errado devolve a lista das válidas. |
O que não é oferecido em agente de WhatsApp
Nove ferramentas somem da lista quando o squad atende WhatsApp, e o servidor recusa mesmo que o canvas insista. São duas famílias: as que deixam o modelo fazer coisa demais, e as que deixam ele contar para fora o que viu.
| Ferramenta | Por que |
|---|---|
| Executar Query SQL | Use Consultar Dados do Cliente: as consultas ficam prontas e o filtro pelo telefone é do sistema. |
| Listar Tabelas do Banco | Expor o schema a quem conversa serve de reconhecimento para um ataque. |
| Descrever Estrutura de Tabela | Mesma razão. |
| Executar Codigo Python | Execução de código arbitrário dirigida por texto de terceiro. |
| Instalar Pacote Python | Instalação de pacote dirigida por texto de terceiro. |
| Buscar Dados de API | A URL, o método e o corpo viriam do texto do cliente — e a conversa sairia junto no POST. |
| Acessar Pagina Web | Buscar um endereço que o cliente ditou é canal de saída, e a página volta para a conversa como se fosse fala dele. |
| Ler Arquivo de URL | Buscar um endereço que o cliente ditou é canal de saída. |
| Enviar E-mail | O destinatário é parâmetro: o texto do cliente escolheria para quem vai. |
Em squad manual ou agendado, onde a entrada vem de quem opera e não de um desconhecido, as nove continuam disponíveis.
Ferramenta do HubSpot

Clique no balão da ferramenta embaixo do agente para configurá-la. O agente localiza a pessoa pelo telefone da conversa. Marque o que ele pode consultar (cadastro, chamados, negócios) e o que pode gravar (criar e completar cadastro, mover estágio, criar lead, abrir chamado em qual funil e etapa). A gravação começa desligada.
O gatilho

Entradas do squad (para squads manuais: campos que se preenchem antes de rodar, usados como {chave} nas tarefas), tipo de gatilho, schema (genérico, WhatsApp, Typeform), equipe vinculada (para onde vai o transbordo quando nenhuma fila se aplica), número do WhatsApp e modelos deste número.

Organização do atendimento: as filas de transbordo que este squad alcança (o agente escolhe só entre elas; o "para quê" de cada uma mora em Filas) e as etiquetas que o agente aplica.

Pesquisa de satisfação: despedida, até 8 perguntas (nota 1–5, NPS 0–10, sim/não ou escrita), qual é a nota do atendimento (estrela), se aparece no painel, agradecimento e por quantas horas a nota é aceita.

Encerrar sem retorno do cliente, Lembrete de véspera, Pesquisa após o compromisso (cada um liga pela caixa do canto) e Alertas do atendimento — destinos de e-mail, WhatsApp ou webhook para avisar quem não está com o Inbox aberto. Por último, a URL do webhook para o painel da Meta.
Testar

- Conversa — converse como um cliente no WhatsApp, com roteador, menu e transbordo.
- Execução — roda as tarefas uma vez e entrega um resultado. É o caminho de relatório e conteúdo.

O simulador usa o canvas salvo. A mensagem passa pelo caminho real (menu, prompt, ferramentas, transbordo), mas a conversa não aparece no Inbox nem conta atendimento. Gravar no CRM de verdade fica desligado por padrão: o painel mostra o que gravaria e nada é enviado.
Montar com IA

Descreva o atendimento em uma frase e a IA monta agentes, menu e caminhos; depois você ajusta conversando. Há exemplos prontos para começar.
Verificador de coerência

Confere o squad enquanto você mexe e diz o que vai falhar na prática: vermelho impede funcionar, amarelo faz funcionar pior. Cada item tem ver no canvas.