Perguntas Frequentes

Para acessar a plataforma, siga as etapas abaixo:

1. Na página inicial, localize e clique no botão 'Entrar'. Este botão está no canto superior direito da tela.

2. Após clicar, será exibida uma tela solicitando seu e-mail e sua senha.

3. Insira seu e-mail cadastrado e sua senha nos campos indicados.

4. Em seguida, clique novamente no botão 'Entrar'.

Você será então redirecionado para a área de testes do seu último agente. Caso ainda não possua nenhum agente criado, a plataforma o levará para a página de criação de agentes.

Sim, você pode entrar diretamente com sua conta Google, sem precisar de senha própria. Siga as etapas abaixo:

1. Na tela "Entrar", localize os botões de login social no topo do cartão: "Google" e "Microsoft".

2. Clique no botão "Google".

3. Você será levado à página do próprio Google para autorizar o acesso. Confirme com a conta desejada.

4. Ao voltar para a plataforma, você já estará autenticado. Se for o seu primeiro acesso, a conta é criada automaticamente a partir dos seus dados do Google.

Observação: o botão do provedor que você usou da última vez fica marcado com um selo "Último", para você lembrar por onde entrou.

Quando o login não é concluído, uma mensagem em destaque aparece no cartão de login explicando o motivo. As mais comuns são:

- "E-mail ou senha inválidos." — as credenciais não conferem. Confira se digitou o e-mail e a senha corretamente e tente de novo.

- "Sua conta ainda não foi confirmada." — falta confirmar o e-mail que você recebeu ao se cadastrar. Abra esse e-mail e clique no link de confirmação antes de entrar.

- "Sua conta foi bloqueada." — o acesso está suspenso. Entre em contato com o suporte para regularizar.

Se você apenas errou a senha, é só corrigir e clicar em "Entrar" novamente.

Você mesmo redefine a senha a partir da tela de login. Siga as etapas abaixo:

1. Na tela "Entrar", clique no link "Esqueceu a senha?", no rodapé do cartão.

2. Informe o e-mail da sua conta e confirme.

3. Você receberá um e-mail com um link para redefinir a senha. Abra esse e-mail e clique no link.

4. Na tela que abrir, crie a nova senha e salve.

Pronto: com a nova senha definida, volte à tela "Entrar" e acesse normalmente.

Criar uma conta começa pela própria tela de login. Siga as etapas abaixo:

1. Na tela "Entrar", clique no link "Ainda não tem conta? Cadastre-se!", no rodapé do cartão.

2. Você será levado ao formulário de cadastro.

3. Preencha os dados solicitados e conclua o cadastro.

Dica: se preferir, você também pode criar a conta na hora usando os botões "Google" ou "Microsoft" no topo da tela de login — nesse caso a conta é criada automaticamente a partir dos seus dados do provedor, sem precisar preencher formulário.

Entrar no time é só um clique — não há formulário a preencher. Siga as etapas:

1. No e-mail "Você foi convidado para um time!", confira os Detalhes do Convite (o nome do time e o seu papel).

2. Clique no botão Aceitar Convite.

3. Você será levado à plataforma:

- Se já tem conta com o e-mail que recebeu o convite, é só fazer login — o convite é aplicado na hora e você cai na página do time.

- Se ainda não tem conta, crie uma rápida usando o mesmo e-mail para o qual o convite foi enviado.

Pronto: você entra no time com o papel definido no convite.

Atenção ao e-mail: o convite é amarrado a um e-mail específico. Se você entrar com um e-mail diferente do que recebeu o convite, ele não é aceito. Nesse caso, entre com o e-mail correto ou peça um novo convite.

Se aparecer "Convite não encontrado ou expirado", o link pode ter sido cortado ao copiar, ou o convite foi cancelado — peça um convite novo a quem administra o time.

Alguns pontos resolvem a maioria dos casos:

1. Confira a caixa de spam / lixo eletrônico. O e-mail vem de prototipeai@prototipeai.com e às vezes cai lá.

2. Confirme o e-mail digitado. Por segurança, a tela mostra a mesma mensagem mesmo que o e-mail não esteja cadastrado — então, se você não recebe nada, pode ter digitado um endereço diferente do usado no cadastro. Tente com o e-mail correto.

3. Aguarde alguns minutos e reenvie a solicitação, caso o e-mail demore.

4. Se ainda assim não chegar, é possível que sua conta tenha sido criada via Google ou Microsoft (login social) — nesse caso, você não tem senha própria; entre pelo botão do provedor na tela de login.

Persistindo, fale com o suporte pela Clarice ou pelo canal de atendimento.

O link de redefinição tem validade limitada por segurança — depois de um tempo, ele deixa de funcionar. Se ao clicar você recebe um aviso de link inválido ou expirado, é só gerar um novo:

1. Vá à tela de login e clique em "Esqueceu a senha?".

2. Informe seu e-mail e envie — você recebe um novo link de recuperação.

3. Abra o link mais recente logo que receber e crie a nova senha.

Dicas ao criar a senha: ela precisa ter no mínimo 6 caracteres, e os dois campos (senha e confirmação) precisam ser idênticos — se estiverem diferentes, a tela avisa e não salva. Use sempre o link mais recente; links antigos deixam de valer quando você pede um novo.

Criar sua conta é rápido e você pode fazer de dois jeitos. Escolha o que preferir:

Opção 1 — com Google ou Microsoft (mais rápido):

1. Na tela de Cadastro, clique no botão Google ou Microsoft, no topo do cartão.

2. Autorize o acesso na janela do próprio provedor.

3. Pronto: sua conta é criada na hora, a partir dos seus dados, sem precisar preencher formulário nem criar senha.

Opção 2 — com e-mail e senha:

1. Na tela de Cadastro, preencha os campos E-mail e Senha.

2. Clique em Continuar. Ao continuar, você concorda com a Política de Privacidade e os Termos de Uso.

3. Você receberá um e-mail de confirmação. Abra-o e clique no link para ativar a conta antes de entrar.

Se você já tem conta, clique em Já tenho conta! para ir direto ao login.

Sim, quando você cria a conta com e-mail e senha. Depois de concluir o cadastro, você recebe um e-mail de confirmação — abra-o e clique no link para ativar a conta antes de entrar.

Se ao tentar logar aparecer "Sua conta ainda não foi confirmada", é justamente esse passo que falta: procure o e-mail de confirmação (verifique também o spam) e clique no link.

Observação: se você se cadastrar pelos botões Google ou Microsoft, não precisa dessa etapa — a conta já entra confirmada pelo próprio provedor.

Essa mensagem significa que já existe uma conta com esse e-mail. Você não precisa criar outra — é só entrar. Como:

1. Vá para a tela de login e tente acessar normalmente com esse e-mail e a sua senha.

2. Não lembra a senha? Use "Esqueceu a senha?" para redefinir.

3. Atenção a um caso comum: se você criou a conta antes pelo Google ou Microsoft, ela não tem senha própria — entre pelo botão do mesmo provedor na tela de login, não pelo formulário de e-mail/senha.

Ou seja, o e-mail já cadastrado quase sempre quer dizer "entre em vez de cadastrar" — escolha o caminho de acesso que você usou da primeira vez.

Para criar seu primeiro agente de IA, siga este procedimento:

1. Na página inicial, observe a caixa de texto principal. Nela, digite a solicitação do que você deseja que o agente automatize. Um exemplo pode ser: 'crie um agente para analisar atestados'. Você pode incluir regras e detalhes específicos nesta descrição inicial.

2. Depois de descrever a função do agente, clique no botão 'Criar agente'.

3. A plataforma apresentará opções para você selecionar o time ao qual o agente pertencerá e para definir um nome para o projeto. Faça essas escolhas e clique em 'Continuar'.

4. Em seguida, valide as regras que a plataforma sugeriu com base na sua descrição. Se estiverem corretas, clique em 'Iniciar Desenvolvimento'.

Com isso, seu agente estará criado e pronto para as próximas etapas de configuração e uso.

Aprenda a iniciar a criação de um novo agente já integrado a sistemas externos. Ao fornecer a documentação da API durante a fase de Discovery, a assistente Esther estrutura o fluxo automaticamente considerando os endpoints e dados necessários.

Passo a passo:

1 - Inicie o Discovery: Comece descrevendo brevemente o fluxo ou o agente que você deseja criar. Isso abrirá automaticamente a sala de Discovery.

2 - Acesse a Conexão de APIs: Dentro da sala de Discovery, localize e clique no botão "Conectar APIs", situado no canto inferior esquerdo da tela.

3 - Selecione a Fonte da API: Você terá duas opções:

- Escolher uma API pronta (já disponível na lista da plataforma).

- Inserir a documentação da API específica que você deseja conectar (copiando e colando o texto técnico ou JSON).

4 - Criação Assistida pela Esther: Após inserir a documentação, uma nova conversa será iniciada com a Esther. Ela irá fazer algumas perguntas e montar o fluxo de agente, para posteriormente processar as informações técnicas e criar o fluxo de agentes já com a integração configurada.

Você chega a esta tela pelo botão Enviar Material para Treino do Agente, na Sala de Discovery. Aqui você entrega o conteúdo que a IA vai usar para entender e construir o seu agente.

Como funciona:

1. Você pode colar um texto diretamente ou subir um arquivo — os dois caminhos funcionam.

2. Tipos de arquivo aceitos: Áudio (MP3, WAV, M4A), PDF, Imagem (PNG, JPG, GIF) e Planilha (CSV, TXT, XLSX, XLSB).

3. Envie. O material é entregue como entrada para a IA da Sala de Discovery, que o analisa e incorpora aos requisitos do agente.

Há a opção processar material automaticamente após envio: se marcada, a análise dispara sozinha ao enviar, sem você precisar acionar um passo extra. Se desmarcada, o material fica registrado e você aciona o processamento quando quiser.

Sim. Você não precisa entender de código nem saber montar a documentação técnica da API — a plataforma te ajuda nas duas frentes.

Como funciona:

1. Na sala de discovery, clique em Conectar APIs (canto inferior esquerdo).

2. Abre o Assistente de Cadastro de API. Se você já tem a documentação, cole no campo "Cole aqui a documentação da API.".

3. Se não tem a documentação ou não sabe como gerá-la, clique em "Precisa de ajuda para gerar documentação?" — a plataforma te orienta a montá-la.

4. Com a documentação inserida, a Esther conversa com você, faz as perguntas necessárias e estrutura o fluxo com a integração já configurada.

Ou seja: a parte técnica fica com a plataforma e com a Esther. Você só precisa saber o que quer que o agente faça.

Depois de conversar com a Esther e reunir os materiais, você aciona a construção pela própria sala de discovery. O que fazer depende de os requisitos estarem completos:

- Requisitos alinhados (completos) — aparece o botão Iniciar Desenvolvimento. Clique nele para a plataforma começar a construir o agente com base no que foi definido.

- Ainda falta alinhar — o destaque é Enviar Material para Treino do Agente (para você complementar os requisitos), e há a opção Iniciar Desenvolvimento com Requisitos Incompletos caso queira seguir mesmo assim.

O painel Requisitos do Agente, à direita, mostra o que já foi capturado. Quando estiver satisfeito, é o Iniciar Desenvolvimento que dá a ordem de construir.

Na sala de discovery, o painel Requisitos do Agente (à direita) reúne o documento que a Esther vai construindo a partir das conversas e dos materiais que você envia. Ali você pode ver e editar o documento diretamente, ajustando o que a IA capturou.

Um detalhe importante: quando você faz um ajuste manual no documento, a plataforma pode rodar uma revisão por IA em seguida, para garantir que tudo ficou coerente. Assim, o documento de requisitos é colaborativo — você e a Esther o refinam juntos até ele representar exatamente o agente que você quer, antes de iniciar o desenvolvimento.

Depende de quão completa está a descrição do que você quer, mas o caminho é rápido e você acompanha cada etapa.

Como funciona:

1. Depois que você descreve o pedido e inicia o projeto, a Esther lê sua descrição na sala de discovery.

2. Se estiver tudo claro, ela já inicia a construção da primeira versão do agente em instantes.

3. Se faltar alguma informação importante, ela te chama para uma conversa por voz para alinhar os pontos em aberto antes de criar.

Ou seja: quanto mais clara e completa for a sua descrição inicial, mais rápido o agente fica pronto. Você não fica no escuro — a tela mostra o que a Esther está fazendo a cada momento.

Iniciar Prototipação manda a plataforma gerar os agentes do seu projeto a partir dos requisitos reunidos na sala de discovery. É o passo que transforma a conversa e os materiais em agentes prontos para testar.

Essa funcionalidade é exclusiva de planos pagos: se o time não tem uma assinatura ativa, ao clicar em Iniciar Prototipação você é levado à tela de assinaturas com o aviso para fazer upgrade.

Depois que os agentes são gerados, eles aparecem nesta tela de protótipos — organizados por situação (por exemplo, Liberado para Testes) — e você pode abrir cada um para testar. Se você ainda não vê nenhum agente aqui, normalmente é porque a prototipação ainda não foi iniciada (ou o time precisa de um plano pago para iniciá-la).

Fique tranquilo: apagar uma sala é uma exclusão suave — ela vai para a lixeira, e o conteúdo não é perdido. Veja como acessá-la:

1. Na lista Minhas Salas de Discovery, role até o rodapé e clique em "Ver Salas de Discovery deletadas".

2. Você chega à tela Salas de Discovery Deletadas, onde cada sala aparece com a marca DELETADA.

3. Clique em Visualizar sala para abrir e consultar o conteúdo dela — inclusive os agentes que já haviam sido criados a partir dela continuam disponíveis.

Observação: essa tela permite visualizar a sala na lixeira, mas não há um botão para reativá-la como sala ativa. Se você precisa que a sala volte a ficar ativa, fale com o suporte pela Clarice (o balão de ajuda no canto inferior direito).

Todas as suas salas de discovery (onde você cria e refina agentes com a Esther) ficam reunidas em um só lugar:

1. Acesse Minhas Salas de Discovery pelo menu.

2. Cada sala aparece como um card, com o nome, o time e uma prévia da descrição. Use Entrar na sala para abri-la ou Ver Agentes para ir direto aos agentes criados nela.

3. Se você tem muitas salas, use a paginação no rodapé (1, 2, 3. Next / Last) para navegar entre elas.

Dica: apagou uma sala e quer encontrá-la? No rodapé da lista há o link "Ver Salas de Discovery deletadas", que mostra as salas que foram para a lixeira.

Você chegou à sala de discovery — é aqui que seu agente ganha forma. A bolinha rosa com um microfone é a Esther, a IA que conversa com você por voz para finalizar os requisitos do agente.

O que fazer agora:

1. Clique na bolinha da Esther (o orb).

2. Abre uma janela de preparação. Se quiser, cole ali um documento, briefing ou anotação para a Esther considerar — ou deixe em branco e siga só na conversa.

3. Autorize o microfone e comece a falar. A Esther vai fazer as perguntas certas para entender o que seu agente precisa fazer.

Quando as informações estiverem completas, a própria plataforma inicia a construção do agente. Você não precisa saber nada técnico — é só conversar.

Falar com a Esther é simples e não precisa instalar nada. Siga as etapas:

1. Dentro da sala de discovery, clique na bolinha rosa com o microfone (o orb da Esther).

2. Na janela que abre, você pode colar um documento ou anotação para ela considerar na conversa (opcional) e escolher o microfone que vai usar.

3. Autorize o uso do microfone quando o navegador pedir.

4. Quando o status mostrar "Ao vivo — fale agora", é só falar naturalmente. A Esther responde por voz e vai conduzindo as perguntas.

Para encerrar, é só fechar a conversa. Tudo o que vocês conversaram fica registrado como material da sala.

Sim. A Esther pode ouvir uma reunião web (Microsoft Teams, Google Meet ou Slack) e participar da conversa junto com você. Ela não entra como um convidado na chamada — em vez disso, ela capta o áudio da aba da reunião no seu navegador.

Como ativar:

1. Clique no orb da Esther, na sala de discovery.

2. Ative o toggle "Incluir Esther em uma reunião web (Teams, Meet ou Slack)".

3. No passo seguinte, selecione a aba ou janela da reunião que a Esther deve escutar.

4. Use sem fone de ouvido — assim o som da reunião sai pelo computador e a Esther consegue captá-lo.

Importante: esse recurso é exclusivo do plano Enterprise. Se ele aparecer bloqueado para você, é porque seu plano atual não o inclui.

Porque o recurso de incluir a Esther em uma reunião web (captar o áudio de uma call do Teams, Meet ou Slack) é exclusivo do plano Enterprise.

No orb da Esther, esse toggle aparece com um selo Enterprise e fica desabilitado enquanto seu time não estiver nesse plano. Ao lado, há um link para fazer upgrade para Enterprise.

Se você precisa dessa funcionalidade, faça o upgrade do plano ou fale com quem administra o time. Todas as outras formas de conversar com a Esther por voz continuam disponíveis normalmente, sem depender do Enterprise.

Você pode entregar esse conteúdo à Esther na hora de iniciar a conversa por voz. Assim ela já entra no assunto conhecendo o seu material.

Como fazer:

1. Clique no orb da Esther, na sala de discovery.

2. Na janela "Preparando a conversa com Esther", use o campo de texto para colar o documento, briefing, e-mail ou anotação que explica seu processo.

3. Inicie a conversa normalmente. A Esther vai considerar esse conteúdo enquanto conversa com você e monta os requisitos do agente.

Dica: se o material for muito longo, cole as partes mais importantes — o que descreve as regras, etapas e exceções do seu processo é o que mais ajuda a Esther a acertar o agente.

Essa notificação aparece quando a Esther identificou que falta alguma informação importante para gerar seu agente com qualidade. Em vez de criar algo incompleto, ela te chama para um alinhamento rápido por voz.

O que fazer:

1. Clique na notificação. Ela te leva direto à sala de discovery do agente e já abre a conversa com a Esther.

2. Responda às perguntas que ela fizer — são justamente os pontos que ficaram em aberto.

3. Assim que os pontos forem esclarecidos, a plataforma segue com a criação do agente.

Ou seja: não é um erro. É a Esther garantindo que o agente nasça alinhado ao que você realmente precisa.

Para gerenciar seus agentes, ou seja, editá-los ou excluí-los, siga as instruções:

1. Na área de testes do agente, observe a barra de navegação superior ou lateral. Você encontrará um ícone de lápis, que indica a função 'editar'. Clique neste ícone, localizado próximo ao menu de seleção de agentes.

2. Ao clicar em 'editar', você poderá alterar o nome do agente ou inseri-lo em subgrupos, conforme necessário.

3. Para excluir um agente, clique no ícone de lixeira, que também estará visível nessa mesma área de gerenciamento.

4. Após clicar no ícone de lixeira, uma caixa de confirmação será exibida. É necessário confirmar sua intenção de excluir o agente nesta etapa.

Sim. Quando você exclui um agente, ele não é apagado de vez — vai para a lixeira e pode ser restaurado. Para recuperá-lo:

1. Na tela Agentes, clique no link Ver deletados, no topo.

2. Localize o agente na lista de excluídos e clique em Restaurar.

3. Confirme no aviso que aparece. O agente volta ao status ativo e reaparece na listagem principal, junto com suas conversas e requisitos.

Só quem tem permissão de gestão no projeto consegue restaurar. Se o agente que você procura não estiver na lista de deletados, fale com o suporte pela Clarice.

Para alternar entre os agentes que você já criou, utilize o menu de seleção:

1. Na área de testes da plataforma, localize o menu de seleção (também conhecido como dropdown).

2. Este menu está localizado no topo da página e exibe uma lista de todos os agentes que você tem disponíveis.

3. Basta clicar e selecionar o nome do agente para o qual você deseja alternar. A plataforma carregará automaticamente a área de testes correspondente ao agente escolhido.

Na área de **Testes** de um agente conversacional:

1. Clique em **Ferramentas do Agente**
2. Selecione o card **Conectar Fluxos e Ferramentas**
3. Selecione o **fluxo de origem**

A partir daí, você tem dois caminhos:

**Opção 1 - Automático:**
- Deixe a plataforma definir o nome da ferramenta automaticamente a partir do fluxo
- O sistema insere o trecho necessário no prompt automaticamente

**Opção 2 - Manual:**
- Insira um nome customizado para a ferramenta
- Adicione as instruções no prompt manualmente na localização de sua escolha

---

**Enviar resultado em link:**

Você também pode escolher se quer enviar o resultado em um link - sendo possível gerar links para **documentos** e **planilhas**.

Ao selecionar uma dessas opções, a plataforma já cria automaticamente a configuração para gerar o link e produzir a resposta personalizada a partir dele.

Sim! Ao excluir um agente, ele não some de vez — vai para a lixeira e pode ser restaurado. Siga as etapas:

1. Na tela Agentes, clique no link Ver deletados, no topo.

2. Você chega à tela Agentes Excluídos. Localize o agente que quer recuperar.

3. Clique em Restaurar no card do agente.

4. Confirme no aviso que aparece.

O agente volta ao status ativo e reaparece na listagem principal, junto com suas conversas e requisitos. Só quem tem permissão de gestão no projeto consegue restaurar — se você não vê o botão, peça a alguém com esse acesso no time.

O nome de um fluxo é alterado na tela de edição do fluxo. Siga as etapas:

1. Na tela Fluxos de Agentes, localize o card do fluxo que você quer renomear.

2. Clique no ícone de lápis (Editar Fluxo) no card.

3. Na tela Editar Fluxo de Agentes, altere o campo Nome do Fluxo.

4. Salve as alterações.

Atenção: o Nome do Fluxo é o nome amigável, que você pode mudar à vontade. Ele é diferente do Código do Fluxo — este é o identificador técnico (só letras, números e underlines, único no time) usado em integrações; mude o código apenas se souber o impacto.

O time responsável por um agente/fluxo é definido na edição dele — é assim que você "transfere" para outro time. Siga as etapas:

1. Abra o fluxo em Editar Fluxo de Agentes (pelo ícone de lápis no card do fluxo).

2. No campo Time Responsável, selecione o time para o qual quer mover o agente/fluxo.

3. Salve.

O agente passa a pertencer ao time escolhido, respeitando as permissões daquele time. Você só consegue atribuir a times dos quais faz parte.

Todos os seus agentes ficam reunidos na tela Agentes (a sua listagem de projetos). Nela você tem:

1. Os agentes organizados por situação — por exemplo, Fluxos em Produção e Conversacionais em Produção — cada um como um card com o nome, o ID e o time.

2. Em cada card, os botões Editar e Abrir para ir direto ao agente.

3. Quando uma seção tem muitos agentes, aparece o link Ver todos para expandir.

Ali no topo você também encontra o filtro por time, a busca e o botão Criar Agente. Para ver agentes que foram apagados, use o link Ver deletados.

Você pode buscar tanto pelo nome quanto pelo conteúdo do agente (o que está escrito nas instruções dele). Há duas formas:

Busca rápida (barra do topo):

1. Clique em Buscar Agentes e Fluxos, no topo da tela.

2. Digite o termo. Você pode filtrar por tipo — Conversacionais, Analíticos, Fluxos, Prompts Globais e APIs — e por time.

3. Os resultados vêm ordenados por relevância: primeiro os que batem no nome, depois os que batem no conteúdo das instruções.

Busca na tela de Agentes:

Na listagem, use o campo Buscar Agente para procurar pelo nome, ou Buscar conteúdo do agente para procurar por algo escrito dentro do prompt dele. Assim você encontra um agente antigo mesmo sem lembrar o nome exato — basta lembrar de algo que ele faz.

Na tela Agentes, seus agentes ficam agrupados por situação, e cada card tem um badge de status com a cor correspondente:

- Produção (badge verde) — o agente está publicado/em uso real.

- Em teste (badge azul) — está sendo testado.

- Pronto para testar (badge laranja) — foi liberado para testes e aguarda validação.

Agentes sem badge estão em desenvolvimento. As seções só aparecem quando têm pelo menos um agente — por isso você pode não ver todas de uma vez. Quando uma seção tem muitos agentes, surge o link Ver todos para expandir e navegar por ela.

Um card também pode ter o selo verde "Fluxo: [nome]", indicando que o agente faz parte de um fluxo — clicar nele abre o fluxo.

Quem pode ver e mexer nos agentes depende do papel de cada pessoa no time e das permissões que esse papel recebeu. Você define isso na tela Permissões de Projetos, nas configurações do time.

Existem quatro tipos de permissão que você liga ou desliga para cada papel (Owner, Admin, Member e Auditor):

- View — visualizar os projetos e seus detalhes.

- Edit — editar os projetos (conteúdo, descrição etc.).

- Manage — gerenciar membros e configurações do projeto.

- Delete — excluir projetos.

Assim, por exemplo, você pode deixar um papel apenas com View (só vê, não altera) e reservar Edit, Manage e Delete para quem realmente administra os agentes. Cada permissão é um botão liga/desliga por papel — basta ativar as que aquele papel deve ter.

O nome de um agente conversacional é alterado na tela de edição dele. Siga as etapas:

1. Abra o agente na Área de Testes.

2. No topo direito, ao lado do seletor de agentes, clique no ícone de lápis (Editar).

3. Na tela de edição, altere o campo do nome do agente.

4. Clique em Salvar.

Pronto: o novo nome passa a aparecer em todos os lugares onde o agente é listado.

Excluir um agente conversacional é feito na tela de edição dele. Siga as etapas:

1. Abra o agente na Área de Testes e clique no ícone de lápis (Editar), no topo direito.

2. Role a tela de edição até o final.

3. Clique no ícone de lixeira, ao lado do botão Salvar.

4. Confirme a exclusão no aviso que aparece.

Fique tranquilo: o agente não é apagado de vez — ele vai para a lixeira e pode ser restaurado depois pelo link Ver deletados, na tela de Agentes.

As instruções (ou prompt) que definem o comportamento de um agente podem ser visualizadas e alteradas na seguinte seção:

1. Dentro da área de testes de um agente específico, procure e clique na aba intitulada 'Instruções'.

2. Nesta aba, você encontrará o prompt completo que governa as ações do agente.

3. Para realizar modificações, clique no botão 'Editar'. Após fazer as alterações desejadas, lembre-se de salvar para que as novas instruções sejam aplicadas.

Sim, é possível restaurar uma versão anterior de um agente. Siga os passos:

1. Na aba 'Instruções' de um agente, localize e clique no ícone de relógio. Este ícone representa o histórico de versionamento do agente.

2. Ao clicar, será exibido um histórico com todas as versões anteriores do agente.

3. Você pode visualizar cada versão para identificar o estado desejado.

4. Para reverter o agente a uma versão específica, clique no botão 'Restaurar' ao lado da versão escolhida. Isso é útil caso uma alteração recente não tenha produzido o comportamento esperado.

Sim. O histórico de versões permite comparar versões e ver as diferenças destacadas, no estilo de um "diff" (como no GitHub): o que foi adicionado e o que foi removido aparece realçado, lado a lado ou em linha.

Isso é útil para entender o que uma alteração realmente mudou antes de decidir Restaurar uma versão anterior — restaurar faz o agente/prompt voltar exatamente àquele estado. Cada versão também mostra quando foi criada e por quem, e mudanças salvas juntas podem aparecer agrupadas como uma única versão.

Cada agente de um fluxo tem suas próprias instruções, acessadas a partir do passo dele. Siga as etapas:

1. Abra o fluxo (na tela de montagem, os passos aparecem em ordem, um por agente).

2. No passo do agente que você quer ajustar, clique em Instruções.

3. Você chega à tela Inteligência do Agente, com o prompt completo daquele agente. Clique em Editar para alterar e salve.

4. Ali também há os botões Versões (histórico, para voltar a uma versão anterior) e Copiar.

Dica: se preferir não editar o texto na mão, peça o ajuste à Clarice (o balão de ajuda no canto inferior direito) — ela mexe no prompt do agente por você.

Sim, sem problema. Toda alteração no prompt do agente fica guardada no histórico de versões, então dá para voltar ao estado anterior. Siga as etapas:

1. Na aba Instruções do agente, clique no botão Versões (ícone de relógio).

2. No histórico, localize a versão que estava boa — cada versão mostra quando foi alterada e por quem.

3. Clique em Restaurar ao lado dela.

Pronto: o agente volta exatamente àquele estado. Nada é perdido no caminho — mesmo depois de restaurar, as versões anteriores continuam no histórico, então você pode ir e voltar quantas vezes precisar.

As instruções (o prompt) de um agente conversacional ficam na aba Instruções dele. Siga as etapas:

1. Se ainda não estiver no agente, use a busca Buscar Agentes e Fluxos no topo, encontre o agente conversacional e clique em Editar/Abrir.

2. Na tela do agente, clique na aba Instruções. Ali aparece o texto completo que governa o comportamento do agente, sob o título Inteligência do Agente.

3. Para alterar, clique em Editar, faça as mudanças e salve. Você também tem os botões Copiar (copia o prompt) e Versões (histórico, para voltar a uma versão anterior).

Dica: se você não quiser mexer no texto na mão, pode pedir à Clarice (o balão de ajuda no canto inferior direito) para ajustar o comportamento do agente por você.

Você não precisa mexer no texto do prompt na mão — é só pedir para a Clarice, a copilota da plataforma. Ela ajusta o prompt e as configurações do agente por você.

Como fazer:

1. Em qualquer tela do agente, clique no balão de ajuda (o círculo escuro com 💬 no canto inferior direito) para abrir a Clarice.

2. Descreva em palavras simples o que você quer mudar — por exemplo: "faça o agente responder de forma mais curta" ou "acrescente uma regra para sempre pedir o CPF antes de continuar".

3. A Clarice aplica o ajuste no prompt/configuração do agente. Você pode conversar por texto (campo "Peça um ajuste à Clarice.") ou por voz (Toque para conversar).

Assim você evolui o comportamento do agente conversando, sem reescrever tudo. E, se algo não ficar como esperado, dá para voltar a uma versão anterior do prompt pelo histórico de Versões na aba Instruções.

É importante compreender a distinção entre a área de testes e a área de ajustes para o uso correto da plataforma:

* A área de testes é onde se encontra a caixa de texto principal no centro da tela, identificada como 'Digite aqui seu input'. Esta área é destinada ao envio dos dados reais que o agente deve processar, sejam eles áudios, textos ou imagens.

* A área de ajustes é a área de chat localizada na lateral direita da tela. Esta área é para interagir com o agente e solicitar modificações em seu comportamento ou regras, como por exemplo: 'Insira uma nova regra para.'.

Não utilize a área de ajustes para enviar os dados de trabalho que o agente deve processar; para isso, use sempre a caixa de texto principal na área de testes.

Para testar um agente conversacional, clique no ícone de robô chamado "Área de Testes" e selecione o nome do agente específico no menu superior direito. Na área de testes de agentes conversacionais, você pode enviar mensagens de texto, áudios, imagens e documentos PDF. Cada conversa completa fica salva e pode ser avaliada em conjunto. Se você desejar avaliar conversas separadamente, utilize o botão "Reiniciar" sempre que quiser iniciar uma conversa do zero. Isso mantém suas conversas separadas e organizadas no histórico de testes.

Para testar um agente analítico, clique no ícone de robô chamado "Área de Testes" e selecione o nome do agente específico que você deseja testar no menu superior direito. Na aba "Enviar", você pode enviar diversos tipos de input: documentos em PDF, imagens, áudios, texto livre no campo de mensagem, ou planilhas com dados estruturados. Caso você envie algum documento, imagem ou áudio, haverá um tempo de processamento inicial enquanto o agente faz a leitura do conteúdo. Após finalizar a extração da informação, o campo de texto livre será automaticamente preenchido com o conteúdo extraído do material enviado. Clique no ícone "Enviar Mensagem" para dar início ao trabalho de análise do agente.

Na lateral direita da Área de Testes, você encontrará o histórico de execuções com cada envio registrado. Quando o agente concluir a análise, aparecerá o link "Ver Resultados" e um ícone de Download. Você pode fazer download em diversos formatos: xlsx, docx, txt, html, de acordo com o tipo de resposta do agente. Ao clicar em "Ver Resultados", você será direcionado para a aba Resultados, onde verá o material inicial enviado na coluna esquerda e a resposta produzida pelo agente na coluna direita. Para materiais visuais como slides, haverá a opção "Abrir em Nova Aba" para visualização ampliada.

Na Área de Testes, é possível avaliar cada resposta produzida pelo agente. O feedback é fundamental para o treinamento e melhoria do desempenho do agente. Na aba "Resultados", você deve avaliar a resposta do agente:

* Aprovar: Se não houver considerações negativas, clique em "Aprovar" para que a métrica seja computada automaticamente.

* Reprovar: Se clicar em "Reprovar", o campo "Comentário de Feedback" será acionado. É necessário escrever um feedback detalhado antes de confirmar a reprovação. Quanto mais específico for seu feedback, mais eficiente será o treinamento do agente.

Explique em suas próprias palavras por que a resposta não foi adequada: mencione itens que faltaram, erros cometidos, ou qualquer aspecto que impediu sua satisfação plena com a resposta.

Existem dois modos de processamento de feedback:

Modo Automático: Quando configurado, o feedback será imediatamente incorporado após você salvá-lo. A plataforma entrará automaticamente em modo de treino do agente a partir do seu feedback.

Modo Manual: Neste modo, a plataforma não processa o feedback imediatamente. É necessário que um humano entre no feedback registrado na aba "Feedbacks", avalie se ele será incorporado e clique no botão "Corrigir com IA" para iniciar o treinamento. Isso permite manter controle sobre quais feedbacks são realmente relevantes e precisam ser incorporados, sendo especialmente útil quando múltiplos usuários estão fornecendo feedbacks no projeto.

Para compartilhar seu projeto e permitir que outros usuários testem e forneçam feedbacks:

1. Clique no botão "Compartilhar"
2. Insira o usuário que deseja adicionar
3. Selecione o papel de "Auditor"

O usuário com papel de auditor poderá enviar testes e dar feedbacks de forma livre. Se você quiser revisar os feedbacks antes de incorporá-los, mantenha seu projeto em modo de feedback manual. Assim, você terá tempo para verificar cada feedback e decidir se irá incorporá-lo posteriormente.

A tela de Métricas do fluxo te dá esse termômetro. O indicador principal é a Taxa de Aprovação: o percentual de feedbacks marcados como aprovados sobre o total avaliado. Quanto maior, melhor a qualidade percebida dos resultados do fluxo.

A tela mostra os números por casos — cada caso é uma unidade de análise gerada pelo fluxo, que pode receber feedback. Você pode filtrar por intervalo de datas e por release (versão) para comparar a qualidade antes e depois de uma mudança. Ali também há a lista de agentes do fluxo na ordem de execução, ajudando a localizar onde está o problema quando a taxa cai.

Dica: acompanhe a Taxa de Aprovação depois de cada ajuste — se ela subir, a mudança foi boa; se cair, vale reverter.

A Taxa de Dissenso é o percentual de casos, avaliados por mais de um usuário, em que pelo menos dois avaliadores chegaram a resultados diferentes (um aprovou, outro reprovou, por exemplo).

Ela mede onde há divergência de julgamento entre os membros do time. Uma taxa de dissenso alta é um sinal de que os critérios de avaliação não estão claros ou de que aqueles casos são ambíguos — vale alinhar com o time o que conta como resposta "boa" para aquele agente, para os feedbacks ficarem consistentes.

Para ter essa segurança, use os testes automatizados (Plano de Testes) do fluxo. Eles guardam casos de referência e comparam o resultado atual com o esperado, mostrando o que Passou e o que Falhou. É a proteção contra regressão — garante que uma mudança de prompt, modelo ou configuração não quebrou o que já funcionava.

Como usar:

1. Na tela do fluxo, abra Plano de Testes.

2. Monte um plano com os casos que representam o comportamento correto — você pode inserir execuções de referência (os casos "padrão-ouro" e os problemáticos) a partir do relatório de execução, ou montar no formulário de novo plano.

3. Sempre que mexer no fluxo, clique em Executar. O fluxo roda de novo para cada caso e a IA compara com o esperado, marcando Passou/Falhou caso a caso.

Quando rodar: depois de qualquer mudança (prompt, modelo, condições, memória) e antes de liberar para produção. Cada rodada consome créditos como execuções normais, então o custo cresce com o número de casos do plano.

Não, rodar um plano de teste não afeta suas execuções reais. Ao clicar em Executar, a plataforma cria execuções novas de teste para cada caso do plano; as execuções originais de referência ficam intactas. (Só lembre que cada rodada consome créditos como execuções normais, proporcional ao número de casos.)

Quando um caso falha (o resultado desviou do esperado), você tem a coluna Orientação, com o diagnóstico da IA sobre o que mudou, e pode:

- Clicar em Corrigir na linha do caso, ou

- Marcar vários casos e usar Solicitar correção em lote.

Nos dois caminhos, a IA de correção analisa a falha e ajusta o agente. Depois, rode o plano de novo para confirmar que os casos voltaram a passar.

São formas de disponibilizar o agente, e ficam no botão Publicar, no topo direito da tela do agente.

Liberar para Testes: muda o status do agente para "Pronto para testar" e (se você quiser) avisa os membros do time por e-mail. É o passo para chamar outras pessoas a testarem e darem feedback, antes de colocar o agente pra valer.

Colocar em produção (uso real): aqui não existe um único botão "produção" — colocar o agente para funcionar de verdade é escolher por onde ele vai atender, no mesmo menu Publicar:

- Publicar Web — página própria do agente para compartilhar por link.

- Embedar (iframe) — colocar o agente dentro do seu site.

- Publicar por API — integrar o agente ao seu sistema.

- Publicar no WhatsApp — conectar o agente a um número de WhatsApp.

Resumo: Liberar para Testes abre o agente para o time validar; a "produção" acontece ao publicar por um desses canais.

São os dois tipos de caso de referência que você coloca no plano de teste — cada um serve para uma proteção diferente:

- Gold standard (padrão-ouro) — um caso que saiu exatamente como deveria. Ele vira a referência do "resultado certo": nos testes, o agente é conferido para garantir que continua entregando aquele nível.

- Problema (problemático) — um caso que deu errado no passado. Ele entra no plano para garantir que aquele erro não volte a acontecer depois de futuras mudanças.

Como montar: na tela de criação, você escolhe quais conversas/execuções entram no plano (dá para filtrar só as que têm feedback) e marca cada uma como gold standard ou problema. Ao clicar em Criar Teste, o plano é montado com esses casos, e cada rodada compara o comportamento atual do agente com o esperado deles.

Você convida a pessoa com o papel de Auditor — ela consegue testar e dar feedback, mas não altera o prompt nem as configurações do agente. Siga as etapas:

1. Na tela do agente, abra a aba Compartilhar.

2. Informe o usuário que deseja adicionar.

3. Selecione o papel Auditor e confirme.

Pronto: o auditor pode enviar testes e registrar feedbacks livremente, sem risco de mexer na configuração do agente. Se você quiser conferir cada feedback antes de aplicá-lo, deixe o projeto em modo de feedback manual — assim você revisa e decide o que incorporar.

Todas as conversas que você fez com o agente ficam guardadas e você pode retomá-las. Siga as etapas:

1. Na Área de Testes do agente, abra a aba Exportar Histórico.

2. Você verá a lista Todas as conversas, com data, quantidade de mensagens e feedbacks de cada uma.

3. Na conversa que quer retomar, clique em Continuar — a conversa reabre no ponto onde parou, com todo o histórico.

Nessa mesma lista você também pode Avaliar ou Exportar cada conversa individualmente. Para baixar tudo de uma vez, use Exportar todas as conversas do projeto (CSV).

Um fluxo (vários agentes em sequência) é testado a partir da tela de montagem do fluxo. Siga as etapas:

1. Abra o fluxo — use a busca Buscar Agentes e Fluxos no topo, encontre o fluxo e clique em Abrir.

2. Na tela de montagem, clique em Testar Fluxo. Você envia o input inicial e acompanha o fluxo rodando passo a passo, do primeiro ao último agente.

3. Para testar um agente isolado do fluxo, cada passo tem o link Testar Agente.

Dica: para validar em lote (vários casos de uma vez) ou garantir que o fluxo continua acertando o que já acertava, use o Plano de Testes / testes automatizados do fluxo.

Sim. Na área de testes conversacional, você pode recomeçar a conversa a partir de uma mensagem específica, mantendo tudo o que veio antes dela e refazendo só dali em diante. É útil para testar uma variação de resposta sem começar do zero.

Como fazer:

1. Na conversa de teste, passe o mouse sobre a mensagem a partir da qual quer refazer.

2. Clique em Recomeçar a partir daqui (ou Testar novamente a partir daqui).

3. Confirme no aviso "Testar novamente a partir daqui?".

O agente descarta as respostas dali para frente e gera de novo a partir daquele ponto, preservando o histórico anterior. Se quiser, em vez disso, começar uma conversa totalmente nova, use Reiniciar conversa.

Use os Testes Automatizados do agente para validar o comportamento em lote e garantir que uma mudança não quebrou o que já funcionava. Siga as etapas:

1. Na Área de Testes do agente, abra a aba Testes Automatizados.

2. Clique em + Montar Teste e monte um plano com as conversas/casos que representam o comportamento correto do agente.

3. Sempre que mexer no agente (prompt, modelo, configurações), clique em Executar. O plano roda as conversas e mostra, caso a caso, o que Passou e o que Falhou.

Assim você compara o comportamento atual com o esperado e detecta regressões antes de liberar o agente. Cada rodada consome créditos como conversas normais, proporcional ao número de casos do plano.

Sim, o agente aceita áudio como input. Ele faz a transcrição automática do áudio e insere o texto transcrito na caixa de texto. Após o upload do áudio, basta clicar em enviar para que o agente processe o input.

Sim, o agente aceita imagens como input. Você pode fazer o upload clicando no ícone de imagem. Se a imagem contiver texto, o agente fará a extração automática e colocará o texto na caixa de texto. Se a imagem não contiver texto, o agente fará uma descrição detalhada da imagem e transformará essa descrição em texto.

Sim, o agente aceita PDF como input. Você pode fazer o upload clicando no ícone de arquivo. Se o PDF contiver texto, o agente fará a extração automática e colocará o texto na caixa de texto. Se o PDF não contiver texto, o agente fará uma descrição detalhada da imagem e transformará essa descrição em texto.

Passo a passo de como permitir ou bloquear o envio de áudios, imagens e arquivos no chat:

1 - Acesse a área de testes do agente.
2 - No canto superior direito da tela, clique no botão Editar (ícone de lápis).
3 - Você será direcionado para a página de edição do agente.
4 - Role a página até encontrar a seção Anexos do Chat.
5 - Selecione as opções de anexos que deseja habilitar ou desabilitar, como:
- Áudios
- Imagens
- Arquivos
6 - Após realizar as alterações, clique em Salvar para que as configurações sejam aplicadas.

Importante: As alterações só entrarão em vigor após salvar as configurações do agente.

Sim. No fluxo você define um modo de processamento de CSV recomendado, que já vem pré-selecionado quando alguém envia uma planilha para aquele fluxo — evita que o usuário tenha que escolher toda vez. Siga as etapas:

1. Abra o fluxo em Editar Fluxo de Agentes (pelo ícone de lápis no card do fluxo).

2. Localize o campo Modo de processamento de CSV recomendado.

3. Escolha o modo padrão para esse fluxo:

- Processar todo o conteúdo — a planilha inteira como um único input.

- Processar linha a linha — cada linha vira um caso independente.

- Agrupar por ID de uma coluna — junta as linhas com o mesmo ID e processa em conjunto.

4. Salve o fluxo.

A partir daí, quando alguém subir um CSV nesse fluxo, o modo escolhido já vem selecionado automaticamente. Se você deixar em Não definido, a plataforma pergunta o modo a cada envio.

É só enviar a planilha para o agente analítico — ele processa os casos em lote, sem você precisar rodar um por um. Siga as etapas:

1. Na tela de execução do agente, escolha o card Planilha (formatos aceitos: CSV, XLSX, TXT) e envie o arquivo.

2. A plataforma pergunta "Como deseja processar a planilha?". Para tratar cada caso separadamente, escolha Processar linha a linha — assim cada linha vira um caso independente.

3. Clique em Enviar.

Cada linha é processada como uma execução, e os resultados vão aparecendo no Histórico de Execuções, onde você acompanha o andamento e abre cada resultado. Os outros modos são Processar todo o conteúdo (a planilha inteira como um único input) e Agrupar por ID de uma coluna (junta as linhas que compartilham o mesmo ID).

Sim. Ao enviar uma planilha para o agente, um dos modos de processamento é justamente Agrupar por ID de uma coluna — ele junta todas as linhas que têm o mesmo valor numa coluna de identificação e processa esse conjunto como um único caso.

Como usar:

1. Envie a planilha pelo card Planilha na tela de execução do agente.

2. Na pergunta "Como deseja processar a planilha?", escolha Agrupar por ID de uma coluna.

3. Indique a coluna que serve de identificador e clique em Enviar.

É o modo ideal quando várias linhas pertencem à mesma entidade (por exemplo, vários registros do mesmo cliente) e você quer que o agente analise tudo junto, em vez de linha a linha. Os outros modos disponíveis são Processar todo o conteúdo e Processar linha a linha.

Sim. Todo agente construído na plataforma possui automaticamente uma API dedicada pronta para ser consumida por sistemas externos.

Como obter o acesso:

1 - Acesse o Fluxo: Vá até o editor do fluxo de agentes o qual você deseja utilizar a api.

2 - Menu Publicar: Clique no botão "Publicar" e selecione a opção "Publicar via API".

3 - Painel de Integração: Nesta tela, você terá acesso a todos os dados necessários para a requisição:

- URL do Agente: O endereço (endpoint) para onde você enviará os dados.

- Chaves de API: Área para gerar e copiar o Token de autenticação seguro.

- Formatos Aceitos: Documentação técnica explicando como enviar diferentes tipos de input (JSON, Imagem, Áudio, etc.).

Resumo: Basta gerar a chave de acesso e utilizar a URL fornecida para enviar o input inicial (dados de entrada). Isso acionará o fluxo do agente remotamente, permitindo a integração com qualquer software ou automação.

Sim ele pode, esta funcionalidade permite que a resposta gerada pelo agente da PrototipeAI seja enviada automaticamente para um sistema externo (como Zoho, Salesforce, entre outros sistemas) através de uma requisição API.

Passo a passo de configuração:

1 - Acesse as Configurações do passo do fluxo: No menu principal, vá até a aba de Configurações.

2 - Envio de Resposta: Localize a seção "Envio de resposta do agente" na parte inferior da tela.

3 - Criar Novo Destino: Clique para adicionar uma nova integração. Você precisará preencher os seguintes campos:

- Nome do Destino: Identificação interna (ex: Integração Zoho Recruit).

- URL da API: O endpoint do sistema externo que receberá os dados.

- Autenticação: Defina o método necessário (ex: Bearer Token, API Key).

- Método HTTP: Geralmente POST ou PUT.

- Caminho da API: O path específico da rota, se houver.

- Variáveis de Rota: Caso a API exija variáveis dinâmicas na URL.

4 - Configuração do Template (O passo mais importante):

Nesta etapa, você estruturará o corpo da requisição (Body).

Você deve montar o JSON exatamente no formato que o sistema externo espera receber.

Utilize a variável da resposta do agente anterior para preencher o conteúdo dinamicamente.

5 - Customização e Salvamento:

Configure cabeçalhos (headers) ou JSONs customizados se necessário.

6 - Clique em Salvar Alterações.

A partir de agora, assim que o agente gerar a análise, o sistema fará o envio (disparo) dessa resposta formatada diretamente para a plataforma conectada.

Sim, você pode cadastrar uma API para que o agente consulte dados durante a execução. Se a API for protegida, é necessário cadastrar o token de autenticação. Isso é feito através de um formulário na interface do sistema, sem necessidade de escrever código.

Para cadastrar uma API no agente, você precisa de alguns dados que vêm do sistema externo que será consultado — não da prototipe.ai. Normalmente são:

- URL / endpoint — o endereço da API que o agente vai chamar.

- Método HTTP — geralmente GET (consultar) ou POST (enviar).

- Autenticação — se a API é protegida, o token ou a chave de acesso (ex.: Bearer Token, API Key).

- Parâmetros / caminho — o que a API exige na chamada.

Onde achar: esses dados ficam na documentação da API do sistema externo ou no painel de desenvolvedor dele (é lá que se gera o token de acesso). Com eles em mãos, você preenche o formulário de integração na plataforma — sem escrever código. Se você tem a documentação da API mas não sabe interpretá-la, a Esther pode ajudar a montar a integração a partir dela na sala de discovery.

As chaves de API do time ficam em Configurações do time → Chaves API. Para criar uma:

1. Abra Chaves API e inicie a criação de uma nova chave.

2. Defina a Expiração (por quanto tempo a chave vale).

3. Escolha as Permissões da chave — o que ela poderá fazer.

4. Defina o escopo: acesso total ou restrito a projetos/fluxos específicos (veja a FAQ sobre limitar a chave).

5. Confirme. A chave é exibida uma única vez — copie na hora (veja a FAQ sobre perder a chave).

Depois, use essa chave no seu sistema para autenticar as chamadas à API do agente.

Não. Por segurança, a chave de API é mostrada uma única vez, no momento em que é criada — o aviso na tela deixa claro: "Copie agora - ela não será exibida novamente". Depois que você fecha, o valor completo não pode mais ser recuperado.

O que fazer se perdeu: revogue a chave antiga (para ela deixar de funcionar) e crie uma nova, copiando o valor com cuidado desta vez. Guarde a chave num lugar seguro (um gerenciador de segredos), nunca em texto aberto compartilhado.

Criar chaves de API exige permissão adequada no time e, dependendo do caso, um plano que inclua o recurso. Se o botão de criar não aparece ou fica bloqueado:

- Confira se você tem permissão de gestão no time (papel como Owner/Admin) — membros sem esse acesso não criam chaves.

- Verifique se o plano do time contempla o uso de API.

Se você precisa criar e não consegue, peça a alguém com papel de administrador do time, ou fale com o suporte pela Clarice.

Ao criar a chave, você define o que ela pode fazer e onde:

- Permissões — marque só o que a integração realmente precisa (princípio do menor privilégio). Evite dar mais do que o necessário.

- Escopo — escolha entre acesso total (a chave enxerga todos os projetos/fluxos do time) ou restrito, selecionando os projetos e/ou fluxos específicos que ela pode acessar.

Para limitar a chave a um agente específico, use o escopo restrito e selecione apenas aquele projeto/fluxo. Assim, se a chave vazar, o estrago fica contido ao que ela tinha acesso.

Atenção: uma chave com acesso total passa a enxergar também os agentes criados depois — porque o escopo é "tudo do time", não uma lista fixa. Se você quer que novos agentes fiquem de fora, use escopo restrito.

Para cortar o acesso, revogue a chave na tela Chaves API: uma chave revogada para de funcionar imediatamente em qualquer integração que a use. Faça isso assim que suspeitar de vazamento ou quando a integração não for mais necessária.

Para saber se uma chave ainda está sendo usada, olhe a coluna Último uso na lista de chaves — ela mostra quando a chave foi usada pela última vez. Uma chave sem uso recente é candidata a ser revogada; uma com uso recente indica que há uma integração ativa dependendo dela (confirme antes de revogar, para não derrubar algo em produção).

Você também pode filtrar a lista por status (ativas, revogadas) para organizar a auditoria.

Sim, você pode trocar o modelo de IA do agente para qualquer um dos principais modelos de mercado (como OpenAI ou Google), sem escrever código. A troca é feita por um menu na própria tela, em dois lugares:

- Na edição do passo do fluxo: abra o passo e use a etiqueta/menu de modelo para escolher o modelo daquele agente.
- Na área de testes: você também pode ajustar o modelo enquanto testa o agente.

Para dúvidas sobre o que acontece se o modelo escolhido ficar indisponível, consulte a aba de testes do agente e a configuração de modelos de reserva (fallback) — tela Área de Testes: aba Testar (inventario_screen_tab_studio_testar).

Não precisa parar. Você pode montar uma cadeia de fallback de modelos: se o modelo principal falhar ou não der conta, o agente passa automaticamente para o próximo modelo da lista, na ordem que você definir.

Como configurar:

1. Na área de testes do agente, clique no botão ⚙️ Fallbacks (ao lado do seletor de modelo).

2. Abre a janela Cadeia de fallback de modelos. No topo aparece o Modelo principal (sempre o primeiro a ser usado).

3. Em Fallbacks (em ordem), use + adicionar modelo de fallback para incluir quantos modelos de reserva quiser, na ordem de prioridade.

4. Clique em Salvar.

A cadeia também protege quando o contexto da conversa fica maior que a janela do modelo principal: o sistema tenta escalar para o próximo modelo da fila. Se não houver nenhum fallback configurado, conversas que excedam o modelo principal recebem um aviso pedindo curadoria de memórias.

Para trocar o modelo principal do agente, consulte a tela de edição do passo — Editar Passo no Fluxo (inventario_screen_passo_editar).

O custo médio por execução é o cálculo feito automaticamente pela plataforma para determinar o custo de uma mensagem ou análise do agente. Ele é baseado na estimativa dos tokens que as instruções do agente possuem e varia conforme o modelo utilizado.

O custo por mensagem inclui tanto o input enviado pelo usuário quanto a resposta do agente. É o custo combinado de ambas as partes, utilizado para calcular o custo médio de uma conversa completa.

Créditos são a unidade de consumo da plataforma. Esta calculadora estima quantos créditos (e quanto em R$) um fluxo consome, com base nos tokens dos agentes e no plano do time.

O plano importa porque cada um tem uma taxa de crédito diferente: planos maiores pagam mais barato por token. Na prática, o mesmo fluxo custa menos créditos no Enterprise do que no Plus, e no Plus menos que no Standard. Ao escolher o plano na calculadora, o custo estimado se ajusta a essa taxa.

Use para prever o gasto mensal/anual de um fluxo e para comparar quanto um plano superior economizaria no seu volume.

A calculadora usa o GPT-4o como modelo base de referência para converter tokens em créditos/custo. Isso dá uma estimativa consistente para comparar cenários.

Se você quer estimar com outro preço — por exemplo, um modelo mais barato ou uma negociação específica —, use o campo Preço por Milhão de Tokens (R$) para informar o valor manualmente. A calculadora recalcula os créditos e o custo com base no número que você digitou, em vez do padrão.

Como modelos mais baratos custam menos por token, ver o resultado com um preço menor mostra a economia potencial de trocar o modelo dos agentes.

Porque crédito não é a mesma coisa que token. Token é a unidade que os modelos de IA processam; crédito é a unidade de cobrança da plataforma. A calculadora converte um no outro aplicando a taxa do plano (o preço por token daquele plano).

Por isso os créditos podem aparecer com casas decimais — o custo por execução costuma ser pequeno, e é ao multiplicar pelo volume (execuções por mês) que o total ganha escala. Cada agente pode ter um volume próprio de execuções por mês, e o resumo soma tudo para dar o custo por execução, mensal e anual do fluxo.

O custo de uma execução vem da soma de três tipos de token:

- Tokens de instrução — o tamanho do prompt/instruções do agente. Toda vez que ele roda, essas instruções entram no cálculo.

- Tokens de input — o que você envia ao agente naquela execução (a mensagem, o texto do documento, os dados).

- Tokens de output — o que o agente gera como resposta.

Cada modelo tem um preço por milhão de tokens, e normalmente o output é mais caro que o input. Por isso, prompts enormes e respostas longas encarecem a execução. A calculadora usa esses três valores, multiplicados pelo preço do modelo, para estimar o custo.

A própria calculadora ajuda com isso: ao montar a estimativa, você informa (ou ela estima) os tokens de instrução do agente — é o tamanho do prompt convertido em tokens.

Regra prática: quanto mais longo e detalhado o prompt, mais tokens de instrução, e maior o custo por execução (porque as instruções entram em toda rodada). Se o custo estiver alto, uma forma de reduzir é enxugar o prompt, tirando repetição e texto desnecessário, sem perder as regras importantes.

Nesta calculadora você adiciona um cartão por agente do fluxo, na ordem em que eles executam. A seta entre os cartões indica que a resposta de um alimenta o próximo.

Para cada agente, você define o modelo e os tokens (instrução, input e output). A calculadora soma o custo de todos os agentes para dar o custo de uma execução do fluxo inteiro. Informando as execuções por mês, ela projeta também o custo mensal e anual.

Assim você compara cenários — por exemplo, ver quanto economiza trocando o modelo de um agente específico — antes de rodar de verdade.

Porque cada modelo de IA tem um preço por token diferente. Modelos mais avançados costumam custar mais por token; modelos mais simples custam menos. Como o custo da execução é (tokens × preço do modelo), trocar o modelo muda diretamente o valor.

Use isso a seu favor: se um agente do fluxo não precisa do modelo mais caro para fazer bem o trabalho dele, trocá-lo por um mais barato reduz o custo total sem necessariamente perder qualidade naquele passo.

Execuções por mês é quantas vezes você espera rodar o agente/fluxo em um mês — o volume. A calculadora usa esse número para projetar o gasto:

- Custo por execução = soma dos tokens × preço do modelo de cada agente.

- Custo mensal = custo por execução × execuções por mês.

- Custo anual = custo mensal × 12.

Cada agente pode ter o seu volume, e o resumo agrega tudo. É por isso que o resultado pode aparecer com casas decimais — o custo por execução costuma ser um valor pequeno, e a projeção mensal/anual o multiplica.

São dois recortes do mesmo custo:

- Por Mensagem — estima o custo de uma troca (o input do usuário + a resposta do agente). Bom para saber quanto custa cada interação isolada.

- Por Conversa — estima o custo de um diálogo inteiro, com várias mensagens. Como numa conversa o histórico vai crescendo e sendo reenviado ao modelo a cada nova mensagem, o custo por conversa não é simplesmente o custo de uma mensagem vezes o número de mensagens — ele considera esse acúmulo.

Use "Por Mensagem" para ter a unidade básica e "Por Conversa" para projetar o custo real de um atendimento completo.

O modo avançado serve para estimar com mais precisão agentes conversacionais organizados por estados (etapas do fluxo da conversa). Dois conceitos:

- Instruções transversais — a parte do prompt que vale para a conversa toda, presente em qualquer estado.

- Estados — blocos de instrução que valem só em certas etapas da conversa. Um agente "otimizado por estados" só carrega, a cada momento, as instruções daquele estado, em vez do prompt inteiro — o que reduz tokens e custo.

Quando usar: se o seu agente é grande e você o dividiu em estados, use o modo avançado para refletir essa economia. Se ainda não organiza por estados, marque a opção correspondente ("ainda não otimizo por estados") e use o modo simples, que considera o prompt inteiro a cada mensagem.

O cálculo parte do preço dos modelos de IA, que é cobrado pelos provedores em dólar por milhão de tokens. A calculadora usa esses valores para estimar o custo de cada mensagem/conversa.

Os valores costumam aparecer com várias casas decimais porque o custo de uma única mensagem é muito pequeno — é ao multiplicar pelo volume (muitas mensagens ou conversas por mês) que o número ganha escala. Use a estimativa para comparar cenários (modelos, tamanho de prompt) mais do que como valor exato de fatura.

A assinatura é paga apenas por cartão de crédito. Não é possível pagar a assinatura recorrente por PIX — o PIX não serve para a cobrança automática de cada ciclo.

O pagamento é recorrente: a cada ciclo (mensal ou anual), a cobrança acontece automaticamente no cartão cadastrado, sem você precisar fazer nada. O processamento é feito pelo Asaas (o gateway de pagamento).

Não. Nenhum dado de cartão passa pela plataforma — todo o cadastro e o processamento do cartão acontecem no ambiente seguro do Asaas, o gateway de pagamento. A prototipe.ai não armazena o seu cartão.

O que a plataforma pede antes (CPF e endereço) é exigência do próprio gateway para emitir a cobrança e a nota fiscal. Esses dados de cobrança ficam salvos no perfil do time/usuário só para você não precisar digitar de novo numa próxima compra.

Depois de clicar em Ir para pagamento, o sistema cria a assinatura no Asaas e te leva ao checkout do Asaas para cadastrar o cartão. Enquanto o pagamento não é confirmado, pode aparecer uma tela de espera que atualiza sozinha.

Quando tudo dá certo, aparece um check verde e "Assinatura ativada!", com o plano e o time. Pontos importantes:

- Fechar a aba não cancela nada — a assinatura é ativada automaticamente assim que o pagamento é confirmado.

- Se ainda estiver processando, a página se atualiza até ativar.

- Se algo travar ou o link de pagamento não voltar, é caso de falar com o suporte.

A assinatura é sempre por time, nunca por usuário individual. Ela tem ciclo mensal ou anual e é cobrada automaticamente no cartão de crédito a cada ciclo.

Detalhes importantes:

- Qualquer membro logado pode ver os planos, mas apenas Owners e Admins do time conseguem concluir a contratação (o checkout).

- Ao escolher um plano, você vai direto para os dados de cobrança e o pagamento é processado no ambiente seguro do gateway.

- Como é por time, todos os membros passam a usufruir do plano contratado para aquele time.

Para cancelar ou trocar de plano, vá em Configurações do Time → Uso de Créditos e clique em Minha Assinatura — a partir daí você gerencia (cancela ou muda de plano). Só quem administra o time (Owner/Admin) tem acesso a isso.

Se a assinatura vencer (não for renovada/paga), ela passa para expirada ou suspensa, e os recursos que dependem de plano pago deixam de funcionar para o time — por exemplo, publicar via API, iniciar prototipação e outras funcionalidades pagas. Ao renovar/reassinar, o acesso volta.

Crédito é a unidade de consumo da plataforma. Cada operação que a IA realiza consome uma quantidade de créditos, calculada com base no modelo de IA usado e no volume processado.

Contam como consumo, por exemplo: uma mensagem respondida por um agente, um passo de fluxo executado, um áudio transcrito, uma imagem analisada ou um PDF processado. Cada uma dessas operações é um "evento" de consumo. Na tela de uso, você acompanha o total de créditos gastos, o ranking de quais agentes/fluxos mais consomem e o gráfico de consumo por dia.

Porque esta tela (/usage) é somente leitura — ela serve para qualquer membro do time acompanhar o consumo, mas não tem os controles de cobrança.

Para comprar créditos, gerenciar limites ou trocar/cancelar o plano, use a tela administrativa em Configurações do Time → Uso de Créditos. Essa tela tem os botões de ação, mas só aparece para quem é Owner ou Admin do time.

Ou seja: /usage é para ver; a de Configurações é para gerenciar (e requer permissão de administração).

Depende do modo configurado pelo administrador do time (em Configurações → Uso de Créditos):

- Hard stop — ao atingir o limite, o uso de créditos é bloqueado: conversas, fluxos e API param de funcionar até o limite ser ajustado ou mais créditos serem adicionados.

- Soft limit — nada para; o administrador recebe alertas, mas o time continua operando normalmente.

Se aparecer "Sem limite definido", significa que o plano não impõe um teto mensal (ou o admin não configurou um) — o consumo é livre, apenas monitorado, nunca bloqueado.

Após o agente processar um input, você poderá acessar e baixar os resultados:

1. Depois de enviar um input para o agente, os resultados gerados aparecerão no 'Histórico de Execuções'.

2. Para visualizar os resultados diretamente na tela, clique em 'Ver resultados' na entrada correspondente no histórico.

3. Para baixar os resultados, utilize o botão de 'Download' disponível. Os formatos de exportação incluem CSV, XLSX e DOCX.

O formato da resposta do agente influencia diretamente o tipo de exportação:

* Para exportar um arquivo DOCX com formatação adequada, é necessário solicitar nas instruções do agente que a resposta seja gerada em formato Markdown.

* Para exportar em CSV ou XLSX, você deve solicitar nas instruções do agente que a resposta seja gerada em formato JSON.

Certifique-se de configurar a instrução do agente de acordo com o formato de exportação desejado.

Existem duas formas de exportar o conteúdo gerado pelo agente para um formato Word. A primeira é exportar em JSON, caso você tenha acesso a uma API que fará a criação automática do documento em seu sistema. Caso contrário, você pode solicitar que o agente crie o conteúdo em formato Markdown. Ao informar o agente de que o formato adequado é Markdown, ele habilitará automaticamente um botão para download em DOCX, permitindo que você obtenha o documento no formato desejado.

No relatório da execução, você vê o resultado de cada passo e pode baixá-lo. Siga as etapas:

1. Abra a execução em Ver Relatório (no Histórico de Execuções).

2. Para cada passo, aparece o Prompt (instruções) de um lado e a Resposta gerada do outro.

3. Use o botão Baixar no passo para salvar o resultado. Dependendo do tipo de resposta, os formatos incluem HTML, XLSX, DOCX, CSV, TXT.

O relatório também mostra a Informação da Execução (status, início, fim, duração) e o Consumo (créditos consumidos, custo e tempo de execução).

Os resultados de uma execução podem ser baixados em vários formatos, conforme o tipo de resposta do agente. Os principais são:

- XLSX (planilha)

- DOCX (documento Word)

- CSV (dados tabulares)

- HTML (conteúdo formatado)

- TXT (texto simples)

Você encontra o botão Baixar no passo, dentro do relatório da execução. Vale lembrar que o formato ideal depende de como você pediu a resposta ao agente: para sair bem em DOCX, oriente o agente a responder em Markdown; para CSV/XLSX, peça a resposta em JSON.

Esse link abre a visualização de um arquivo/resultado exportado pela plataforma — por exemplo, uma resposta que um agente gerou e alguém compartilhou com você por link, sem precisar de conta.

Pontos importantes:

- O link pode expirar. Cada link tem validade; passado o prazo, aparece a mensagem "Link expirado". Nesse caso, peça a quem compartilhou para gerar um novo link.

- O que você vê depende do tipo do conteúdo exportado (texto, HTML, etc.) — por isso, em alguns casos, o resultado aparece apenas como texto formatado.

Se o link não abrir mesmo dentro da validade, confirme com quem enviou se ele ainda está ativo e se você tem permissão de acesso àquele conteúdo.

Não é necessário publicar o agente para ele começar a funcionar. Assim que o agente é concluído, você é redirecionado para a área de testes, onde já pode começar a interagir com ele. O botão 'Publicar' oferece outras opções de disponibilização do agente, como gerar o token de acesso para a API e conectar o agente ao WhatsApp.

Depois de pronto, seu agente pode ser disponibilizado de quatro formas, no botão Publicar → tela Publicar o Agente:

- Web — uma página online do agente, acessada por link no navegador.

- API — integração com o seu sistema, enviando dados por requisição.

- WhatsApp — o agente atende num número de WhatsApp Business.

- Embedar — o agente aparece dentro do seu site (iframe).

Cada aba tem as instruções e os campos daquela forma. Você pode usar mais de uma ao mesmo tempo — por exemplo, o mesmo agente na Web e no WhatsApp. Escolha conforme onde seus usuários vão conversar com ele.

Para compartilhar seu agente por link, use a aba Web da tela de publicação. Siga as etapas:

1. No agente, clique em Publicar e vá para a aba Web ("Publicar na Web").

2. Copie o Link atual do agente (há um botão de copiar ao lado dele).

3. Para que qualquer pessoa consiga abrir sem precisar ter conta, clique em Publicar Agente Web e confirme no aviso.

Atenção: enquanto o agente não está publicado, o link só funciona para membros com permissão no projeto/time. Depois de publicado, ele fica acessível sem exigir login — por isso, confira se não há dados sensíveis nas páginas públicas do agente antes de publicar.

Para embutir o agente no seu site, use a aba Embedar da tela de publicação. Siga as etapas:

1. No agente, clique em Publicar e abra a aba Embedar (iframe).

2. Copie o código de embed gerado e cole no HTML do seu site, onde quiser que o agente apareça.

3. Por segurança, restrinja quais sites podem embedar o agente (a proteção de embed bloqueia o acesso direto pela URL e libera só nos domínios que você autorizar).

Assim o agente roda dentro da sua página, como um chat integrado. Se o agente ainda não estiver publicado, publique-o primeiro para que o embed funcione fora dos membros do time.

As duas deixam o agente acessível fora da plataforma, mas de formas diferentes:

- Publicar na Web — cria uma página própria do agente, com um link que você compartilha. A pessoa abre esse link no navegador e conversa com o agente numa tela dedicada.

- Embedar (iframe) — coloca o agente dentro do seu site, como um chat integrado à sua própria página, sem a pessoa sair do seu site.

Escolha Web quando quiser mandar um link direto; escolha Embedar quando quiser que o agente apareça como parte do seu site. Dá para usar as duas ao mesmo tempo.

A aba WhatsApp na tela de publicação só aparece em certas condições. Se ela não estiver visível, os motivos mais comuns são:

- O recurso de WhatsApp não está habilitado para o seu contexto (tipo de agente ou acesso).

- Você chegou à tela por um caminho que não expõe essa aba.

Se você precisa conectar o agente ao WhatsApp e a aba não aparece, fale com o suporte pela Clarice para confirmar se o recurso está liberado para o seu time/agente.

Alguns pontos costumam explicar isso:

- O agente ainda não está publicado de fato. Enquanto o status for "Não publicado", o link só funciona para membros com permissão no projeto/time — para outras pessoas, não abre. Clique em Publicar Agente Web e confirme.

- Proteção de embed / Modo Restrito ligado. Se essa proteção estiver ativa, o acesso direto pela URL (link digitado, e-mail, WhatsApp) é bloqueado de propósito — o agente só abre embedado nos sites autorizados. Nesse caso, ou você libera o acesso direto, ou usa o embed no site permitido.

- Link errado ou do tipo incorreto. O link pode variar conforme o tipo de agente; confira se copiou o link atual mostrado na aba Web.

Verifique o status na aba Web e a configuração de Modo Restrito; na maioria dos casos é um desses dois.

O Modo Restrito (também chamado de proteção de embed) controla por onde o agente pode ser acessado. Quando ativado:

- Bloqueia o acesso direto pela URL — o link digitado no navegador, mandado por e-mail ou WhatsApp não abre o agente.

- Libera o agente só embedado nos sites que você autorizar. Você informa os domínios permitidos, e só neles o agente funciona.

Serve para segurança: evita que o link "vaze" e seja usado fora do seu site. Se você quer que qualquer pessoa acesse por um link, deixe o Modo Restrito desligado; se quer o agente só dentro do seu site, mantenha ligado e liste os domínios.

O agente pode ser embedado em várias plataformas, usando o mesmo código de iframe da aba Embedar. Os caminhos variam por ferramenta:

- SharePoint — use a web part "Embed" e cole o código; o administrador do site precisa autorizar o domínio.

- WordPress, Notion, Confluence e outras — cole o código de embed no bloco de HTML/iframe da plataforma.

Na aba Embedar há guias específicos (ex.: "Como embedar no SharePoint" e "Outras plataformas") com o passo a passo de cada uma. Lembre de, se o Modo Restrito estiver ligado, incluir o domínio da ferramenta na lista de sites autorizados.

Sim. O acesso via API exige plano pago — no plano gratuito, a aba API mostra um aviso de que a API não está disponível.

Com o plano adequado, na aba API você gera a chave de acesso (por exemplo, "Criar Chave Pessoal" / chave do time) e usa a URL do agente para integrá-lo ao seu sistema. Se a opção aparecer bloqueada, é sinal de que o plano atual não inclui a API — faça o upgrade ou fale com quem administra o time.

Você pode criar um manual de uso do fluxo — uma instrução que fica disponível para quem for usar o agente, acessível pelo botão Como usar. Siga as etapas:

1. Abra o fluxo em Editar Fluxo de Agentes e clique em Criar instruções sobre esse fluxo.

2. Na tela de edição da instrução, escreva o conteúdo do manual (como enviar arquivos, o que o fluxo faz, dicas de uso) e, se quiser, adicione mídia.

3. Salve. A instrução passa a aparecer como um item de ajuda do fluxo.

4. Para o usuário final, o manual fica acessível pelo botão Como usar, no topo da tela de interação com o agente.

Assim, quem for usar o agente tem um guia claro, escrito por você, direto na interface.

O AgentVerse é um mapa visual de todos os agentes e fluxos do seu time — uma forma de enxergar, de cima, tudo o que o time construiu e como as peças se relacionam. Você abre por AgentVerse, no topo da plataforma.

O que você encontra lá:

1. Os agentes representados como nós no mapa, agrupados/coloridos por área ou categoria.

2. Painéis de alertas e status, que ajudam a ver rapidamente o que precisa de atenção.

3. Uma visão do todo, útil para navegar entre muitos agentes sem depender só das listas.

É especialmente útil quando o time tem muitos agentes e fluxos: em vez de rolar listas, você vê o panorama e localiza o que procura visualmente.

Você adiciona o agente (ou fluxo) ao contexto da conversa, e a Clarice passa a responder e agir focada nele. Como fazer:

1. Na conversa com a Clarice, use a busca de contexto para procurar um agente ou fluxo pelo nome.

2. Selecione o item — ele entra como contexto da conversa atual.

3. A partir daí, quando você pedir um ajuste ("mude o tom", "acrescente tal regra"), a Clarice sabe que é sobre aquele agente.

Você pode falar sobre qualquer agente que você tem acesso. Ao escolher o primeiro item, a Clarice trava naquele time — então os próximos agentes/fluxos oferecidos no contexto são do mesmo time, para não misturar. Sem contexto definido, ela responde de forma mais geral sobre a plataforma.

Sim. Suas conversas com a Clarice ficam salvas e acessíveis pela barra lateral da tela dela — cada linha é uma conversa anterior, que você pode reabrir para continuar de onde parou.

A lista reúne suas conversas com a Clarice de diferentes projetos/times (por isso você pode ver conversas de contextos variados na mesma barra). É a sua a mesma copilota, esteja você usando a tela cheia da Clarice ou o balão de suporte no canto das telas — os dois compartilham o mesmo histórico e o mesmo backend; muda só o formato (janela dedicada vs. painel flutuante).

Você dá ao agente a ferramenta Transf. para Humano (handoff). Quando a conversa precisa de um atendente, o agente aciona essa ferramenta: a IA é pausada e a conversa é encaminhada para o atendimento humano.

Como configurar:

1. Na tela do agente, abra Ferramentas do Agente e escolha Transf. para Humano.

2. Selecione a plataforma de atendimento para onde a conversa vai — Chatwoot ou Webhook Genérico — e preencha os campos pedidos.

3. Salve.

A partir daí, quando o agente decidir transferir (ou quando o próprio prompt mandar), a IA para de responder e um atendente humano assume a conversa naquela plataforma. Depois, a IA pode voltar a responder quando o atendimento for concluído.

Ao configurar a ferramenta Transf. para Humano, escolha a plataforma Chatwoot — assim, quando o agente transferir, a conversa aparece na sua caixa de atendimento do Chatwoot para um atendente assumir. Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente e selecione Transf. para Humano.

2. Em plataforma de atendimento, escolha Chatwoot.

3. Preencha os dados de conexão do Chatwoot pedidos no formulário e salve.

Depois disso, sempre que o agente acionar a transferência, a IA é pausada e a conversa é entregue ao Chatwoot para atendimento humano. O passo a passo técnico completo dessa integração está detalhado logo abaixo, na FAQ de configuração do Chatwoot.

Depende de como o atendimento é encerrado. Quando o agente transfere a conversa para um humano, a IA fica pausada — ela não responde enquanto o atendente está no comando. Para a IA voltar a responder, a conversa precisa ser devolvida (retomada):

- O atendimento humano sinaliza que terminou (por exemplo, resolvendo/encerrando o ticket na plataforma de atendimento), e a conversa é retomada — a partir daí a IA volta a responder normalmente.

- Enquanto a conversa estiver marcada como em atendimento humano (IA pausada), o agente não responde, para não atropelar o operador.

Ou seja: a IA volta assim que a conversa é retomada após o atendimento. Se você usa Chatwoot ou Webhook, esse "devolver para a IA" faz parte da integração de handoff — confira os detalhes na FAQ de configuração correspondente logo abaixo.

Quando você faz parte de mais de um time, trabalha em um time por vez (o time ativo). Para alternar entre eles:

1. No topo da área de Configurações (ou no seletor de time da plataforma), clique no nome do time atual — ele abre uma lista com todos os seus times.

2. Selecione o time para o qual quer mudar.

3. A partir daí, as telas de configuração (Membros, Uso de Créditos, White Label, etc.) passam a se referir ao time escolhido.

Assim você gerencia cada time separadamente, trocando o time ativo sempre que precisar mexer nas configurações de outro. Cada time tem seus próprios membros, permissões, créditos e integrações.

Sim. O fluxo pode persistir memória entre execuções — cada nova execução recebe, no início, o contexto da execução anterior. É útil quando o fluxo precisa continuar de onde parou ou lembrar do que já processou.

Como ativar:

1. Abra o fluxo em Editar Fluxo de Agentes.

2. Ative o toggle Persistir memória entre execuções.

3. Salve o fluxo.

Com isso ligado, cada execução começa já sabendo o contexto da anterior. Se você deixar desligado, cada execução é independente, sem memória das anteriores.

Sim. No fluxo existe o modo Processar apenas dados novos — quando ativado, o fluxo lembra até onde já processou e ignora dados que já foram analisados. É ideal para planilhas que crescem ao longo do tempo (vendas, logs, transações), evitando reprocessar linhas repetidas.

Como ativar:

1. Abra o fluxo em Editar Fluxo de Agentes.

2. Ative o toggle Processar apenas dados novos.

3. Configure a regra de corte: a coluna de referência (ex.: data, id) e como comparar (por exemplo, "somente maiores que o ponto de corte"). Você pode deixar o ponto de corte automático (a plataforma lembra da última execução e avança sozinha) e escolher o escopo (global ou por entidade).

4. Salve.

A partir daí, se o fluxo receber dados que já viu, ele os ignora e processa só o que é novo.

Sim. O fluxo tem o toggle Habilitar Recebimento de Múltiplos Arquivos de uma vez, que controla se o fluxo pode receber e processar vários arquivos numa única execução. Para desabilitar, é só desligá-lo.

Como fazer:

1. Abra o fluxo em Editar Fluxo de Agentes.

2. Localize o toggle Habilitar Recebimento de Múltiplos Arquivos de uma vez.

3. Desligue o toggle para permitir apenas um arquivo por execução (ou ligue para permitir vários).

4. Salve o fluxo.

Com o toggle desligado, o fluxo passa a aceitar um arquivo por vez em cada execução.

Sim. É o modo orquestrador: um fluxo orquestrador aguarda os resultados de outros fluxos antes de executar. Assim você encadeia fluxos, garantindo que um só rode depois que os outros terminarem.

Como configurar:

1. Abra o fluxo em Editar Fluxo de Agentes.

2. Ative o toggle Tornar este fluxo um orquestrador.

3. Em Selecione os fluxos que devem ser orquestrados, adicione os fluxos que este deve aguardar (use o seletor e o botão Adicionar; para tirar, use Remover).

4. Clique em Salvar.

A partir daí, este fluxo só executa depois que os fluxos selecionados terminarem.

No fluxo há o toggle Visibilidade pública. Por padrão o fluxo é privado (só membros com permissão no time acessam); ao ativar a visibilidade pública, ele fica acessível de forma aberta.

Como fazer:

1. Abra o fluxo em Editar Fluxo de Agentes.

2. Localize o toggle Visibilidade pública.

3. Ative o toggle.

4. Clique em Salvar.

Enquanto o toggle estiver desligado, o fluxo permanece privado — apenas quem tem permissão no time consegue vê-lo e usá-lo.

Você tem alguns caminhos para corrigir, do mais guiado ao mais manual, a partir do relatório da execução:

1. Conversar com a Esther sobre esta execução — clique nesse botão e analise o problema por voz/chat com a IA, que ajuda a entender o que aconteceu.

2. Dar feedback no passo problemático — no passo que não ficou bom, use o botão de feedback; ele aciona a correção do agente por IA a partir do que você apontou.

3. Ajustar a configuração do passo — abra as Configurações daquele agente e ajuste instruções, modelo ou entrada.

4. Reexecutar a partir do ponto ajustado, para ver o novo resultado sem rodar tudo de novo.

Ou seja: dá para melhorar conversando com a Esther, corrigindo por feedback ou editando o passo — e testar de novo até a resposta ficar como você quer.

Sim. No relatório da execução, você pode repetir a partir de um passo específico, reaproveitando o que já rodou. Siga as etapas:

1. Abra o relatório da execução e localize o passo a partir do qual quer reexecutar.

2. Clique em Repetir naquele passo.

3. No modal Repetir Execução, escolha a opção desejada:

- Apenas esse passo — roda de novo só aquele passo.

- A partir deste passo — reaproveita os resultados dos passos anteriores e roda daí em diante.

- Execução completa — refaz o fluxo inteiro do início.

Escolhendo A partir deste passo, você economiza créditos e tempo, porque só o trecho restante é reprocessado.

Você tem caminhos do mais guiado ao mais manual, a partir do relatório da execução:

1. Conversar com a Esther sobre esta execução — analise o erro por voz/chat com a IA, que recebe o contexto do que aconteceu e ajuda a entender.

2. Copiar detalhes do erro — no alerta de erro, copie o diagnóstico completo (mensagem, chamadas que falharam) e envie a quem dá suporte.

3. Dar feedback no passo problemático — aciona a correção do agente por IA a partir do que você apontou.

4. Ajustar a configuração do passo e reexecutar a partir do ponto do erro — corrige e roda de novo só o trecho necessário, sem refazer tudo.

Comece pela Esther se quiser entender o que houve; parta para ajustar o passo e reexecutar quando já souber o que corrigir.

Todo o histórico de execuções do fluxo fica na tela Histórico de Execuções. Para chegar nela:

1. Abra o fluxo e clique em Ver Logs (no topo da tela do fluxo).

2. A lista mostra cada execução com ID, fluxo, Status, quando foi Iniciado e Concluído, Duração, número de Passos e Passos Pulados.

3. Em cada linha, use Ver Relatório para abrir os detalhes daquela execução.

O status ajuda a entender o resultado: Completed (terminou com sucesso), Completed com erros (terminou, mas um passo falhou), Failed (parou por erro), Paused/Aguardando aprovação (parada esperando alguém), Running/Queued (rodando ou na fila), entre outros.

Você cancela (aborta) uma execução que ainda está rodando ou pausada direto no Histórico de Execuções. Siga as etapas:

1. Abra Ver Logs do fluxo para ver a lista de execuções.

2. Localize a execução em andamento/pausada (status como Running, Queued ou Paused).

3. Na coluna Ações daquela linha, clique em Abortar.

A execução é interrompida e passa para o status de abortada pelo humano. Execuções já concluídas não têm o botão Abortar — ele aparece só enquanto a execução ainda pode ser interrompida.

Você pode procurar uma execução pelo que apareceu dentro dela — um nome, um e-mail, um número de pedido. Siga as etapas:

1. Abra o Histórico de Execuções do fluxo (Ver Logs).

2. No campo Buscar nas respostas., digite um trecho que apareceu no input ou nas respostas da execução.

3. Clique em Buscar.

A busca varre o conteúdo das execuções recentes e lista só as que contêm aquele trecho. Por padrão ela olha as últimas 50 execuções — o link Alterar permite ajustar quantas execuções entram na busca.

Cada execução no histórico tem um status que resume como ela terminou (ou em que ponto está):

- Completed — terminou com sucesso.

- Completed (com erros) — terminou, mas algum passo falhou (vale abrir e conferir).

- Failed — parou por erro.

- Aguardando aprovação — está parada esperando alguém aprovar uma tarefa; o próprio badge leva à tarefa de aprovação.

- Abortado pelo humano — foi cancelada por alguém.

- Limite de iterações excedido — um ciclo (por exemplo, de aprovação ou verificação) repetiu além do limite configurado.

- Processando subgrupos / Consolidando subgrupos — está no meio do processamento em lotes.

- Running — está rodando agora.

- Queued — está na fila, aguardando começar.

Use o status para saber rapidamente o que precisa de atenção — os "com erros", "Failed" e "Aguardando aprovação" são os que costumam pedir ação sua.

Cada fluxo tem uma documentação que descreve o que ele faz e como funciona, gerada a partir dos seus agentes e passos. Para acessá-la:

1. Abra o fluxo.

2. No topo, clique em Ver Documentação (ao lado de Publicar e Versões).

3. A documentação abre com a explicação do fluxo — o que ele recebe, o que cada passo faz e o que ele produz.

É uma boa forma de entender rapidamente um fluxo (seu ou de um colega) sem precisar abrir passo por passo. Se os agentes do fluxo mudarem, a documentação pode ser sincronizada para refletir o estado atual.

Um fluxo de agentes é uma sequência de agentes que executam, um após o outro, para dar conta de um processo maior — cada passo é um agente com uma função, e a resposta de um alimenta o próximo. Você organiza os passos "na ordem que deseja que sejam executados".

Quando usar um fluxo (em vez de um agente único):

- Quando a tarefa tem etapas distintas (por exemplo: classificar → analisar → gerar resposta), cada uma melhor resolvida por um agente especializado.

- Quando você precisa encadear resultados, com um agente usando a saída do anterior.

- Quando quer reaproveitar um mesmo agente em vários processos.

Já um agente que só existe dentro do fluxo faz sentido quando ele é um passo específico daquele processo e não precisa ser usado sozinho — você o cria direto no passo, sem que ele vire um agente independente. Se o agente for útil isoladamente, crie-o como agente próprio e adicione ao fluxo.

Você exclui um fluxo a partir da própria tela dele. Siga as etapas:

1. Abra o fluxo.

2. No topo, ao lado do nome do fluxo e do ícone de lápis (Editar Fluxo), clique no ícone de lixeira.

3. Confirme a exclusão no aviso que aparece.

Feito isso, o fluxo é removido. Antes de excluir, verifique se ele não está publicado ou sendo usado em integrações, para não interromper algo em produção.

Você pode criar um fluxo já começando a montar os agentes que ele terá, mesmo que nenhum exista ainda. Siga as etapas:

1. Crie o fluxo (por exemplo, descrevendo o que quer automatizar e iniciando o projeto, ou por Criar Novo Fluxo). O fluxo nasce vazio, com a mensagem "Organize os agentes do fluxo na ordem que você deseja que sejam executados.".

2. Clique em Adicionar Agente ao Fluxo para criar o primeiro passo.

3. Em cada passo, defina o agente daquele passo (você cria o agente ali mesmo) e configure suas instruções.

4. Repita para cada etapa do processo, na ordem desejada.

Assim o fluxo e seus agentes nascem juntos — você desenha a sequência e vai preenchendo cada passo com um agente novo.

Você pode montar um fluxo novo aproveitando agentes que já criou antes. Siga as etapas:

1. Crie o fluxo — ele começa vazio, com o aviso para organizar os agentes na ordem de execução.

2. Clique em Adicionar Agente ao Fluxo.

3. No passo, use o campo Selecionar um Agente e escolha um agente que já existe (você pode usar a busca Buscar termo exato nos prompts dos agentes. para achar pelo conteúdo).

4. Adicione quantos passos precisar, escolhendo agentes existentes, e organize a ordem.

Assim você reaproveita agentes que estavam soltos, encadeando-os em um novo fluxo.

Dentro de um fluxo, você adiciona um agente existente em um novo passo. Siga as etapas:

1. Na tela de montagem do fluxo, clique em Adicionar Agente ao Fluxo.

2. No passo criado, use o campo Selecionar um Agente e escolha o agente que já existe.

3. Ajuste a posição do passo (com Mover para cima/baixo ou o campo "Mover para") para deixá-lo na ordem certa.

O agente existente passa a fazer parte do fluxo naquele ponto, sem você precisar recriá-lo.

Você pode criar um agente novo no próprio passo do fluxo, sem sair para outra tela. Siga as etapas:

1. Na montagem do fluxo, clique em Adicionar Agente ao Fluxo.

2. No passo, em vez de escolher um agente existente, defina um agente novo e configure suas Instruções ali mesmo.

3. Ajuste as Configurações do passo (modelo, entrada, etc.) e a posição na ordem.

Assim o agente nasce já dentro do fluxo, naquele passo — útil quando o agente só faz sentido no contexto daquele processo.

A ordem dos passos (agentes) do fluxo é a ordem em que eles são executados, e você a reorganiza direto na tela de montagem. Em cada passo você tem:

- Mover para cima / Mover para baixo — desloca o passo uma posição por vez.

- Mover para — informe o número da posição para onde quer levar o passo.

O campo Posição mostra em que lugar da sequência o passo está. Ajuste até que a ordem reflita exatamente como você quer que os agentes rodem, do primeiro ao último.

No fluxo, cada agente recebe automaticamente, como parte do seu input, o histórico e a resposta dos passos anteriores — é assim que um agente "enxerga" o que outro produziu. Você controla isso nas Configurações do passo:

1. Abra o passo e vá em Configurações.

2. Em Dados de Entrada / Input do agente, o passo já recebe a saída do agente anterior; ali você define o que compõe a entrada daquele agente.

3. Na tela de configuração, o painel mostra o Prompt de um lado e a Resposta do outro, com os blocos de contexto (data/hora, input, histórico) que o agente recebe.

Assim, o agente seguinte trabalha em cima do resultado do anterior, sem você precisar copiar nada manualmente.

Dentro de um fluxo, a saída de um passo vira, automaticamente, parte da entrada do passo seguinte. O agente seguinte já recebe a resposta anterior no seu contexto e pode usá-la nas instruções.

Na prática:

1. Nas Instruções do agente, você se refere ao que veio do passo anterior (por exemplo, pedindo para ele analisar ou transformar o resultado recebido).

2. Nas Configurações do passo, em Input do agente, você confirma/ajusta o que entra para aquele agente.

Como o encadeamento é automático, basta escrever o prompt do agente contando com o resultado do anterior — a plataforma cuida de passar esse conteúdo adiante.

Sim. Um passo do fluxo pode enviar sua resposta para outro fluxo e aguardar o retorno — é o recurso Agente no Looping. Assim um fluxo aciona outro no meio do processo e usa o resultado.

Como configurar:

1. Abra as Configurações do passo (agente) que deve chamar o outro fluxo.

2. No card Agente no Looping, clique em Editar e ative o recurso ("Ative para enviar a resposta deste passo para outro fluxo e aguardar o retorno").

3. Indique o fluxo a ser chamado e salve.

Vale lembrar que também existe o modo orquestrador (na edição do fluxo), em que um fluxo aguarda outros terminarem antes de rodar. São formas complementares de encadear fluxos.

São dois caminhos para criar, com nível diferente de acompanhamento:

- Modo Padrão — passa pelo alinhamento de requisitos com a Esther antes de construir. Ela conversa com você, entende o que o fluxo precisa fazer e monta com base nisso. É o recomendado quando você quer que o agente já nasça bem estruturado.

- Criar Rápido — cria de forma mais direta, sem a etapa de alinhamento por conversa. Bom quando você já sabe exatamente o que quer e prefere montar na mão, ganhando tempo.

Escolha Modo Padrão para ter ajuda no desenho do fluxo; Criar Rápido quando quer ir direto ao ponto e ajustar você mesmo.

Ao Liberar para Produção um fluxo, você pode definir quando ele fica disponível e se o time é avisado. No modal de liberação:

1. Use o campo Disponível a partir de para escolher a data e hora em que o fluxo deve ficar visível para o time — permite agendar a liberação para um momento certo, em vez de liberar na hora.

2. Em Informações da versão, escreva (opcional) um resumo do que mudou nesta versão — esse texto vai no e-mail de notificação ao time.

3. Confirme. Se você usar Salvar sem notificar, o fluxo ainda vai para produção normalmente — a única diferença é que o time não recebe o e-mail de aviso.

Depois de liberar, aparece um link de acesso direto para o fluxo em produção, que você pode copiar e compartilhar.

Isso normalmente acontece quando o fluxo está com o corte incremental ligado (a opção "Processar apenas dados novos"). Com ela ativa, o fluxo lembra até onde já processou e ignora as linhas que já foram analisadas em execuções anteriores — então ele processa só o que é novo, e não o arquivo inteiro de novo.

Não é erro: é o comportamento esperado para planilhas que crescem ao longo do tempo (vendas, logs), evitando reprocessar e gastar créditos à toa. Se você quer que o fluxo processe tudo de novo, desligue esse modo na edição do fluxo ou ajuste o ponto de corte.

No relatório da execução há uma seção de Passos Pulados. Cada linha mostra o passo que não executou e a condição que causou o pulo, no formato "atributo = valor", além de qual passo originou a decisão.

Passo pulado nem sempre é problema: se o fluxo tem condições (chamar/pular agentes conforme a resposta), é esperado que alguns passos sejam ignorados em certas execuções. Para ver exatamente qual regra pulou o passo, abra o "Ver detalhes" dentro do aviso — ele lista cada condição avaliada. Se o pulo não deveria ter acontecido, revise as condições configuradas naquele passo.

No relatório da execução, expanda o passo que fez a chamada. Ali o card da integração mostra os detalhes técnicos: o endpoint chamado, o método HTTP, a mensagem de erro (quando houve) e a resposta bruta que o sistema externo devolveu.

É por aí que você diagnostica: um erro de autenticação, uma URL errada, um campo faltando no corpo da requisição. Com a resposta bruta em mãos, dá para corrigir a configuração da API no passo (ou os dados enviados) e reexecutar.

Não. Respostas e prompts muito grandes vêm truncados apenas na exibição do relatório, com um aviso do tipo "Exibindo os primeiros X de Y". O conteúdo completo não foi perdido — ele existe inteiro.

Para ter o texto completo, use o download da resposta do passo (o ícone ao lado de "Resposta"), que oferece formatos como HTML, CSV, XLSX, DOCX, JSON e TXT. O corte é só para a tela não ficar pesada; o dado real está preservado.

Significa que a resposta daquele passo foi revisada e alterada por uma pessoa — por exemplo, numa etapa de aprovação humana, alguém ajustou o resultado antes de o fluxo seguir. A versão editada é a que vale para os passos seguintes, não a original gerada pela IA.

É um indicador de rastreabilidade: mostra que aquele resultado passou por curadoria humana. Se algo depois parece diferente do que a IA produziria, esse selo explica o porquê.

A plataforma monitora as execuções e marca comportamentos fora do padrão como anomalia — por exemplo, uma resposta vazia, muito curta, ou um consumo/tempo fora do esperado. O aviso serve para chamar sua atenção àquela execução, que pode ter saído diferente do normal.

Não significa necessariamente falha grave: é um alerta para você conferir o resultado daquele passo. Abra os detalhes da execução para ver o que motivou a marcação e decidir se precisa reexecutar, dar feedback ou ajustar o agente.

Não use um número que já esteja ativo no WhatsApp pessoal ou no WhatsApp Business (app). Para conectar o agente, o número precisa estar na WhatsApp Business Platform (API) da Meta — e um número não pode estar, ao mesmo tempo, no app do WhatsApp e na API.

O recomendado é usar um número dedicado ao agente (por exemplo, um novo chip/linha), que você registra na plataforma da Meta para a API. Assim você não perde o uso pessoal de um número e evita conflito na hora de conectar.

O token que a Meta mostra direto na tela da API costuma ser temporário — ele expira em pouco tempo, o que derrubaria a conexão do seu agente. Por isso o guia orienta criar um Usuário de Sistema e gerar o token a partir dele: esse token é permanente (não expira), garantindo que o agente continue respondendo sem a integração cair.

Ou seja: use o Usuário de Sistema para ter um Access Token estável. Cole esse token no formulário de WhatsApp da plataforma (o campo Access Token). Se um dia precisar revogar, faça isso na própria Meta e gere um novo.

Sim. O Phone Number ID é o identificador daquele número específico na plataforma da Meta. Se você trocar o número usado pelo agente, o Phone Number ID também muda — e você precisa atualizar esse valor no formulário de WhatsApp da plataforma, senão o agente continua apontando para o número antigo.

Sempre que mexer no número na Meta, confira o Phone Number ID (no painel do Meta Business, na área de WhatsApp Business API) e atualize a configuração do agente.

MCP (Model Context Protocol) é um padrão que permite a um assistente de IA (como Claude, Cursor, VS Code, ChatGPT ou Gemini) conversar com um servidor externo e usar os recursos dele. O prototipe.ai oferece um servidor MCP: ao conectar seu assistente, ele passa a acessar e operar recursos do seu time na plataforma direto de dentro da ferramenta que você já usa.

Na prática, você trabalha no seu assistente favorito e ele consegue consultar e agir sobre seus agentes/fluxos da prototipe.ai, sem você precisar abrir a plataforma. A tela de Documentação do Servidor MCP reúne os dados de conexão e os atalhos para cada cliente.

Você usa os dados do servidor MCP do prototipe.ai em qualquer cliente que aceite configuração de MCP. Os três valores são:

- Nome do servidor: prototipeai

- Tipo (transport): http

- URL: https://www.prototipeai.com/mcp

Como aplicar, por cliente:

- Claude Code — no terminal, rode: claude mcp add --transport http prototipeai https://www.prototipeai.com/mcp

- Cursor / VS Code / Claude (app) / ChatGPT — cole os três dados acima na configuração de MCP do cliente (arquivos como .mcp.json, ~/.claude.json ou o settings do Cursor), no formato que cada um pede.

- Gemini CLI — use o comando de adicionar servidor MCP do próprio Gemini CLI com esses dados.

A tela de documentação traz o atalho pronto (com botão de copiar) para os clientes suportados; se o seu não estiver listado, monte a configuração manualmente com os três dados.

O acesso via MCP é escopado ao seu contexto de time na plataforma — o assistente opera dentro do que a sua conta/time permite, não a tudo indiscriminadamente. Ele usa a autenticação da conexão configurada.

Sobre autorizar a cada uso: depende do cliente. Alguns pedem uma autorização inicial e mantêm a conexão; outros confirmam ações sensíveis. Na dúvida, siga o comportamento padrão do seu assistente. Se precisar cortar o acesso, remova o servidor MCP na configuração do cliente.

Além de responder com IA, seu agente pode usar ferramentas para agir no mundo real e buscar informações. Você adiciona essas ferramentas em Ferramentas do Agente → Adicionar Nova Ferramenta ou Documento. As principais:

- Documento — consultar seus documentos (base de conhecimento/RAG).

- API — integrar com um sistema externo via API.

- Busca Web — buscar informações na internet em tempo real.

- Scraping de Site — extrair o conteúdo de páginas web.

- Calculadora — resolver contas com precisão.

- Gerar Link — transformar respostas em links de planilha ou documento.

- Gerar Imagem/Vídeo — criar imagens ou vídeos com IA.

- CRM Pessoa / CRM Empresa — memória de leads e empresas para fluxos de CRM.

- LinkedIn — perfis, empresas e vagas.

- Google — tendências e vagas via Google.

- Prompts Globais — gerenciar conhecimento compartilhado.

- Transf. para Humano — passar a conversa para um atendente.

Importante: cada agente usa uma ferramenta nativa por vez (documentos são a exceção — dá para ter vários). Para combinar capacidades diferentes, crie agentes separados dentro de um fluxo.

Você conecta seus próprios documentos ao agente com a ferramenta Documento — assim o agente responde consultando esse material (o que se costuma chamar de base de conhecimento / RAG). Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente e clique em Documento em "Adicionar Nova Ferramenta ou Documento".

2. Envie os documentos que o agente deve consultar.

3. Salve. A partir daí, o agente usa o conteúdo desses documentos para embasar as respostas.

Diferente das outras ferramentas, você pode adicionar vários documentos ao mesmo agente. Só lembre que documentos não se combinam com ferramentas nativas (como Busca Web ou CRM) no mesmo agente — se precisar das duas coisas, use agentes separados em um fluxo.

Use a ferramenta Busca Web — ela permite ao agente buscar informações atualizadas na internet em tempo real durante a conversa ou a execução. Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente.

2. Em "Adicionar Nova Ferramenta ou Documento", clique no card Busca Web.

3. Confirme para adicionar a ferramenta ao agente.

Pronto: quando a resposta depender de algo atual (uma notícia, um dado recente), o agente pesquisa na web e usa o resultado. É uma ferramenta nativa, então já vem pronta — você não precisa configurar chaves nem endpoints.

Use a ferramenta Scraping de Site — ela extrai o conteúdo de páginas web para o agente usar. Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente.

2. Em "Adicionar Nova Ferramenta ou Documento", clique no card Scraping de Site.

3. Confirme para adicionar a ferramenta.

Com ela, o agente consegue abrir uma página e trazer o texto/dados dela para a resposta. A diferença para a Busca Web: a Busca Web procura informações na internet; o Scraping lê o conteúdo de uma página específica. É uma ferramenta nativa, já pronta para uso.

Sim. Com a ferramenta Gerar Imagem/Vídeo, o agente cria imagens (e vídeos) com IA a partir do que for pedido. Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente.

2. Em "Adicionar Nova Ferramenta ou Documento", clique no card Gerar Imagem/Video.

3. Confirme para adicionar a ferramenta.

Depois disso, quando o usuário (ou o fluxo) pedir uma imagem, o agente a gera e entrega na resposta. É uma ferramenta nativa, então já vem integrada — sem necessidade de configurar serviços externos.

Sim. Com a ferramenta Gerar Link, o agente transforma a resposta em um arquivo para download por link — em planilha ou em documento Word. Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente.

2. Em "Adicionar Nova Ferramenta ou Documento", clique no card Gerar Link.

3. Escolha o tipo: Gerar Link - Planilha (converte os dados em XLSX para download) ou Gerar Link - Documento Word (converte o conteúdo em DOCX para download).

Assim, em vez de só texto na conversa, o agente entrega um link com o arquivo pronto para baixar.

Sim. Além de buscar na web, existe a ferramenta Google, voltada a recursos específicos do Google — como tendências (Google Trends) e vagas (Google Jobs). Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente.

2. Em "Adicionar Nova Ferramenta ou Documento", clique no card Google.

3. Confirme para adicionar a ferramenta ao agente.

Com ela, o agente consulta esses dados do Google durante a execução. É uma ferramenta nativa, já pronta para uso.

Sim. A ferramenta LinkedIn permite ao agente consultar perfis de pessoas, empresas e vagas no LinkedIn. Siga as etapas:

1. Na tela do agente, abra Ferramentas do Agente.

2. Em "Adicionar Nova Ferramenta ou Documento", clique no card LinkedIn.

3. Confirme para adicionar a ferramenta.

A partir daí, o agente pode buscar dados de perfis, empresas e vagas durante a execução — útil, por exemplo, em fluxos de recrutamento ou qualificação de leads.

Sim. Além de consultar perfis e vagas, a plataforma tem ferramentas para o agente publicar posts no LinkedIn — tanto em nome de uma pessoa quanto de uma empresa (organização).

Como funciona:

1. Na tela do agente, abra Ferramentas do Agente e selecione a ferramenta de publicação no LinkedIn.

2. Conecte a conta do LinkedIn (via OAuth) que fará a publicação.

3. Configure quem publica — o perfil de uma pessoa ou a página de uma organização que você administra.

Com isso, o agente ou o fluxo consegue publicar conteúdo automaticamente no LinkedIn como parte do processo. A publicação usa a conexão autorizada, então só sai em nome de contas/páginas às quais você tem acesso.

Sim. Mesmo sem integrar uma API do seu CRM externo, a plataforma tem um CRM próprio de memória para fluxos — as ferramentas CRM Pessoa e CRM Empresa. Elas guardam o histórico e os dados de cada lead/empresa, de modo que o agente responde de forma contextualizada, lembrando das interações anteriores daquele contato.

Como funciona:

1. Na tela do agente, abra Ferramentas do Agente.

2. Adicione CRM Pessoa (memória por lead/pessoa) e/ou CRM Empresa (memória por empresa).

3. Ao longo do fluxo, o agente registra e consulta esse histórico por lead automaticamente.

Assim, cada contato tem sua "ficha" mantida pela própria plataforma, garantindo continuidade e contexto nas respostas — sem depender de o seu CRM ter API.

Depende do tipo. A regra é: cada agente usa uma ferramenta nativa por vez — um agente com uma ferramenta nativa (Busca Web, CRM, Gerar Imagem etc.) não pode ter, ao mesmo tempo, outra ferramenta nativa nem uma API customizada nem documentos.

A exceção são os Documentos: você pode adicionar vários documentos ao mesmo agente.

Se você precisa combinar capacidades diferentes — por exemplo, um agente que busca na web e outro que consulta seu CRM — a forma certa é criar agentes separados dentro de um fluxo, cada um com sua ferramenta, encadeados na ordem que fizer sentido.

As duas dão poderes ao agente, mas em níveis diferentes de configuração:

- Ferramenta nativa — uma integração já pronta (Busca Web, CRM, LinkedIn, Gerar Imagem etc.). Você só seleciona e, em alguns casos, ajusta parâmetros básicos; a plataforma cuida do resto, sem endpoint nem autenticação para configurar.

- API customizada — para conectar qualquer sistema externo seu. Você configura o endpoint, o método, a autenticação e os parâmetros. É o caminho quando o que você precisa não é coberto por uma ferramenta nativa (ex.: o seu CRM ou ERP próprio).

Em resumo: se já existe uma ferramenta nativa para o que você quer, use-a (é mais simples); se é um sistema seu específico, use a API customizada.

São duas ferramentas de e-mail com focos diferentes:

- Email Analytics — traz métricas consolidadas de um conjunto de e-mails: totais, taxas de abertura, cliques e conversões por campanha. Use quando o agente precisa de uma visão agregada do desempenho.

- Email Individual — traz o histórico detalhado de e-mails de um contato específico: assunto, data e status (aberto, clicado etc.). Use em fluxos de follow-up ou nutrição, quando o agente precisa saber o que já foi enviado para aquele lead antes de compor a próxima mensagem.

Resumindo: Analytics responde "como está o desempenho geral?"; Individual responde "o que já mandamos para esta pessoa?".

Sim, são recursos diferentes, para situações diferentes:

- Transf. para Humano (handoff) — é uma ferramenta de agente conversacional: no meio de uma conversa, a IA pausa e passa o atendimento para uma pessoa (via Chatwoot ou Webhook). Serve para atendimento ao cliente — quando o usuário pede um humano ou a IA não deve seguir sozinha.

- Humano no Looping — é uma configuração de passo de fluxo (automação): a resposta daquele passo vai para uma fila de aprovação (em Tarefas / Painel de Revisão) antes de o fluxo continuar. Serve para revisar/aprovar resultados de processos em lote.

Resumindo: handoff é conversa ao vivo entregue a um atendente; Humano no Looping é aprovação de uma etapa antes de o fluxo seguir.

É uma proteção de segurança das ferramentas de CRM (Pessoa e Empresa) contra prompt injection. Quando ativada, o identificador do contato — o lead_id (ou lead_company_id, no CRM Empresa) — só é aceito a partir dos metadados da execução, e não do texto que o usuário digita.

Por que isso importa: sem essa proteção, alguém mal-intencionado poderia tentar, pela conversa, fazer o agente acessar os dados de outro lead ("me mostre os dados do cliente X"). Com a proteção ligada, o agente fica preso ao contato correto da execução, evitando que o ID seja manipulado pela mensagem.

Recomenda-se manter ligada em fluxos onde o usuário final conversa com o agente e há dados de CRM envolvidos.

Tudo o que precisa da sua aprovação fica reunido no Painel de Revisão (o "Humano no Loop"), acessível em Tarefas. Nele você:

1. Vê a lista de tarefas com ID, Nome, Time/Projeto, Responsável, Status e data de criação.

2. Usa as abas para filtrar por situação — Abertas, Abertas com auto-aprovação, Agendadas, Aprovadas e Arquivadas.

3. Refina com a busca e os filtros por Time, Projeto e Responsável.

Em cada tarefa há as ações Ver, Reprovar e Aprovar, direto na lista. Assim você acompanha e decide rapidamente tudo que os fluxos deixaram parado esperando um humano.

Quando um fluxo gera muitas tarefas de aprovação (por exemplo, um item por linha de uma planilha), você pode aprovar todas de uma vez em vez de uma por uma. Siga as etapas:

1. No Painel de Revisão (Tarefas), abra a tarefa "mãe" que agrupa os itens pendentes (clique em Ver).

2. Use o botão Aprovar todas de uma vez.

3. Confirme no aviso — a plataforma avisa quantas tarefas pendentes serão aprovadas de uma só vez.

Cada item é aprovado como se você tivesse aprovado individualmente, disparando a execução correspondente. É o caminho para não precisar clicar em Aprovar item a item quando há muitos.

Sim. É o recurso Humano no Looping — quando ativado num passo, a resposta daquele agente vai para aprovação humana antes de o fluxo continuar. Siga as etapas:

1. Nas Configurações do passo, abra o card Humano no Looping e clique em Editar.

2. Ative Aprovação Humana obrigatória. As respostas desse agente passam a exigir aprovação e ficam localizáveis em Tarefas (o Painel de Revisão).

3. Defina o que fazer em cada caso: Ao aprovar, ir para (por padrão, o próximo passo) e Ao reprovar, ir para.

4. Salve.

A partir daí, o fluxo pausa naquele ponto até alguém aprovar ou reprovar a resposta. Você pode ligar isso em quantos passos quiser.

Ao configurar o Humano no Looping de um passo, você define o que o fluxo faz quando a resposta é reprovada. Na opção "O que acontece se o humano reprovar?" há três caminhos:

- Fluxo é completamente abortado — a execução para ali.

- Fluxo prossegue considerando a resposta do humano — segue adiante usando o que o humano indicou.

- Fluxo prossegue sem considerar a resposta do humano — continua, ignorando o conteúdo da reprovação.

Você também define Ao reprovar, ir para (para qual passo o fluxo segue nesse caso). Assim, reprovar não é só "recusar": você controla exatamente o que acontece depois — parar, redirecionar ou seguir com ajustes.

Você configura condições no passo para o fluxo decidir, na hora da execução, se chama ou pula um agente. Siga as etapas:

1. Nas Configurações do passo, abra a seção de Orquestração de Agentes (condições de execução).

2. O assistente mostra qual é o próximo agente e pergunta se você deseja inserir condições. Escolha:

- Adicionar condição para CHAMAR agente — o passo só executa se a condição for verdadeira.

- Adicionar condição para PULAR agentes — o passo é ignorado quando a condição for atendida.

3. Defina a condição e salve. Ela aparece em Condições Salvas.

Assim o fluxo deixa de ser sempre linear: dependendo do resultado dos passos anteriores, ele chama ou pula determinados agentes.

Sim. As condições de orquestração podem se basear no conteúdo da resposta do agente — inclusive em texto livre — para decidir chamar ou pular o próximo passo. Siga as etapas:

1. Nas Configurações do passo, abra a Orquestração de Agentes.

2. Escolha Adicionar condição para CHAMAR agente ou Adicionar condição para PULAR agentes.

3. Monte a condição avaliando o que a resposta do agente contém — por exemplo, chamar o próximo passo apenas quando a resposta mencionar determinado resultado.

4. Salve; a condição fica listada em Condições Salvas.

Com isso, o caminho do fluxo se adapta ao que o agente efetivamente respondeu, e não só a valores fixos.

São dois lugares que controlam coisas diferentes do mesmo agente:

- Estúdio do agente — controla o agente em si: o prompt (instruções), o comportamento base, os testes. É a "identidade" do agente, independente de onde ele é usado.

- Configurações do passo (esta tela) — controla como aquele agente se comporta dentro deste fluxo: o que ele vê de contexto, o modelo naquele passo, quando pausa para aprovação humana, para onde manda a resposta, condições de execução, loopings, etc.

Resumindo: mexa no estúdio para mudar o que o agente é; mexa nas Configurações do passo para mudar como ele roda naquele ponto específico do fluxo.

Sim. Cada passo de fluxo tem configurações independentes. O mesmo agente pode, por exemplo, ter aprovação humana obrigatória em um fluxo e não ter em outro, usar um modelo em um passo e outro modelo em outro, ou receber contextos diferentes conforme o fluxo.

Isso é possível porque as Configurações do passo pertencem ao passo (àquele uso do agente no fluxo), não ao agente em si. Já o prompt do agente, que vive no estúdio, é compartilhado — se você quer instruções realmente diferentes, aí sim convém agentes separados.

Cada passo pode depositar a sua resposta numa memória compartilhada da execução, e passos posteriores podem consumir essa memória. É diferente de simplesmente ver a resposta do passo anterior: a memória de sessão acumula ao longo da execução e fica disponível para quem você escolher.

Nas Configurações do passo:

- Depositar na Memória de Sessão — ao ativar, a resposta deste agente é gravada na memória. Há modos: Acrescentar (soma ao que já havia) ou Substituir (troca o conteúdo).

- Consumir Memória de Sessão — o conteúdo acumulado é injetado no contexto deste agente, para ele usar o que os passos anteriores depositaram.

Use quando vários passos precisam construir um resultado em conjunto — um deposita, outro consome — em vez de depender só da resposta imediatamente anterior.

Porque as ferramentas nativas são exclusivas por agente: um agente que já tem uma ferramenta nativa (Busca Web, CRM, Gerar Imagem etc.) não aceita outra ferramenta nativa, nem API, nem documentos ao mesmo tempo. Do mesmo modo, documentos (RAG) e APIs também são mutuamente exclusivos no mesmo passo.

A exceção são os documentos entre si — vários documentos podem conviver no mesmo agente.

Se você precisa combinar capacidades (por exemplo, buscar na web e consultar seu CRM), crie passos/agentes separados no fluxo, cada um com a sua ferramenta. É por isso que, ao tentar marcar uma segunda ferramenta incompatível, a opção fica bloqueada.

Depende do comportamento de rejeição configurado no Humano no Looping daquele passo. As tarefas de aprovação aparecem em Tarefas (o Painel de Revisão); quando alguém rejeita, o fluxo pode:

- Abortar — a execução para ali.

- Prosseguir considerando a resposta do humano — segue usando o que a pessoa indicou.

- Prosseguir sem considerar — continua, ignorando o conteúdo da rejeição.

Há ainda o auto-retomar: se ninguém responder dentro de um tempo (timeout), o fluxo retoma sozinho sem esperar aprovação. Você define esses comportamentos na seção Humano no Looping do passo, junto com para qual passo ir ao aprovar ou reprovar.

Os dois fazem um passo se comunicar com outro fluxo, mas de formas diferentes:

- Agente no Looping — o passo envia a resposta para outro fluxo e aguarda o retorno antes de seguir. É de mão dupla e síncrono: o fluxo principal pausa naquele ponto até o fluxo secundário terminar e devolver o resultado (há um "passo de callback" que sinaliza o fim).

- Conectar Fluxo — em agentes conversacionais, é uma ferramenta que o agente aciona durante a conversa quando uma condição acontece, sem necessariamente travar a execução esperando.

Resumindo: use Agente no Looping quando o passo precisa do resultado de outro fluxo para continuar; use Conectar Fluxo quando o agente conversacional dispara um fluxo como uma ação.

O Looping de Verificações faz o passo checar automaticamente a própria resposta e, se ela não atender a uma condição, refazer ou seguir por um caminho de correção. Na prática:

1. O agente responde.

2. O sistema verifica se a resposta cumpre a condição que você definiu.

3. Se não cumpre, o fluxo pode voltar para um passo de destino em caso de falha (por exemplo, refazer ou ajustar) — repetindo até passar ou até um limite.

Configura-se na seção Looping de Verificações das Configurações do passo. É útil quando a qualidade da resposta é crítica e você quer uma checagem automática antes de o fluxo seguir adiante.

Na seção Modo de Processamento das Configurações do passo, você escolhe como o agente trata os dados recebidos. Os modos são exclusivos (só um ativo por vez):

- Item a Item — processa cada linha/registro separadamente. Há um limite de 100 itens por execução nesse modo.

- Subagrupamento — agrupa os dados (por exemplo, por um ID) e processa cada grupo; você define o destino do subagrupamento, ou seja, se os resultados de cada grupo seguem juntos ou separados no envio.

- Processar tudo — trata o conjunto como um único input.

Escolha conforme o volume e como o resultado deve ser entregado — item a item para casos independentes, subagrupamento quando várias linhas pertencem à mesma entidade.

Não. A Prototipaí se compromete, em caráter irrevogável, a não utilizar os dados do cliente — nem os dados de entrada nem o conteúdo gerado — para treinar, re-treinar ou aprimorar seus modelos de IA ou os modelos de IA dos sub-processadores (terceiros).

Ou seja, o que você e seus usuários enviam e o que os agentes produzem servem apenas para operar o serviço que você contratou, e não alimentam nenhum treinamento de modelo. Isso está previsto nos Termos de Serviço e na Política de Privacidade.

A Prototipaí assegura os direitos de titular previstos no art. 18 da LGPD — como confirmar o tratamento, acessar, corrigir, e solicitar a exclusão dos seus dados, de forma gratuita e a qualquer tempo.

Para exercer esses direitos (inclusive pedir exclusão), entre em contato com o Encarregado de Dados (DPO), Guilherme Putzeys, pelo e-mail dpo@prototipeai.com. Para garantir que você é mesmo o titular, pode ser solicitada uma comprovação de identidade.

Além disso, ao encerrar o contrato, você tem um prazo de 30 dias para exportar seus dados. Findo esse prazo, e não havendo solicitação de exportação, os dados são permanentemente eliminados ou anonimizados das bases — ressalvadas as hipóteses de guarda obrigatória previstas no art. 16 da LGPD.

A Prototipaí não compartilha seus dados pessoais com terceiros não autorizados. O compartilhamento acontece apenas com sub-processadores — parceiros que fornecem a infraestrutura essencial para a plataforma funcionar (por exemplo, provedores de nuvem e de modelos de IA).

Esse compartilhamento é feito sob Acordos de Processamento de Dados (DPAs), que garantem que esses parceiros também não utilizem os seus dados para fins próprios (como treinar modelos). Os detalhes e a lista de sub-processadores estão na Política de Privacidade completa.

As Memórias Globais permitem ao agente lembrar de informações sobre uma pessoa ou objeto específico independentemente de qual usuário está conversando. Elas são compartilhadas entre diferentes usuários, ao contrário da memória comum, que é separada por usuário.

Exemplo: um agente de saúde que guarda memórias sobre um paciente — essas informações ficam acessíveis a qualquer usuário que interaja sobre aquele paciente, não só a quem as registrou.

Quando usar: sempre que o agente precisa manter um histórico por entidade (paciente, cliente, sala, processo), e não por quem está falando. Sem memória global, cada usuário teria a sua própria memória isolada, e o agente não "lembraria" do que outro usuário registrou sobre a mesma entidade.

É uma opção que decide como as respostas vindas de APIs externas chegam ao usuário:

- Ativado — a resposta da API passa por uma camada de IA que a reescreve de forma mais natural e amigável antes de mostrar ao usuário. Bom quando a API devolve dados crus (JSON, códigos) que ficariam feios na conversa.

- Desativado — a resposta da API vai direto ao usuário, sem processamento. Bom quando a API já retorna um texto bem formatado e você não quer que a IA altere.

Escolha conforme a qualidade do que sua API devolve: ligue para "humanizar" respostas técnicas; desligue para preservar exatamente o que a API mandou.

Sim. O aviso amarelo "Agente em manutenção" significa que o agente está passando por um retreinamento/ajuste, mas continua disponível para uso. A única ressalva é que ele pode apresentar instabilidade temporária nesse período — respostas menos consistentes enquanto o ajuste não termina.

Se você depende de respostas estáveis para algo crítico, vale aguardar o aviso sair. Do contrário, pode continuar conversando normalmente.

Há dois motivos comuns, cada um com uma solução:

- O botão de enviar leva para a tela de assinaturas. Isso acontece quando o time não tem assinatura ativa — em vez de enviar a mensagem, o botão redireciona para a página de planos. Para usar o agente, é preciso ter um plano ativo.

- O campo de texto some e aparece um aviso. Isso ocorre quando o agente ainda tem requisitos pendentes (por exemplo, agentes que precisam ser separados/configurados antes de testar). Nesse caso, o campo é substituído por uma mensagem com link para o projeto — clique nele para concluir a configuração e depois volte a conversar.

Em resumo: sem assinatura ativa, o chat manda para os planos; com configuração pendente, ele manda para o projeto para você finalizar antes.

São dois jeitos de mandar dados para um fluxo, na tela de envio do orquestrador:

- Modo Orquestração Real — você configura como cada arquivo/entrada será tratado (com os seletores de orquestração), permitindo coordenar de fato o processamento de múltiplos arquivos/entradas em conjunto.

- Modo Simples — envio direto por cards de formato, sem a camada de orquestração. Bom quando você só quer processar o conteúdo sem coordenar várias fontes.

Escolha o Real quando precisa que o fluxo orquestre várias entradas juntas; use o Simples para um envio mais direto.

Esse aviso significa que, no meio do processamento, o sistema detectou uma falha, interrompeu o agente e o reajustou automaticamente — uma espécie de "recalibração" para corrigir o problema. O aviso mostra qual foi o número do treino/execução do agente.

O que fazer é simples: processe os dados novamente. Como o agente já foi reajustado, a nova tentativa tende a rodar corretamente. Se o aviso se repetir várias vezes com o mesmo conjunto de dados, vale revisar a configuração do agente ou falar com o suporte pela Clarice.

Sim. Assim como os prompts de agente, os prompts globais têm histórico de versões, então dá para voltar a um estado anterior. Siga as etapas:

1. Abra o prompt global em Detalhes do Prompt Global (pelo Ver na Biblioteca de Prompts Globais).

2. Clique em Histórico, no topo da tela.

3. Localize a versão que estava boa e restaure-a.

Como o prompt global é usado por vários agentes (quem o inclui com @nome_do_prompt), voltar a uma versão anterior conserta de uma vez todos os agentes afetados. Nada é perdido: as versões seguem no histórico, então você pode ir e voltar conforme precisar.

Por padrão, todos os prompts globais referenciados no agente entram em todas as conversas. As condições permitem incluir ou excluir um prompt específico dependendo de onde a conversa começou (a URL de origem). Assim você personaliza o comportamento por contexto — por exemplo, incluir um prompt de suporte só quando o usuário vem da página de suporte.

Cada condição tem um tipo:

- EXECUTAR — o prompt só é incluído se a URL contiver o trecho informado.

- PULAR — o prompt é removido se a URL contiver o trecho.

O trecho da URL é qualquer parte que identifique a origem: um parâmetro (ex.: feedback_id), um pedaço do caminho (ex.: /briefing), uma query string (ex.: projeto=marketing) ou um domínio. A verificação é por substring — se o trecho aparecer em qualquer posição da URL, a condição é ativada.

Se você não vê nenhum prompt global aqui, é porque o agente ainda não referencia nenhum prompt global no texto das instruções (com @nome_do_prompt) — só aparecem condições para prompts que o agente de fato usa.

Prompts globais são trechos de instrução reutilizáveis, disponíveis para todos os agentes do seu time. Em vez de repetir a mesma regra em vários agentes, você a escreve uma vez como prompt global e a inclui onde precisar.

Como usar:

1. Acesse a Biblioteca de Prompts Globais. Ali ficam todos os prompts do time, com nome, categoria, status e nº de caracteres.

2. Crie um novo em Novo Prompt Global ou edite um existente.

3. Para incluir um prompt global nas instruções de um agente, escreva @nome_do_prompt no texto das instruções — o conteúdo do prompt global entra ali.

A grande vantagem: quando você atualiza o prompt global, a mudança se reflete em todos os agentes que o utilizam. É a forma de manter regras e conhecimento padronizados e fáceis de manter em um só lugar.

Antes de editar um prompt global, vale conferir onde ele é usado, para não impactar agentes sem querer. Siga as etapas:

1. Na Biblioteca de Prompts Globais, localize o prompt e clique em Ver (na coluna Ações) para abrir os Detalhes do Prompt Global.

2. No detalhe, você vê o nome do prompt (ex.: @nome_do_prompt), a categoria, o conteúdo e onde ele se aplica. Como os agentes incluem o prompt escrevendo @nome_do_prompt nas instruções, é esse nome que indica o vínculo.

3. Se precisar rastrear os agentes que o usam, procure pelo @nome_do_prompt na busca de conteúdo de agentes (a busca por "conteúdo do agente" encontra as instruções que citam aquele prompt).

Assim você entende o alcance da mudança antes de editar — lembrando que alterar o prompt global reflete em todos os agentes que o incluem.

Tudo isso fica no Quadro Colaborativo da sala de discovery (acessível pelo botão do Quadro na sala). Ele tem abas:

- Post-its — um mural onde você cria post-its (escolhendo a cor antes de criar), arrasta para reorganizar e apaga quando quiser. Serve para mapear ideias e requisitos visualmente.

- Notas da Reunião — as anotações geradas a partir da conversa com a Esther ficam registradas aqui.

- Transcrição — o texto da conversa por voz com a Esther aparece nesta aba.

Sobre o Miro: há o botão Conectar Miro no quadro, mas essa integração é exclusiva do plano Enterprise — ao tentar autorizar em outro plano, aparece a tela de upgrade. Com o Enterprise, você integra o quadro ao Miro que o time já usa.

Sim. Na tela Email Senders (nas configurações do time) você cadastra remetentes próprios, para que os e-mails saiam com o seu endereço/domínio em vez de um padrão da plataforma. Siga as etapas:

1. Vá em Configurações do time → Email Senders.

2. Adicione um novo remetente informando o nome e o e-mail que deseja usar.

3. Conclua a verificação do remetente — é o passo que comprova que você tem direito de enviar por aquele endereço/domínio (a lista mostra a data de verificação de cada remetente).

Depois de verificado, os e-mails enviados pelos seus agentes/fluxos podem usar esse remetente, saindo com a identidade da sua empresa. Sem a verificação, o remetente não fica disponível para uso.

Cada chave de API tem um limite de 500 requisições por hora por padrão. Além disso existe um limite por time, igual a 10× o limite da chave (por padrão, 5.000 requisições por hora somando todas as chaves do time).

Se você estourar qualquer um dos dois, a API responde com erro 429 (rate limit exceeded), indicando se o estouro foi da chave ou do time. Basta aguardar a janela de 1 hora reabrir. Se você precisa de um teto maior de forma recorrente, fale com o suporte para avaliar o ajuste do limite da sua chave.

A API do LLM Gateway valida o tamanho do que você envia:

- No máximo 200 mensagens por requisição (o array messages). Acima disso vem erro pedindo para reduzir.
- No máximo 500 mil caracteres (~500 KB) por mensagem, no campo content.
- Cada mensagem precisa ter um role válido: user, system, assistant ou tool. Qualquer outro valor é recusado.
- model e um messages não-vazio são obrigatórios.

Se estourar qualquer um desses, a API devolve 400 (invalid_request_error) apontando exatamente qual mensagem e qual limite foi excedido.

Ainda não. Se você enviar stream: true na requisição, a API recusa com uma mensagem pedindo para remover essa opção. Faça a chamada sem stream e receba a resposta completa de uma vez.

A plataforma expõe um servidor MCP, que permite conectar seu assistente de IA (como o Claude ou o Cursor) ao seu time e operar a prototipe.ai de lá. Você configura em Conectar via MCP, nas configurações do time.

Como fazer:

1. Vá em Configurações do time → Conectar via MCP.

2. Use os Dados do servidor MCP em qualquer cliente que aceite configuração manual (arquivos como .mcp.json, ~/.claude.json ou o settings.json do Cursor): Nome do servidor, Tipo (transport) e URL. Há um botão Copiar em cada valor.

3. Se o seu cliente estiver listado, use o atalho pronto — por exemplo, em Uso o Claude Code, copie e cole no terminal o comando claude mcp add --transport http prototipeai <URL>. Há também atalhos para outros clientes.

Depois de conectado, seu assistente passa a acessar os recursos do time via MCP. Se o seu cliente não aparecer na lista, monte a configuração manualmente com os três dados do servidor.

Você convida novos membros pela tela de Membros do Time, nas configurações do time. Siga as etapas:

1. Vá em Configurações do time → Membros.

2. No bloco Convidar Novos Membros, preencha o Nome do Usuário e o Email da pessoa.

3. Escolha o Papel no Time (Owner, Admin, Member ou Auditor).

4. Clique em Enviar Convite.

A pessoa recebe um e-mail de convite e, ao aceitar, entra no time com o papel escolhido. Em Convites enviados você acompanha os convites pendentes. Importante: o convite é amarrado ao e-mail informado — a pessoa precisa entrar/cadastrar-se com esse mesmo e-mail.

Ao adicionar alguém ao time, você escolhe um papel. Os papéis são:

- Owner (Proprietário) — controle total do time, incluindo membros, configurações e cobrança.

- Admin — administra o time e os projetos (normalmente tudo, menos ações mais sensíveis reservadas ao Owner).

- Member (Membro) — trabalha nos agentes conforme as permissões concedidas ao papel.

- Auditor — voltado a testar e dar feedback, sem alterar configurações.

O que cada papel efetivamente pode fazer com os projetos (visualizar, editar, gerenciar, excluir) é configurável na tela Permissões de Projetos — lá você liga/desliga cada permissão por papel. Assim, os papéis são a base, e as Permissões de Projetos ajustam o detalhe.

A remoção de um membro é feita na tela de Membros do Time. Siga as etapas:

1. Vá em Configurações do time → Membros.

2. Em Membros Ativos, localize a pessoa que quer remover.

3. Use a ação de remover/desativar o membro no item correspondente e confirme.

A pessoa perde o acesso ao time. Só quem tem papel de gestão (Owner/Admin) consegue remover membros. Se precisar apenas mudar o que a pessoa pode fazer, em vez de removê-la, ajuste o papel dela ou as Permissões de Projetos.

Você conecta o Slack ou o Microsoft Teams na tela de Notificações, nas configurações do time — assim as notificações da plataforma são enviadas para um canal da sua equipe. Siga as etapas:

1. Vá em Configurações do time → Notificações.

2. Conecte a integração desejada (Slack ou Teams) e configure o canal para onde as mensagens devem ir.

3. Marque a opção correspondente (Slack e/ou Microsoft Teams) para ativar o envio.

Observações importantes: o canal precisa estar configurado antes de ativar a opção — enquanto não houver canal, ela fica indisponível. Além disso, essa integração de notificações por canal é um recurso Enterprise; se as opções aparecerem desabilitadas, o time precisa desse plano.

O consumo de créditos do time fica na tela Uso de Créditos, nas configurações do time. Nela você acompanha:

1. Seus créditos — quanto foi consumido e quanto ainda resta do total.

2. Créditos consumidos, eventos processados e média por dia, para entender o ritmo de uso.

3. Um filtro por período (este mês, últimos 7/30/90 dias ou um intervalo de datas) para ver o consumo no recorte que interessa.

Como usar: vá em Configurações do time → Uso de Créditos, escolha o período e clique em Filtrar. Assim você monitora quanto o time está gastando e planeja o uso. Lembre que rodar agentes, testes e execuções consome créditos — é aqui que você vê o total.

Você personaliza a identidade visual do seu time na tela White Label, nas configurações do time. Hoje é possível definir o logo do time. Siga as etapas:

1. Vá em Configurações do time → White Label.

2. Na seção Logo do Time, clique em Escolher arquivo e selecione a imagem do seu logo.

3. Clique em Salvar.

Formatos aceitos: PNG, JPG ou SVG, com tamanho recomendado de 200×100px. Com o logo definido, a identidade do seu time passa a aparecer no lugar do padrão, deixando a experiência com a cara da sua empresa.

Você. O cliente retém todos os direitos, títulos e interesses sobre os dados de entrada e o conteúdo gerado (output) — a Prototipaí não reivindica propriedade sobre nada que você cria na plataforma.

Para efeito de LGPD, você é o Controlador dos seus dados e a Prototipaí atua apenas como Operadora, processando esses dados em seu nome e sob as suas instruções. A propriedade intelectual da própria plataforma (software, marca, etc.) é da Prototipaí, e você recebe uma licença de uso — mas o conteúdo que você produz é seu.

Não. Os Termos de Serviço trazem uma proibição irrevogável de treinamento de IA: a Prototipaí se compromete a não usar os dados do cliente (entrada nem output) para treinar, re-treinar ou aprimorar os próprios modelos de IA ou os dos sub-processadores.

Além disso, os provedores de modelos de IA usados por trás (como Google, OpenAI) operam sob acordos de Zero Data Retention — eles não retêm nem usam os seus dados para fins próprios. Seu conteúdo serve só para operar o serviço que você contratou.

Ao encerrar ou rescindir o contrato, você tem um prazo de 30 dias para exportar seus dados da plataforma.

Findo esse prazo, e não havendo solicitação de exportação, os dados são permanentemente eliminados ou anonimizados das bases da Prototipaí — ressalvadas apenas as hipóteses de guarda obrigatória previstas em lei (art. 16 da LGPD, como cumprimento de obrigação legal ou regulatória).

Se precisar exportar antes de cancelar, faça a solicitação dentro desse prazo pelo canal de suporte ou pelo DPO (dpo@prototipeai.com).

Se aparece o aviso "Convites não são permitidos para o seu time pessoal", é porque você está no seu time pessoal — e times pessoais não aceitam convites de outros membros (são individuais, de uma pessoa só).

Para convidar outras pessoas, você precisa de um time não pessoal (um time de trabalho/organização). Nesse tipo de time, a seção Convidar Novos Membros fica disponível e você adiciona pessoas informando nome, e-mail e papel.

Se você tem mais de um time, use o seletor de time para trocar do pessoal para o time de trabalho antes de convidar.

Você conecta seu agente a um número de WhatsApp Business para que ele receba e responda mensagens automaticamente. Siga as etapas:

1. No agente, clique em Publicar e abra a aba WhatsApp ("Conectar WhatsApp Business").

2. Como funciona, em resumo: (1) configure sua conta WhatsApp Business na Meta, (2) cole as credenciais aqui, (3) o agente começa a responder automaticamente.

3. Clique em Conectar WhatsApp e preencha as credenciais pedidas.

Há um Ver passo a passo detalhado na própria tela para orientar a configuração na Meta. Suas credenciais são criptografadas e armazenadas com segurança. Depois de conectado, quem mandar mensagem para aquele número conversa direto com o seu agente.

Para conectar o WhatsApp, o formulário pede três dados, todos obtidos no Meta (a plataforma da Meta para WhatsApp Business):

- Phone Number ID — é o identificador do número. Você o encontra no painel do Meta Business, na área de WhatsApp Business API.

- Access Token — o token de acesso, gerado no Meta for Developers, para a sua aplicação. É ele que autoriza a plataforma a enviar/receber mensagens.

- Webhook Verify Token — um token único de verificação do webhook; você pode gerar um seguro ali mesmo no formulário.

Copie cada um do Meta e cole no campo correspondente. Se tiver dúvida em algum passo da Meta, use o Ver passo a passo detalhado na tela de conexão do WhatsApp.

É o badge de notificação global — um aviso que aparece sozinho na tela quando você tem uma notificação pendente, mostrando a mais recente. Ele só surge quando há algo pendente; sem notificação, não aparece.

Ele é diferente do sino da navbar: o sino guarda a lista completa de todas as suas notificações, para você consultar quando quiser; o badge flutuante é o aviso proativo da notificação pendente do momento, para você não perdê-la. Ao lidar com a notificação (abrir/resolver), o badge some.

A Clarice é a copilota da plataforma — ela fica no balão de ajuda (💬) no canto inferior direito, disponível em qualquer tela do seu time. Ela é mais do que um chat de dúvidas: além de responder perguntas sobre a plataforma, ela opera o agente por você.

O que a Clarice faz:

1. Tira dúvidas sobre como usar a plataforma, com o contexto da tela em que você está.

2. Ajusta o agente a seu pedido — mexe no prompt e nas configurações sem você precisar editar tudo na mão. Basta descrever o que quer ("deixe as respostas mais curtas", "acrescente tal regra").

3. Atende por texto (campo "Peça um ajuste à Clarice.") ou por voz (Toque para conversar).

Se você vê o balão preto no canto da tela, é sinal de que seu time tem a copilota habilitada. Ela foi feita para te ajudar tela a tela, com contexto, sem você sair de onde está.

A ferramenta 🤝 Transf. para Humano permite que o agente de IA pause a conversa e passe o atendimento para um operador humano dentro do Chatwoot. Quando o operador resolve o ticket, a IA volta a responder automaticamente.

Esta integração funciona em dois sentidos:

• Prototipe.ai → Chatwoot: cria o ticket e envia mensagens do usuário enquanto a IA está pausada.


• Chatwoot → Prototipe.ai: entrega as mensagens do operador humano pra você responder no canal original (WhatsApp, web, etc.) e detecta quando o ticket foi resolvido pra reativar a IA.

A configuração tem 6 etapas, todas rápidas (cerca de 10 minutos no total).

Pré-requisito

• Acesso de Administrador ao Chatwoot


• O step do Prototipe.ai onde a tool será adicionada

---

Etapa 1 — Crie a Inbox API no Chatwoot

A Inbox API é onde os tickets vão aparecer pros operadores.

1. No Chatwoot, vai em Settings → Inboxes → Add Inbox.


2. Escolhe o canal API (ícone de chave inglesa).


3. Preenche:
   
   
   
   • Channel Name: Prototipe.ai (ou o nome que preferires)
   
   
   • Webhook URL: deixa qualquer placeholder por enquanto, ex: https://exemplo.com/temp — você atualiza no final.
   
   
   
   


4. Clica Create Inbox.


5. Na tela seguinte (Add Agents), seleciona quem deve receber esses tickets e clica Add Agents.


6. Pula o último passo ("Voilà").

⚠️ Anota o Inbox ID: depois de criar a inbox, abre ela e olha a URL do navegador — o número que aparece depois de /inbox/ é o teu Inbox ID.

Exemplo: em https://app.chatwoot.com/app/accounts/12/inbox/47 o Inbox ID é 47.

Importante: o token inbox_identifier (string longa tipo u95NU7Bb7NeYKPgoxd1JoniV) que aparece na configuração da inbox não é o Inbox ID — aquele token serve pra outra coisa (SDK público de chat). Use o número da URL.

---

Etapa 2 — Identifique o Account ID e a Base URL

Account ID: na mesma URL da Etapa 1, o número depois de /accounts/.

https://app.chatwoot.com/app/accounts/12/inbox/47

 ↑

 Account ID = 12

Base URL: o domínio raiz do teu Chatwoot, sem barra no final.

• Chatwoot Cloud: https://app.chatwoot.com


• Self-hosted: https://chatwoot.suaempresa.com

---

Etapa 3 — Crie um Agent Bot pra obter o Access Token

⚠️ Recomendamos usar Agent Bot em vez do teu token pessoal. Vantagens:

• Não fica atrelado a uma pessoa específica (sobrevive a saídas/desligamentos da equipe).


• Tem escopo limitado às inboxes onde for atribuído.


• Funciona como uma "conta de serviço" identificável nos logs.

Como criar:

1. Vai em Settings → Integrations → Agent Bots.


2. Clica em New Agent Bot.


3. Preenche:
   
   
   
   • Bot Name: Prototipe.ai Handoff
   
   
   • Description: Integração com Prototipe.ai para transferência humana
   
   
   • Bot URL: deixa em branco.
   
   
   
   


4. Clica Create.


5. Copia o Access Token que aparece — em algumas versões ele só é exibido uma vez. Guarda em local seguro.

Atribui o bot à inbox criada na Etapa 1:

1. Settings → Inboxes → Prototipe.ai (a inbox que criaste)


2. Vai na aba Bot Configuration


3. Seleciona o bot Prototipe.ai Handoff


4. Clica Update

💡 Alternativa: se preferires usar o token pessoal, vai em Profile Settings (clica no teu avatar → Profile Settings) e copia o Access Token da seção homônima. Funciona, mas considera as desvantagens acima.

---

Etapa 4 — Cria a tool 🤝 Transf. para Humano no Prototipe.ai

1. No Prototipe.ai, abre o step do agente onde a tool será adicionada.


2. Clica em Adicionar Nova Ferramenta.


3. Seleciona o card 🤝 Transf. para Humano.


4. Clica Continuar.


5. Preenche o form:
   
   
   
   • Plataforma: Chatwoot
   
   
   • Base URL: a URL da Etapa 2 (ex: https://app.chatwoot.com)
   
   
   • Account ID: o número da Etapa 2 (ex: 12)
   
   
   • Inbox ID: o número da Etapa 1 (ex: 47)
   
   
   • Access Token: o token da Etapa 3
   
   
   
   


6. Clica Confirmar.

A tool é criada e fica visível na seção External Sources do step.

---

Etapa 5 — Pega a URL inbound e cola no Chatwoot

Agora fechamos o ciclo: o Chatwoot precisa saber pra onde mandar as mensagens do operador humano e os eventos de status.

1. No Prototipe.ai, na seção External Sources do step, clica Editar no card 🤝.


2. Vai aparecer um campo amarelo destacado com a URL inbound completa, no formato:
   

   https://app.prototipeai.com/api/v1/integrations/chatwoot/webhooks/<id>?t=<token>

   
   


3. Copia essa URL inteira (incluindo ?t=<token>).

No Chatwoot, configura o webhook — escolhe uma das duas opções:

Opção A (recomendada): Webhook da própria Inbox

1. Settings → Inboxes → Prototipe.ai → aba Configuration


2. No campo Webhook URL, cola a URL copiada


3. Clica Update

Vantagem: o webhook só dispara para essa inbox específica.

Opção B: Webhook account-level

1. Settings → Configurations → Webhooks → Add new webhook endpoint


2. Endpoint: cola a URL copiada


3. Subscriptions: marca apenas
   
   
   
   • ✅ message_created
   
   
   • ✅ conversation_status_changed
   
   
   
   


4. Clica Add

---

Etapa 6 — Atualiza o prompt do agente

Pra IA saber quando chamar a transferência, adiciona no prompt do agente:

Você tem disponível a ferramenta "Transf. para Humano".


Use quando:

- O usuário pedir explicitamente para falar com humano

- Demonstrar frustração extrema ou repetida

- Em casos críticos/sensíveis fora do teu escopo

Após chamar a ferramenta, NÃO continue respondendo. Aguarde o operador humano assumir.

---

Como testar se funcionou

1. No canal do agente (WhatsApp, widget, etc.), envia: "quero falar com humano por favor".


2. No Chatwoot, um novo ticket aparece na inbox Prototipe.ai.


3. No canal do agente, aparece a mensagem: "Sua solicitação foi recebida. Em instantes um atendente humano vai responder por aqui."


4. No Chatwoot, o operador responde no ticket.


5. No canal do agente, a resposta do operador chega como se fosse o agente.


6. No Chatwoot, o operador clica em Resolved quando terminar.


7. No canal do agente, a próxima mensagem volta a ser respondida pela IA.

---

Problemas comuns

O ticket não aparece no Chatwoot

• Confere se o Access Token tá correto e o Agent Bot foi atribuído à inbox.


• Confere se o Account ID e Inbox ID são os números da URL, não o inbox_identifier (string).

A mensagem do operador não chega no canal do usuário

• Confere se a Webhook URL no Chatwoot está exatamente igual ao campo amarelo do Prototipe.ai (incluindo o ?t=.).


• Confere se o webhook tem message_created marcado.

A IA continua respondendo mesmo depois da transferência

• Verifica se a tool foi mesmo criada como Transf. para Humano.


• Espera 5 segundos (cache do projeto pode estar ainda válido).

O ticket não fecha quando o operador resolve

• Confere se conversation_status_changed está marcado nas subscriptions do webhook.

---

Segurança e boas práticas

• O Access Token deve ter escopo mínimo. Use Agent Bot em vez do token pessoal de admin.


• O token inbound (?t=.) é gerado automaticamente pelo Prototipe.ai e validado a cada requisição. Nunca compartilhes essa URL publicamente.


• Em produção, todas as URLs devem ser HTTPS — o Prototipe.ai bloqueia automaticamente URLs apontando pra redes privadas (RFC1918, loopback, link-local).

---

Não usa Chatwoot? Veja a FAQ "Como integrar Transferência Humana via Webhook Genérico (HMAC + API REST)" para integrar com Crisp, Zendesk, n8n, dashboard próprio, etc.

A plataforma Webhook Genérico (HMAC) é a opção pra integrar a Transferência Humana com qualquer sistema que não tenha adapter dedicado: Crisp, Zendesk, Freshdesk, Intercom, n8n, dashboards internos, etc.

Diferente do Chatwoot (que tem integração bidirecional pronta), no Generic Webhook você implementa as duas pontas:

• Prototipe.ai → tua plataforma: recebes eventos via webhook HTTP POST assinado com HMAC-SHA256.


• Tua plataforma → Prototipe.ai: chamas nossa API REST com Bearer token pra pausar a IA, mandar mensagens do operador e devolver controle.

Quando usar Generic Webhook vs Chatwoot

• Use Chatwoot se você quer uma solução pronta de atendimento humano (UI de tickets, agentes, SLA, relatórios) e não quer escrever código.


• Use Generic Webhook se você já tem uma plataforma de atendimento, um dashboard interno ou quer orquestrar via n8n/Zapier. Você controla a UX do operador no teu lado.

---

Visão geral do ciclo

1. A IA decide transferir → Prototipe.ai pausa a conversa e dispara webhook conversation.handed_off pra teu endpoint.


2. Tua plataforma recebe o evento, valida o HMAC, abre um ticket/notifica o operador.


3. Enquanto a IA estiver pausada, cada mensagem nova do usuário dispara message.created no teu endpoint.


4. O operador humano responde no teu lado → você chama POST /agent_messages na nossa API → a mensagem chega no canal do usuário (WhatsApp/widget).


5. Quando o operador encerrar, você chama POST /resume → IA volta a responder. Prototipe.ai dispara conversation.resumed de volta pra confirmar.

---

Etapa 1 — Crie a API Key (autenticação inbound)

Pra tua plataforma chamar nossa API, precisa de uma API Key com permissão handoff.

1. No Prototipe.ai, abre Configurações do Time → API Keys.


2. Clica Nova API Key.


3. Preenche:
   
   
   
   • Nome: Integração HITL — <tua plataforma>
   
   
   • Permissões: marca handoff (obrigatório).
   
   
   • Acesso a projetos: seleciona o projeto onde a tool 🤝 vai rodar.
   
   
   
   


4. Salva e copia o token retornado — ele só aparece uma vez.

⚠️ Importante: API Keys criadas pela UI são team-scoped (têm acesso a vários projetos do time). Por isso, todas as chamadas precisam informar ?slug=<slug-do-projeto> na query string. O slug aparece na URL do projeto.

❌ Não funciona com Generic Webhook:

• API Keys flow-scoped (atreladas a um automation_flow específico) — bloqueadas pra prevenir escalada de escopo. Use team-scoped ou project-scoped.

---

Etapa 2 — Cria a tool 🤝 Transf. para Humano

1. No step do agente, clica Adicionar Nova Ferramenta.


2. Seleciona o card 🤝 Transf. para Humano e clica Continuar.


3. No form:
   
   
   
   • Plataforma: Webhook Genérico (HMAC)
   
   
   • URL do webhook externo: a URL do teu endpoint que vai receber os eventos. Ex: https://api.minhaplataforma.com/webhooks/prototipai. Precisa ser HTTPS público (bloqueamos IPs privados/loopback automaticamente por SSRF).
   
   
   • Segredo HMAC: cola um segredo ou usa o botão gerar pra criar um aleatório. Guarda esse segredo no teu lado — é com ele que você vai verificar a assinatura.
   
   
   • Headers extras (JSON, opcional): se teu endpoint exige headers custom (ex: tenant ID, auth secundária), informa como JSON. Ex: {"X-Tenant-Id": "abc-123"}.
   
   
   
   


4. Clica Confirmar.

---

Etapa 3 — Implementa o endpoint que recebe os webhooks

Eventos enviados pelo Prototipe.ai

Todos chegam como POST no endpoint_url que você configurou, com Content-Type: application/json. O body sempre tem o formato:

{

 "event": "conversation.handed_off".

 "delivered_at": "2026-05-10T22:30:00-03:00".

 "data": {. }

}

Eventos possíveis:

• conversation.handed_off — IA pausada. data traz conversation, agent_ref (se houver), reason (se houver).


• conversation.resumed — controle devolvido pra IA. data traz conversation e previous_agent_ref.


• message.created — usuário mandou mensagem nova com a IA pausada. data traz conversation e message.

Headers em cada POST

• X-Prototipai-Event: nome do evento (redundante com body.event, útil pra roteamento rápido).


• X-Prototipai-Delivery: UUID único da entrega. Use pra idempotência — se receber o mesmo UUID duas vezes, ignora a segunda (acontece em retries).


• X-Prototipai-Signature: assinatura HMAC-SHA256 do body cru usando o segredo configurado.

Validação da assinatura HMAC

Ruby:

expected = OpenSSL::HMAC.hexdigest('sha256', SEGREDO, request.raw_post)

received = request.headers['X-Prototipai-Signature']

unless Rack::Utils.secure_compare(expected, received.to_s)

 head :unauthorized and return

end

Node.js:

const crypto = require('crypto');

const expected = crypto.createHmac('sha256', SEGREDO).update(rawBody) // bytes crus, ANTES de JSON.parse.digest('hex');

const ok = crypto.timingSafeEqual(

 Buffer.from(expected).

 Buffer.from(req.headers['x-prototipai-signature'] || '')

);

if (!ok) return res.status(401).end();

Python:

import hmac, hashlib

expected = hmac.new(SEGREDO.encode(), raw_body, hashlib.sha256).hexdigest()

received = request.headers.get('X-Prototipai-Signature', '')

if not hmac.compare_digest(expected, received):

 abort(401)

⚠️ Cuidados:

• Use o body cru (raw bytes) na assinatura, não o JSON re-serializado.


• Use comparação constant-time (secure_compare / timingSafeEqual / hmac.compare_digest) pra evitar timing attacks.


• Responde rápido (< 10s). Demora além disso conta como timeout.

Retry / response codes

• 2xx → entrega marcada como sucesso.


• 4xx (exceto 429) → não retentamos. Assumimos bug permanente no teu lado.


• 5xx ou 429 → retentamos com backoff exponencial via Sidekiq.

---

Etapa 4 — Implementa a chamada à nossa API REST

Todos os endpoints exigem:

• Authorization: Bearer <TOKEN> (a API Key da Etapa 1)


• ?slug=<slug-do-projeto> na query string

POST /api/v1/conversations/:id/handoff — pausa a IA

POST /api/v1/conversations/:id/handoff?slug=<slug>

Authorization: Bearer <TOKEN>

Content-Type: application/json


{

 "agent_ref": "maria@empresa.com".

 "reason": "cliente irritado, escalando"

}

Ambos os parâmetros (agent_ref, reason) são opcionais. Útil quando você quer disparar o handoff do teu lado (ex: regra de negócio), sem depender da IA decidir.

POST /api/v1/conversations/:id/agent_messages — operador responde

POST /api/v1/conversations/:id/agent_messages?slug=<slug>

Authorization: Bearer <TOKEN>

Content-Type: application/json


{

 "content": "Oi, sou a Maria! Como posso ajudar?".

 "agent_ref": "maria@empresa.com"

}

content obrigatório (máx 8.000 caracteres). A conversa precisa estar em handoff (chame /handoff antes, ou a IA chamou a tool). A mensagem entra no canal original do usuário automaticamente.

POST /api/v1/conversations/:id/resume — devolve pra IA

POST /api/v1/conversations/:id/resume?slug=<slug>

Authorization: Bearer <TOKEN>

Sem body. A IA volta no mesmo estado em que estava antes do handoff (preservamos o lookahead_state automaticamente).

GET /api/v1/conversations/:id/poll — alternativa ao webhook

GET /api/v1/conversations/:id/poll?slug=<slug>&since=2026-05-05T12:00:00Z

Authorization: Bearer <TOKEN>

Retorna até 100 mensagens criadas após since (ISO8601). Suporta ETag/If-None-Match — se nada mudou desde a última chamada, retorna 304 Not Modified sem pesar o banco. Use polling se receber webhooks for inviável (ex: ambiente sem URL pública).

---

Exemplo completo (curl, fluxo do operador)

TOKEN='cole-a-key-aqui'

CONV=123

SLUG='meu-projeto-slug'

BASE='https://app.prototipeai.com'


# 1) Pausa a IA (opcional — a tool da IA já faz isso automaticamente)

curl -X POST "$BASE/api/v1/conversations/$CONV/handoff?slug=$SLUG" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"agent_ref":"maria@x.com","reason":"teste"}'

# 2) Operador responde

curl -X POST "$BASE/api/v1/conversations/$CONV/agent_messages?slug=$SLUG" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"content":"Oi, sou a Maria!","agent_ref":"maria@x.com"}'

# 3) Devolve pra IA

curl -X POST "$BASE/api/v1/conversations/$CONV/resume?slug=$SLUG" -H "Authorization: Bearer $TOKEN"

---

Polling vs Webhook — qual usar?

• Webhook (recomendado): tempo real, baixo custo. Requer endpoint público HTTPS.


• Polling: simples de implementar, funciona em qualquer ambiente. Latência depende do intervalo (recomenda-se 5-10s). Cuidado com rate limit.


• Híbrido: webhook como primário, polling como fallback se você suspeitar de eventos perdidos.

---

Erros comuns

• 401 Token de autenticação não fornecido → faltou o header Authorization: Bearer ….


• 401 Token inválido → key errada, expirada ou revogada.


• 401 Projeto não é válido → faltou o ?slug= na query string (team-scoped key precisa).


• 403 API key não possui permissão handoff → recria a key marcando a permissão handoff.


• 403 API key flow-scoped não pode usar handoff → use uma key team-scoped (com slug) ou project-scoped.


• 409 Conversa já está em handoff → tentou pausar uma conversa já pausada. Trate como idempotente no teu lado.


• 409 Conversa não está em handoff → tentou mandar mensagem ou resume em conv ainda controlada pela IA.


• 404 Conversa não encontrada → o :id não existe ou não pertence ao projeto do slug.


• 400 content é obrigatório / content excede 8000 caracteres → ajusta o payload.

---

Segurança e boas práticas

• Nunca exponha a API Key no frontend. Use no backend, com proxy se precisar.


• Rotaciona o segredo HMAC periodicamente (ou se houver suspeita de vazamento). Edita a tool no Prototipe.ai pra trocar.


• Idempotência: armazene os X-Prototipai-Delivery recentes (24h) e ignore duplicatas. Retries acontecem em falhas transitórias.


• Endpoint público: o Prototipe.ai bloqueia URLs apontando pra redes privadas (RFC1918, loopback, link-local) pra prevenir SSRF.


• Timeouts: tenta responder em < 5s. Limite interno é 10s.


• HTTPS obrigatório em produção.

Sim. Você pode fazer o agente reiniciar a conversa automaticamente após um tempo de inatividade — assim, se o usuário some e volta depois, ele recomeça uma conversa nova em vez de continuar de onde parou. Siga as etapas:

1. Na tela de Configurações do agente, localize a seção de reinício por inatividade.

2. Em Ativar reinício automático por inatividade?, selecione Sim.

3. Defina o Tempo de inatividade (em minutos) — quanto tempo sem interação a conversa deve esperar antes de reiniciar.

4. Clique em Salvar Alterações.

A partir daí, se o usuário ficar o tempo definido sem responder e voltar depois, o agente começa uma conversa nova. Se você deixar desativado, a conversa continua de onde parou, sem reinício.

Sim, com o Delay de Mensagens. Ele faz o agente aguardar alguns instantes antes de processar, para juntar várias mensagens que o usuário mandou em sequência e respondê-las de uma vez — muito útil no WhatsApp, onde as pessoas digitam em várias mensagens curtas.

Como configurar:

1. Na tela de Configurações do agente, encontre a seção Delay de Mensagens.

2. Preencha o Tempo de espera (em milissegundos). Por exemplo, 3000 = 3 segundos.

3. Clique em Salvar Alterações.

Como funciona: se você deixar vazio ou 0, as mensagens são processadas imediatamente (padrão). Com um valor, o agente aguarda esse tempo; se novas mensagens chegarem antes de acabar, ele reinicia a contagem e acumula tudo. O limite é 120.000 ms (2 minutos). Exemplo: com 3000 ms, se o usuário mandar 3 mensagens em 2 segundos, todas são juntadas e enviadas de uma vez para a IA.

Sim, o agente conversacional pode ter memória de longo prazo — ele guarda informações importantes de uma conversa e as recupera em conversas futuras com o mesmo cliente, para dar respostas mais contextualizadas.

Onde isso aparece:

1. Na Área de Testes do agente, abra a aba Memórias.

2. Em Memórias Persistentes (Memória de Longo Prazo) você vê o que o agente memorizou — cada item com Tipo, Valor, Descrição e se é Recuperável (isto é, se volta em conversas seguintes).

3. Memórias marcadas como ENTRE SESSÕES são as que atravessam conversas — é o que faz o agente "lembrar" do cliente na próxima vez.

Assim, informações como a profissão ou preferência do usuário podem ser reaproveitadas automaticamente, sem o cliente precisar repetir.

Tudo o que o agente memorizou fica visível — e sob seu controle — na aba Memórias. Siga as etapas:

1. Na Área de Testes do agente, abra a aba Memórias.

2. Percorra as Memórias Ativas. Cada uma mostra o Tipo, o Valor, a Descrição e a data de criação. Use a busca (entity, label, tipo) para localizar uma específica.

3. Para remover uma memória, clique em Fechar Memória no item — ela deixa de ser usada pelo agente.

Dica: marque a opção ocultar fechadas para ver só as memórias ativas. Fechar uma memória é como "esquecer" aquela informação, sem afetar o resto.

Você tem duas formas, dependendo do que quer limpar:

Limpar a conversa atual (na hora do teste):

1. Na aba Chat da Área de Testes, use Reiniciar conversa para começar uma conversa nova do zero, ou Limpar tudo para esvaziar a conversa em andamento.

Ver e organizar todo o histórico:

2. Na aba Exportar Histórico você vê todas as conversas do agente e pode continuar, avaliar ou exportar cada uma.

Importante: limpar/reiniciar a conversa mexe no histórico de teste daquela conversa, mas não apaga a memória de longo prazo do agente. Para remover o que o agente memorizou, use Fechar Memória na aba Memórias.