Principal Primeiros passos

Primeiros passos

primeiros passos na claudia agentica

Por Fabrício Rissetto and 4 outros

• 17 artigos

Como escrever a descrição e as instruções de um Agente Especialista

Quando usar - Você vai escrever um novo Agente Especialista (rastrear pedido, consultar crédito, remarcar agendamento, qualificar lead etc.) - Você está revisando um especialista e quer alinhar com o padrão atual - Você está migrando um Fluxo Controlado para um especialista Sobre este artigo Os Agentes Especialistas são acionados pelo Supervisor. Cada especialista recebe o pedido em linguagem natural, consulta os sistemas pelas ferramentas dele e devolve o resultado ao Supervisor, que redige a resposta para o cliente. Cada especialista tem dois textos: - Descrição: lida pelo Judge e pelo Supervisor para decidir se e quando este especialista atende - Instruções de comportamento: lidas pelo próprio especialista quando ele é acionado :::warning O especialista nunca fala diretamente com o cliente. Ele não vê a conversa inteira: recebe só o que o Supervisor contou e devolve o resultado para o Supervisor. Frases prontas para o cliente dentro das instruções competem com o tom de voz do Supervisor. ::: Além desses dois textos, o comportamento do especialista depende das descrições das ferramentas e dos parâmetros que ele usa. Elas estão em Boas práticas para criar um Agente Especialista. Antes de escrever: autônomo ou determinístico? | Tipo | Quando usar | Template | | --- | --- | --- | | Autônomo | Os passos dependem do que o cliente responde e existe mais de um caminho válido | 02 | | Determinístico | Sequência conhecida, não negociável, com verificação etapa por etapa | 03 | | Nenhum dos dois | Fluxo 100% procedural, sem nenhum ponto de interpretação | Use um Fluxo Controlado | Se o fluxo é quase todo fixo, mas tem um ou dois pontos de interpretação, use o determinístico: o template prevê isso. Os templates prontos para copiar estão em Templates para escrever um Agente Especialista. Ordem de escrita 1. Descrição do especialista. Vem primeiro porque obriga a ter clareza de escopo. 2. Descrições das ferramentas e dos parâmetros. Boa parte do que iria para as instruções resolve-se aqui. 3. Instruções de comportamento. Com as duas etapas anteriores feitas, elas ficam curtas. 4. Tom de voz do Supervisor, só se o projeto for novo. É um por projeto, não por especialista. A descrição A descrição é a superfície de roteamento. Use este formato: [Uma frase dizendo o que este especialista resolve.] EXECUTA - [ação de negócio] NÃO EXECUTA - [ação vizinha] → é de [destino] ACIONE QUANDO - [situação, na linguagem que o cliente usa] NÃO ACIONE QUANDO - [caso de fronteira] → vai para [destino] TESTE FINAL [Uma pergunta de sim ou não que decide os casos duvidosos.] Exemplo — especialista de rastreamento: Consulta onde está um pedido já feito e quando ele deve chegar. EXECUTA - consultar o status e a previsão de entrega de um pedido - informar o código e o link de rastreio da transportadora NÃO EXECUTA - cancelar, trocar ou devolver → é do especialista de Trocas e Devoluções - alterar endereço de entrega → é do especialista de Alteração de Pedido - reembolso → é do especialista Financeiro ACIONE QUANDO - o cliente quer saber onde está o pedido ou quando chega - o cliente pergunta se o produto já foi enviado - o cliente diz que o pedido está atrasado NÃO ACIONE QUANDO - o cliente recebeu o produto com defeito → vai para Trocas e Devoluções - o cliente ainda não fez a compra e quer saber o prazo → vai para a base de conhecimento TESTE FINAL O cliente está perguntando sobre a entrega de um pedido que já existe? Boas práticas: - Use a linguagem do cliente. Se o cliente diz "quero cancelar" e a descrição diz "fluxo de retenção de churn", o roteamento falha. - Declare as fronteiras com destino. Para cada assunto vizinho, diga para onde ele vai. - Se o especialista depende de um dado (número do pedido, CPF), diga em ACIONE QUANDO que o pedido já precisa trazer esse dado. Assim o Supervisor coleta antes de acionar, em vez de acionar, receber "falta dado" e acionar de novo. - Teste com dez frases reais: cinco que devem cair aqui e cinco que não devem. Lendo só a descrição, você conseguiria decidir cada uma? Detalhes em Como o Supervisor decide qual Agente Especialista responde. O que nunca entra na descrição: como executar, regra de negócio, formato de resposta, nome técnico de ferramenta ou de endpoint. As instruções de comportamento A plataforma já entrega ao especialista um conjunto fixo de regras. As instruções existem para o que só você sabe sobre o seu negócio, e por isso têm quatro conteúdos: 1. Fronteira do domínio. O que está coberto e o que não está, com o destino de cada assunto vizinho. 2. Regras de interpretação. O que concluir de cada resultado das ferramentas. Exemplo: "previsão de entrega anterior a hoje significa pedido atrasado". 3. Critério de ação. Quando cada ferramenta se aplica e quais desfechos ela devolve. 4. O que entregar ao Supervisor. O desfecho, os dados com a origem, o que ficou pendente e a recomendação de próximo passo. Na ordem: domínio e fronteira, dados necessários, ações disponíveis, regras de negócio, desambiguação, retenção e transbordo, entrega ao Supervisor. O que a plataforma já garante (não reescreva) O especialista já recebe estas regras da plataforma: - Usar só as informações que vêm das ferramentas, sem conhecimento geral nem suposição - "Não tenho essa informação" é uma resposta correta - Não prometer ação que nenhuma ferramenta executa - A resposta vai para o Supervisor, não para o cliente - Transferir para humano é recomendação: quem executa é o Supervisor :::error Reescrever essas regras com outras palavras atrapalha. A sua versão passa a competir com a da plataforma, e o especialista começa a escolher entre as duas de forma diferente a cada conversa. Blocos longos de "NUNCA invente" ou "BLOQUEANTE" costumam fazer o especialista se recusar a usar as próprias ferramentas. ::: Boas práticas de escrita - Escreva regras como ação: "quando X, faça Y", e não proibições genéricas - Explique o porquê da regra. "Acima de R$ 1.000, porque abaixo disso o frete não compensa" funciona melhor nos casos de borda do que só o número - Dê um veredito para cada caso ambíguo. Nenhum caso conhecido deve ficar em aberto - Nomeie todos os desfechos de cada ferramenta, inclusive os ruins: encontrou vários, não encontrou, status inesperado, dado que contradiz o relato do cliente - Não infle a ênfase. Maiúsculas em série e "NUNCA" repetido dezenas de vezes diluem o que importa O que não entra nas instruções - Tom de voz, saudação e despedida: são do Supervisor - Ordem obrigatória entre ferramentas: se uma sequência é sempre a mesma, ela deve virar uma ferramenta só - Tabelas de conversão entre texto e valor de sistema, regras de formato de dado e "use só o campo X, ignore o resto": são trabalho da ferramenta ou da descrição do parâmetro - Regras de roteamento: ficam na descrição Especialista determinístico Quando o processo é uma sequência fixa, a ordem e a validação das etapas ficam numa ferramenta de controle, e não no texto. O especialista faz três coisas a cada acionamento: 1. Identifica se a mensagem do cliente responde à etapa pendente, traz um assunto novo ou corrige algo já informado 2. Chama a ferramenta de controle com o que tem 3. Leva ao Supervisor o que a ferramenta devolveu As instruções precisam dizer o que fazer quando o cliente corrige um dado no meio do fluxo, quando traz outro assunto (relatar ao Supervisor sem forçar a etapa), quando responde fora do formato (repetir a etapa, não transferir) e qual é o limite de tentativas na mesma etapa. :::info Por que a sequência não fica no texto: quando as instruções descrevem dezenas de passos em ordem, o modelo pula ou funde etapas. O agente fica não determinístico mesmo quando o processo é determinístico. Veja Quando usar Fluxo Controlado ou Agentes Especialistas. ::: Retenção e transbordo Todo especialista precisa de um bloco que diga quando ele não deve recomendar transferência. Sem esse bloco, diante de um resultado que ninguém previu, o caminho mais cauteloso para o especialista é recomendar humano, e o Supervisor cumpre. O bloco padrão está nos templates e a explicação completa está em Como funciona a transferência para humano nos Agentes Especialistas. Usando o AI Companion O AI Companion gera a descrição e as instruções a partir de uma explicação em linguagem natural, migra um Fluxo Controlado existente ou revisa um especialista já criado. Mesmo usando o Companion, vale conferir o resultado com este artigo. Veja Como criar agentes com linguagem natural (AI Companion). Erros comuns - Descrição que se sobrepõe à do vizinho. Quando dois especialistas poderiam atender o mesmo caso, o roteamento oscila. - Ação prometida na descrição sem ferramenta que a execute. Se a descrição diz "trata cancelamento", precisa existir ferramenta de cancelamento. - Frases prontas para o cliente nas instruções. O especialista entrega fatos; o Supervisor redige. - Lógica de conversa no especialista. Retenção do cliente insistente, reformulação e tom são do Supervisor. O especialista faz a mesma coisa na primeira e na quinta chamada. - Sequência de etapas escrita como texto. Vai para a ferramenta. - Transferência por leitura emocional ("se o cliente estiver frustrado"). A regra de transferência precisa se apoiar num dado que a ferramenta devolve. Observações - Para os templates prontos: Templates para escrever um Agente Especialista - Para o material que vale reunir antes: O que preparar antes de montar um Agente Especialista - Para criar, vincular ao Supervisor e publicar: Como criar, editar e publicar um Agente Especialista - Para o Supervisor: Como configurar o Supervisor dos Agentes Especialistas - Para revisar especialistas que já estão no ar: Como revisar um Agente Especialista que já está no ar

Última atualização em Oct 14, 2026

Como configurar o Supervisor dos Agentes Especialistas

Quando usar - Você está configurando pela primeira vez o Supervisor de um projeto - Você quer entender o que ele faz e o que ele não faz - Você precisa escrever ou revisar o tom de voz do atendimento Pré-requisitos - Acesso ao Painel da ClaudIA com os Agentes Especialistas habilitados - Projeto (workspace) selecionado no seletor do canto superior direito da tela de Agentes. O campo Project é obrigatório nos formulários do Supervisor e dos especialistas - (Recomendado) Especialistas já criados. Ver Como escrever a descrição e as instruções de um Agente Especialista Sobre este artigo O Supervisor é quem conversa com o cliente. Ele entende o pedido, decide se responde sozinho ou aciona um especialista e redige a resposta final com o tom de voz do projeto. Ele não acessa sistema nenhum: tudo que envolve consultar ou alterar dados passa por um especialista. O que o Supervisor faz 1. Entende o que o cliente precisa 2. Escolhe o especialista certo, com base na descrição de cada um 3. Aciona um especialista por vez, com um pedido claro e completo, já que o especialista não vê a conversa inteira 4. Usa a resposta do especialista como fonte da verdade 5. Redige a resposta final com o tom de voz configurado :::error O Supervisor não inventa, não complementa e não contradiz o que o especialista informou. A resposta do especialista é a fonte da verdade. ::: O que o Supervisor não faz - Não acessa sistemas: não liga, não envia e-mail, não abre chamado, não altera pedido. Se nenhum especialista executa uma ação, o sistema não executa - Não pede dados "por via das dúvidas": só pede ao cliente o que é indispensável para avançar - Não oferece próximos passos não pedidos: sem "Posso ajudar em mais alguma coisa?" - Não promete ação que não pode executar: em vez de "vou abrir a verificação", diz que o próximo passo é abrir a verificação Essas regras já vêm prontas na plataforma. Não é preciso reescrevê-las no tom de voz. Como o Supervisor escolhe o especialista A escolha é feita pela descrição de cada especialista. :::warning Não liste os especialistas nem as regras de roteamento no tom de voz. As descrições já fazem esse trabalho. Repetir cria duas fontes de verdade que podem se contradizer. Detalhes em Como o Supervisor decide qual Agente Especialista responde. ::: Configurando o tom de voz O tom de voz fica no campo Instruções gerais e tom de voz do Supervisor. É o único lugar de personalidade do sistema: vale para todas as respostas, de todos os especialistas. Escreva uma vez por projeto. Estrutura recomendada - Quem você é: nome, papel, o que a empresa faz do ponto de vista do cliente e o canal de atendimento - Como você fala: tratamento, formalidade, tamanho das mensagens, emoji, idioma - Como você não fala: expressões proibidas e vícios que não combinam com a marca - Exemplos: situação e frase modelo, incluindo uma notícia ruim ou uma negativa - Transbordo para humano: quando o Supervisor chama a transferência (veja abaixo) O modelo pronto está em Templates para escrever um Agente Especialista, template 04. :::info Exemplo calibra melhor que adjetivo. "Seja simpático" muda pouco. "Prefira 'seu pedido tá a caminho' a 'o pedido encontra-se em trânsito'" muda muito. ::: O bloco de transbordo O tom de voz não deve ter regra de operação, com uma exceção: o critério de transferência para humano. Com a ferramenta de transferência ligada, o Supervisor transfere sempre que julgar necessário, e esse campo é o único lugar onde dá para dizer a ele quando isso se aplica. Sem esse bloco, ele decide sozinho e a retenção cai. ## Transbordo para humano Você chama handoff_to_human apenas quando: - um especialista recomendar explicitamente o transbordo, ou - [caso de negócio que dispense especialista, se houver] Você não chama handoff_to_human porque o cliente está irritado, porque repetiu a pergunta, ou porque a resposta do especialista não resolveu o problema dele. Nesses casos, comunique o que o especialista informou. Detalhes em Como funciona a transferência para humano nos Agentes Especialistas. O que não deve estar no tom de voz - Regras de negócio e cenários: vão nas instruções do especialista - Regras de roteamento: vão na descrição do especialista - Quando usar cada ferramenta: vai na descrição da ferramenta - O que a plataforma já garante: não inventar, não prometer, não pedir dado à toa Checklist do tom de voz :::success - Sem contradições: "ser informal" + "sempre usar senhor/senhora" é conflito; resolva antes de publicar - Cobertura de situações: cobre ao menos pergunta neutra, cliente frustrado e notícia ruim - Tem exemplos, não só adjetivos - Tem o bloco de transbordo - Escrito como instrução para a IA, e não copiado do manual de marca ::: Observações - Para os especialistas: Como escrever a descrição e as instruções de um Agente Especialista - Para ligar ou desligar transferir, encerrar e devolver para a ClaudIA: Ferramentas nativas do Supervisor - Para boas práticas gerais: Boas práticas para criar um Agente Especialista

Última atualização em Oct 14, 2026

Como funciona a transferência para humano nos Agentes Especialistas

Quando usar - Os Agentes Especialistas estão transferindo para humano em casos que deveriam resolver - Uma transferência que deveria acontecer não aconteceu - Você vai escrever as regras de transferência de um especialista novo Pré-requisitos - Especialista criado, com as instruções de comportamento preenchidas - Acesso ao Playground para testar os cenários Sobre este artigo Nos Agentes Especialistas, a transferência para humano (N2) passa por duas etapas: o especialista recomenda e o Supervisor executa. As duas precisam de regra escrita. Este artigo explica como escrever essas regras para que o atendimento fique em N1 sempre que possível e vá para N2 apenas nos casos que o seu negócio define. Quem transfere O único mecanismo de transferência é a ferramenta handoff_to_human, que fica com o Supervisor. O especialista não transfere: ele recomenda a transferência na resposta, e o Supervisor decide se chama a ferramenta. 1. O especialista devolve ao Supervisor: "pedido com status extraviado; recomendo transbordo" 2. O Supervisor lê a recomendação 3. O Supervisor chama handoff_to_human 4. A conversa é transferida e o Supervisor avisa o cliente :::warning Descrever não é executar. Se a resposta ao cliente diz "vou te transferir" mas o Supervisor não chamou a ferramenta, a conversa continua com a IA. Confirme na auditoria se a ferramenta foi chamada. ::: A ferramenta pode ser ligada ou desligada no Supervisor. Ver Ferramentas nativas do Supervisor. Sem regra escrita, o padrão é transferir Este é o ponto mais importante do artigo. - No Supervisor: com a ferramenta ligada, ele transfere sempre que julgar que a intervenção humana é necessária. Se o campo de tom de voz não diz quando isso se aplica, ele decide sozinho. - No especialista: diante de um resultado que as instruções não previram, o caminho mais cauteloso é sinalizar que algo está estranho. Isso vira recomendação de transferência, e o Supervisor cumpre. Ou seja: transferência indevida quase nunca é o agente desobedecendo. É a falta de regra sendo preenchida pela opção mais cautelosa. Para reter em N1, a regra precisa estar escrita. O princípio: N1 é o padrão, N2 é exceção nomeada O especialista permanece em N1 e responde com o que tem, inclusive quando a resposta é parcial ou a notícia é ruim. Ele só recomenda N2 quando acontece um caso listado na regra de negócio. Caso não listado não é motivo para transferir. A regra se apoia em dado, não em impressão - ✅ "Se o status do pedido for 'problema empresarial', recomende transbordo." - ❌ "Se o cliente estiver estressado, recomende transbordo." A primeira dá para testar e auditar: existe um campo e existe um valor. A segunda varia a cada conversa e abre espaço para transferir por desconforto. Toda regra de N2 deveria caber no formato "se [campo devolvido pela ferramenta] for [valor], recomende transbordo". Se não cabe, provavelmente é uma impressão, não uma regra de negócio. O que não é motivo para o especialista recomendar transferência - Cliente pediu para falar com uma pessoa - Cliente irritado, agressivo ou insatisfeito com a resposta - Cliente repetiu a pergunta - Cliente ameaçou reclamar, cancelar ou processar Esses casos são tratados pelas configurações de transferência da ClaudIA, fora do especialista. Ver Como configurar a tentativa de retenção antes de transferir e Como configurar a transferência automática por detecção de frustração. Repetir essas regras no especialista duplica uma camada que já existe e derruba a retenção. Resultados que parecem N2 e não são A maior parte das transferências indevidas vem daqui. Cada um tem tratamento em N1: | Resultado | Tratamento em N1 | | --- | --- | | O relato do cliente não bate com o dado do sistema | O dado é a fonte. Informar o que o sistema mostra | | Não encontrou o registro | Pedir outro identificador ou informar que não localizou | | Encontrou vários registros | Devolver a lista para o cliente escolher | | Falta uma informação específica | Dizer o que falta e responder o que tem. Resposta parcial é útil | | O pedido é de outro assunto | Recomendar o especialista correspondente, não humano | | A ação pedida não existe no sistema | Informar que não é possível e qual é o caminho alternativo | O caso da divergência merece destaque, porque é o mais comum em rastreio, cobrança e prazos. O cliente diz "meu pedido está atrasado" e o sistema mostra que está dentro do prazo. Isso não é um conflito: o trabalho do atendimento é justamente comunicar o que o sistema registra, com a informação que sustenta (prazo original, data de envio, status atual). Sem essa regra escrita, o especialista encontra uma contradição que ninguém previu e passa para cima. Onde escrever a regra Em ordem de preferência: 1. Na ferramenta. A ferramenta que consulta o status também avalia a regra e devolve, junto com o dado, se aquele caso exige humano e por quê. O especialista só repassa. A regra executa sempre igual, muda sem mexer nas instruções e fica registrada no retorno. 2. Nas instruções do especialista, num bloco próprio, quando a ferramenta não consegue devolver o veredito. Bloco para as instruções do especialista Vai depois das regras de negócio e antes da entrega ao Supervisor: ## Retenção e transbordo Você permanece em N1 por padrão. Responda com o que você tem, inclusive quando a resposta for parcial ou quando a informação não agradar o cliente. Recomende transbordo para humano APENAS nestes casos: - se [campo] for [valor], recomende transbordo - se [campo] for [valor], recomende transbordo Não recomende transbordo por nenhum outro motivo. Em especial, não recomende transbordo quando: - o relato do cliente divergir do dado retornado pelas suas ferramentas; o dado é a fonte, informe o que o sistema mostra - não localizar o registro; recomende coletar [identificador alternativo] - encontrar mais de um registro; devolva a lista para o cliente escolher - faltar um fato específico; declare a falta e responda o que você tem - o pedido for de outro domínio; recomende o especialista correspondente Se não existe nenhum caso de transferência para esse assunto, escreva isso. Lista vazia é um resultado válido e melhor que uma lista inventada. Bloco para o Supervisor Vai no fim do campo Instruções gerais e tom de voz, depois dos exemplos. É a única regra de operação que deve ficar nesse campo, porque é o único lugar onde dá para dar ao Supervisor um critério de transferência: ## Transbordo para humano Você chama handoff_to_human apenas quando: - um especialista recomendar explicitamente o transbordo, ou - [caso de negócio que dispense especialista, se houver] Você não chama handoff_to_human porque o cliente está irritado, porque repetiu a pergunta, ou porque a resposta do especialista não resolveu o problema dele. Nesses casos, comunique o que o especialista informou. Caso real — quando a transferência não aconteceu Situação: um cliente consultou um pedido atrasado. A ClaudIA identificou o atraso, mas respondeu só com o link de rastreio em vez de transferir. Causa: as instruções do especialista tratavam pedido atrasado igual aos outros. Não havia regra para esse resultado. Correção: uma regra ancorada em dado: "se a data de previsão de entrega for anterior à data atual, recomende transbordo, independente de o rastreio estar disponível". O melhor ainda é a própria ferramenta calcular o atraso e devolver o veredito. Aprendizado: teste os cenários de transferência ativamente, e não só os de resolução. Como testar Além dos casos normais, teste estes três para cada especialista no Playground: | Caso | Esperado | Reprovado se | | --- | --- | --- | | Relato divergente: o cliente afirma um problema e o sistema mostra situação normal | Resposta em N1 informando o dado | Recomendar transferência | | Caso da regra de negócio: o campo com o valor que dispara a regra | Recomendação de transferência e chamada da ferramenta | Ficar em N1 | | Cliente irritado sem caso de regra | Resposta em N1 | Recomendar transferência | O que medir - Taxa de transferência por especialista - Quantas transferências correspondem a um caso listado na regra. Transferência sem regra correspondente é o defeito, e é ela que derruba a retenção Os motivos de transferência e a auditoria das conversas mostram onde estão as transferências indevidas. Em geral elas se concentram em dois ou três resultados que as instruções não nomearam. Observações - Para os templates com os blocos prontos: Templates para escrever um Agente Especialista - Para o Supervisor: Como configurar o Supervisor dos Agentes Especialistas - Para as instruções do especialista: Como escrever a descrição e as instruções de um Agente Especialista

Última atualização em Oct 14, 2026

Quando usar Fluxo Controlado ou Agentes Especialistas (comparativo)

Quando usar - Você está avaliando se um caso de uso deve virar Fluxo Controlado ou Agente Especialista - Você quer entender as forças e limitações de cada abordagem - Você está modernizando um Fluxo Controlado existente e considerando migrar para Agentes Especialistas - Um cliente pediu que o agente siga um processo exato, passo a passo, e você precisa decidir onde esse processo deve rodar Pré-requisitos - Conhecimento básico do Fluxo Controlado e dos Agentes Especialistas Sobre este artigo Agentes Especialistas e Fluxo Controlado são os dois mecanismos que permitem à ClaudIA acessar sistemas externos e executar ações via API. Eles se complementam — a escolha depende do tipo de processo. Fluxo Controlado — fluxos estruturados O Fluxo Controlado é um agente interativo que segue um fluxo pré-definido e bastante rígido. Cada possível caminho da conversa é mapeado antecipadamente — a ClaudIA segue esse roteiro etapa por etapa. Quando o Fluxo Controlado é a escolha certa - Processos regulatórios ou com compliance — qualquer variação é inaceitável - Fluxos com etapas obrigatórias e sequenciais que não podem ser puladas - Situações onde você precisa de controle total sobre cada passo - Processos simples e bem delimitados onde o cliente não sai do roteiro O que o Fluxo Controlado faz bem :::success - Previsibilidade total — a resposta segue exatamente o fluxo - Controle granular sobre o que a IA pode ou não perguntar ::: Limitação :::warning - Se o cliente responder algo fora do caminho previsto, o fluxo trava (ou reinicia) e cai em fallback - Qualquer novo cenário exige atualização manual do fluxo - Esforço de correção cresce exponencialmente com a complexidade do fluxo ::: Agentes Especialistas — raciocínio contextual Com os Agentes Especialistas, não há fluxo fixo. A ClaudIA usa reasoning para decidir em tempo real qual tool acionar, em qual momento e com quais parâmetros — combinando o pedido do cliente, o prompt de diretrizes e as tools disponíveis. Quando os Agentes Especialistas são a escolha certa - Conversas que podem seguir caminhos diferentes dependendo do contexto - Situações onde o cliente pode trazer múltiplas demandas numa mesma mensagem - Processos onde a IA precisa raciocinar antes de agir — ex: verificar se um pedido está em atraso antes de decidir o que fazer - Casos de uso com variações naturais — rastreio, consulta de crédito, agendamentos - Quando existe espaço para a IA modificar a forma de agir para melhor atender o cliente - Quando um Fluxo Controlado cresceu demais e ficou difícil de manter — os Agentes Especialistas absorvem a flexibilidade que o fluxo rígido perdeu O que os Agentes Especialistas fazem bem :::success - Lida com conversas que fogem do roteiro sem travar - Combina múltiplas tools numa mesma interação - Valida o input do cliente antes de acionar a chamada - Melhora conforme os cenários ocorrem em produção - Respostas muito fluidas e zero robóticas ::: Limitação :::warning Requer descrições e instruções bem escritas para a IA agir dentro do escopo correto. E não é a ferramenta certa para executar uma sequência longa de passos sempre na mesma ordem (veja a seção abaixo). ::: E quando o processo é uma sequência fixa? Um pedido comum é que o agente siga um processo exato, com dezenas de passos, sempre na mesma ordem. Nenhum modelo de linguagem entrega isso de forma confiável quando os passos estão escritos como texto. Não é uma limitação dos Agentes Especialistas nem do modelo usado: modelos de linguagem resumem o contexto, reinterpretam instruções longas e priorizam a intenção sobre a execução literal. Na prática, o agente pula ou funde etapas. :::warning O agente fica não determinístico mesmo quando o processo é determinístico. ::: A saída que o mercado adotou é separar as responsabilidades: os passos fixos rodam em código, e o agente fica com a interpretação. Aqui, isso pode ser feito de duas formas: - Especialista determinístico: a ordem e a validação das etapas ficam numa ferramenta de controle, e o especialista identifica se o cliente respondeu a etapa, corrigiu um dado ou mudou de assunto. Ver o template 03 em Templates para escrever um Agente Especialista. - Fluxo Controlado com o agente na porta: a árvore continua existindo e roda onde o determinismo é real, e o agente entende o pedido antes de entrar nela. Nos dois casos, o resultado é o comportamento previsível do fluxo, mais o que só o modelo oferece: entender resposta fora do menu, reconhecer correção e lidar com mudança de ideia no meio do caminho. Se o processo é 100% procedural, sem nenhum ponto de interpretação, ele não precisa de especialista: use o Fluxo Controlado. Comparativo rápido | | Fluxo Controlado | Agentes Especialistas | | --- | --- | --- | | Tipo de fluxo | Pré-definido e fixo | Dinâmico, baseado em reasoning | | Ideal para | Processos rígidos, etapas obrigatórias | Conversas com múltiplos caminhos e flexibilidade | | Cliente sai do roteiro | Trava, reinicia ou vai para fallback | Raciocina e continua | | Configuração | Fluxo visual no Fluxo Controlado | Descrição + instruções + ferramentas no workspace | | Previsibilidade | Total | Alta, mas depende do prompt | | Manutenção | Atualizar fluxo para cada novo cenário | Refinar descrições, instruções e ferramentas com base em casos reais | Migrando de Fluxo Controlado para Agentes Especialistas Se você tem um Fluxo Controlado em produção que cresceu demais ou está caindo em fallback com frequência, dá pra migrar para Agentes Especialistas direto pelo AI Companion. Ao abrir o Companion, você escolhe "Migrar fluxo existente", seleciona o Fluxo Controlado da lista do workspace e o Companion analisa a estrutura: - Webhooks viram tools - Condicionais viram cenários - Mensagens das etapas viram textos do especialista ou da ferramenta (o tom de voz continua no Supervisor) O resultado é um conjunto equivalente de especialistas que você pode revisar e ajustar antes de publicar. :::info Detalhes do fluxo completo em Como criar agentes com linguagem natural (AI Companion). ::: Regra prática :::success Use o Fluxo Controlado quando o processo precisa de controle total e zero variação. Use Agentes Especialistas quando quiser acessar sistemas externos com muita flexibilidade e fluidez. Os dois podem coexistir no mesmo projeto — Fluxo Controlado para processos críticos e fixos, Agentes Especialistas para o restante. E dá para combinar os dois no mesmo atendimento, como mostra a seção acima. ::: Observações - Para entender os Agentes Especialistas: O que são os Agentes Especialistas e como funcionam - Para criar fluxos: Como lançar um novo Fluxo Controlado passo a passo - Para migrar Fluxo Controlado para Agentes Especialistas via Companion: **Como criar agentes com linguagem natural (AI Companion) ** Workshop de apresentação | 29/04/2026 https://www.loom.com/share/df78ef9d1bc94f829def2b0bbc8299c5

Última atualização em Oct 14, 2026

Boas práticas para criar um Agente Especialista

Quando usar - Você está montando seu primeiro Agente Especialista e quer evitar os erros mais comuns - Você está revisando especialistas existentes e quer um checklist - Você quer entender o que vai nas ferramentas e o que vai no texto Pré-requisitos - Acesso à área de Agentes Especialistas no Painel da ClaudIA - Conhecimento básico da arquitetura (Judge, Supervisor, especialista, ferramentas). Ver O que são os Agentes Especialistas e como funcionam Sobre este artigo A maior parte dos problemas de especialistas não vem de texto mal escrito. Vem de instrução escrita no lugar errado: regra de escolha de ferramenta nas instruções, sequência de etapas no texto, tom de voz dentro do especialista. Este artigo mostra onde cada coisa deve morar e traz o checklist de revisão. O princípio que organiza tudo :::success Julgamento de linguagem fica no modelo. Sequência, validação e estado ficam na ferramenta. ::: O modelo é ótimo para entender o que o cliente quis dizer, reconhecer uma correção e lidar com mudança de assunto. Ele não é confiável para executar dezenas de passos sempre na mesma ordem, validar formato ou comparar valores de forma idêntica em toda conversa. Por isso, quando a regra é "sempre faça A, depois B, depois C" ou "se o campo X for maior que Y", ela funciona melhor dentro da ferramenta (na sua API, no servidor MCP ou no fluxo usado como ferramenta) do que escrita nas instruções. Regra na ferramenta executa sempre igual, muda sem reabrir o teste do especialista e fica auditável no retorno. As cinco superfícies de escrita Existem cinco lugares onde o texto que você escreve muda o comportamento do sistema. Cada um tem um leitor diferente: | Superfície | Onde fica | Quem lê | O que entra | O que nunca entra | | --- | --- | --- | --- | --- | | Descrição do especialista | Campo Descrição do especialista | Judge e Supervisor, ao decidir quem atende | O que executa, o que não executa, quando acionar, quando não acionar, teste final | Como executar, regra de negócio, formato de resposta | | Tom de voz | Campo Instruções gerais e tom de voz do Supervisor | Supervisor, ao redigir para o cliente | Identidade, como fala, como não fala, exemplos, critério de transbordo | Regras de operação e de roteamento | | Instruções do especialista | Campo Instruções de comportamento | O especialista, ao ser acionado | Fronteira, regras de interpretação, critério de ação, o que entregar | O que a plataforma já garante, tom de voz, sequência de etapas | | Descrição da ferramenta | Descrição da ferramenta | O especialista, ao escolher a ferramenta | O que faz, quando usar, quando não usar, o que devolve | Nome técnico de endpoint, ordem em relação a outra ferramenta | | Descrição do parâmetro | Descrição de cada parâmetro da ferramenta | A plataforma, ao preencher o campo | O que é o dado, o formato, de onde tirar | Regra de negócio | Regra de decisão rápida Antes de escrever qualquer instrução, pergunte onde ela pertence: - É critério para escolher este especialista? → Descrição do especialista - É como o cliente deve ser tratado? → Tom de voz do Supervisor - É critério para escolher esta ferramenta? → Descrição da ferramenta - É o que preencher num campo? → Descrição do parâmetro - É sequência, validação, conversão ou cálculo? → Dentro da ferramenta - É conhecimento do assunto ou como interpretar um resultado? → Instruções do especialista Ferramentas Descrição da ferramenta É o texto que o especialista lê para escolher a ferramenta certa, na hora certa, com os dados certos. Revisar as descrições das ferramentas costuma render mais do que reescrever as instruções, e é a superfície mais esquecida. Use uma frase de propósito e três blocos curtos: Consulta os pedidos de um cliente a partir do CPF ou do número do pedido. Quando usar: o cliente quer saber status, previsão de entrega ou rastreio de um pedido já feito. Quando não usar: para alterar ou cancelar pedido (use "Alterar pedido"). O que devolve: um pedido encontrado; vários pedidos encontrados (lista para o cliente escolher); nenhum pedido encontrado; CPF sem cadastro. - Escreva em linguagem de negócio, não "chama o endpoint /orders" - Nomeie os desfechos, não o formato técnico: encontrou um, encontrou vários, não encontrou, cliente não existe - Não repita só o nome da ferramenta: "Consulta pedido" não acrescenta nada Descrição do parâmetro Diz à plataforma o que preencher em cada campo. Quando o dado já está na conversa, ela o extrai sozinha. Documento do titular da conta, apenas dígitos, sem pontuação. Usar o documento informado pelo próprio cliente na conversa, não o de terceiros mencionados. Diga o que é, o formato quando importa e de onde tirar quando há mais de uma origem possível na conversa. Como desenhar as ferramentas - Consolide o que sempre roda junto. Quatro consultas que acontecem sempre em sequência não são quatro decisões do especialista: são uma decisão e três execuções. Exponha como uma ferramenta só. - Unifique a leitura do mesmo registro por chaves diferentes. "Buscar por e-mail" e "buscar por telefone" são uma ferramenta com dois parâmetros opcionais. - Separe leitura de escrita. Consultar e alterar (aplicar etiqueta, atualizar cadastro) ficam em ferramentas diferentes, porque têm riscos e permissões diferentes. - Devolva só o que o especialista usa. Filtre o retorno na ferramenta em vez de instruir o especialista a ignorar campos. - Devolva desfechos nomeados, como encontrou_varios, nao_encontrado e erro_consulta, em vez de códigos de status. - Faça o erro dizer o próximo passo: "coletar outro identificador" em vez de "falha na consulta". - Quando possível, a ferramenta devolve o veredito de transferência junto com o dado. Exemplo: além do status do pedido, ela devolve se aquele caso exige atendimento humano e por quê. - Evite listas longas de ferramentas por especialista. A tela recomenda até 15 ferramentas liberadas por agente. Erros conhecidos - Linguagem interna na descrição. Se o cliente diz "quero cancelar" e a descrição diz "fluxo de retenção de churn", o roteamento falha. - Descrições vizinhas que se sobrepõem. Quando dois especialistas poderiam atender o mesmo caso, o roteamento oscila entre eles. - Regras de roteamento repetidas no Supervisor. A descrição já faz esse trabalho. Repetir cria duas fontes de verdade. - Reescrever o que a plataforma já garante, como "não invente dados" ou "não prometa ações". A sua versão compete com a da plataforma. - Frases prontas para o cliente nas instruções do especialista. Conflitam com o tom do Supervisor. - Sequência de etapas e árvores de decisão no texto. "Se X, faça Y; se não, verifique Z" é frágil. Vai para a ferramenta. - "Use a ferramenta Y só depois da X" nas instruções. Se a ordem é obrigatória, as duas viram uma ferramenta. - Ferramenta sem descrição ou com descrição que só repete o nome. - Transferência por leitura emocional. Ver Como funciona a transferência para humano. - Mudar instruções, ferramenta e descrição ao mesmo tempo. Depois ninguém sabe o que funcionou. Checklist de revisão Onde cada coisa está - Nenhuma instrução repete o que a plataforma já garante - As instruções não têm tom de voz, saudação ou despedida - Nenhuma regra de formato de dado está nas instruções quando poderia estar na descrição do parâmetro ou na ferramenta - Nenhuma tabela de conversão e nenhuma ordem entre ferramentas está nas instruções Descrição do especialista - Tem os blocos executa, não executa, acione quando, não acione quando e teste final - Usa a linguagem do cliente e descreve ação de negócio, não ferramenta - Declara as fronteiras com os especialistas vizinhos, com destino - Dez frases reais (cinco que caem aqui, cinco que não caem) são decididas corretamente lendo só a descrição Instruções do especialista - O domínio cabe numa frase, sem "e" ligando duas responsabilidades - Toda ação mencionada tem uma ferramenta que a executa - Todos os desfechos de cada ferramenta têm tratamento, inclusive não encontrou, encontrou vários, status inesperado e relato que contradiz o sistema - Os casos ambíguos têm veredito - Existe o bloco de retenção e transbordo - A entrega ao Supervisor diz quais fatos, com origem, e qual recomendação Ferramentas e parâmetros - Cada ferramenta tem descrição com o que faz, quando usar, quando não usar e o que devolve - Nenhuma ferramenta é sempre chamada junto com outra (se é, consolide) - Cada retorno devolve só o que o especialista usa - As mensagens de erro dizem o que fazer em seguida - Cada parâmetro tem descrição com o que é, o formato e de onde tirar Antes de ligar em produção - Existem casos de teste com o resultado esperado, cobrindo os desfechos ruins e não só o caminho feliz - Os três casos de transferência foram testados: relato que contradiz o sistema (esperado: N1), caso da regra de negócio (esperado: transferência) e cliente irritado sem caso de regra (esperado: N1) - Está definido o que vai ser medido e em quanto tempo Observações - Para os templates prontos: Templates para escrever um Agente Especialista - Para a descrição e as instruções em detalhe: Como escrever a descrição e as instruções de um Agente Especialista - Para revisar especialistas no ar: Como revisar um Agente Especialista que já está no ar - Para conectar ferramentas: Integrações e servidores MCP - Para a transferência para humano: Como funciona a transferência para humano nos Agentes Especialistas

Última atualização em Oct 14, 2026

O que são os Agentes Especialistas e como funcionam

Quando usar - Você quer entender o que são os Agentes Especialistas e como eles diferem da ClaudIA tradicional - Você quer ver exemplos reais de uso (hospedagem, fintech, varejo) - Você quer aprender a estrutura interna (Judge → Supervisor → especialista → ferramentas) Pré-requisitos - Acesso ao painel com os Agentes Especialistas habilitados - Conhecimento básico do que é a ClaudIA tradicional Sobre este artigo Os Agentes Especialistas permitem à ClaudIA executar ações reais via chamadas de API, MCPs (ferramentas) etc. — em vez de responder apenas com base nos conteúdos da base de conhecimento. Na prática, a ClaudIA passa a agir de forma autônoma e contextual, decidindo quando agir, combinando a solicitação do cliente com diretrizes de prompt e executando a ação mais adequada. 🎥 Webinar com o CEO — visão geral e contexto estratégico Como funciona Quando um cliente envia uma mensagem, a IA analisa a solicitação (e o contexto) e decide: - Responder diretamente com base nos conteúdos registrados, ou - Acionar os Agentes Especialistas, que agem para ajudar o cliente :::success Em resumo: a ClaudIA deixa de ser apenas uma IA que responde perguntas e passa a ser uma IA que também age e busca informações para agir. ::: Os três componentes internos Judge — decide se os especialistas atuam Lê a mensagem do cliente e compara com as descrições dos especialistas disponíveis. Se existir um especialista apropriado, a conversa é roteada para o Supervisor. Caso contrário, a ClaudIA responde com base na base de conhecimento. Supervisor — decide quem age e entrega a resposta Quando o Judge aciona os especialistas, o Supervisor: - Seleciona qual especialista é o mais adequado - Formata a resposta final com o tom de voz do cliente Especialista — executa a ferramenta O especialista. Tem prompt próprio para a situação e conta com as ferramentas (chamadas de API). Devolve dados estruturados ao Supervisor — nunca fala diretamente com o cliente. Fluxo: Judge → decide se ativa → Supervisor → seleciona o especialista → especialista → executa a ferramenta → Supervisor → entrega a resposta Uma analogia que ajuda Pense na central de atendimento telefônico de uma empresa grande: - A recepção ouve o cliente e decide para onde encaminhar. É o Judge. - O atendente conversa com o cliente do começo ao fim, mas não acessa sistema nenhum. É o Supervisor. - Os especialistas de retaguarda acessam os sistemas e respondem ao atendente, nunca ao cliente. São os Agentes Especialistas. - Os sistemas da empresa que os especialistas consultam são as ferramentas. Três consequências práticas: - O tom de voz mora num lugar só: no Supervisor. - O especialista não vê a conversa inteira. Ele recebe só o que o Supervisor contou. - Se nenhum especialista executa uma ação, o sistema não executa. O Supervisor não tem acesso a sistemas. :::success O princípio que organiza tudo: julgamento de linguagem fica no modelo; sequência, validação e estado ficam nas ferramentas. Veja Boas práticas para criar um Agente Especialista. ::: Exemplos em produção 🎥 Vídeo de demonstrações Antecipação de check-in — hospedagem Cliente informa que o voo chegará mais cedo. O especialista: - Explica regras gerais (check-in antes das 13h tem cobrança) - Solicita código de reserva para consultar a API - Verifica disponibilidade — entrada antes das 11h indisponível - Oferece check-in gratuito entre 13h-15h (cortesia) - Cliente aceita → o especialista chama a ferramenta para registrar no sistema - Confirma → ticket encerrado sem intervenção humana :::info Por que solicitar o código de reserva? A disponibilidade é específica de cada reserva — a ferramenta precisa do parâmetro para consultar a API. ::: Consulta de limite de crédito — fintech Cliente pergunta sobre fatura, depois sobre aumento de limite. A ClaudIA: - Responde sobre fatura via base de conhecimento - Ativa a ferramenta de consulta de crédito quando muda o tópico - Usa o helpdeskId automaticamente, porque a ferramenta declara um parâmetro com esse nome — sem pedir dados de novo (veja como configurar) - Retorna limite atual, valor disponível e regras - Orienta sobre antecipar parcela para liberar limite Rastreamento com código inválido — varejo Cliente informa código de pedido com mais dígitos do que o esperado. O especialista: - Identifica que o código está fora do formato esperado - Em vez de erro genérico, orienta com exemplo prático - Cliente fornece o código correto → ticket resolvido :::info Como a IA soube? A descrição da ferramenta especifica o formato esperado. Quando a entrada não corresponde, a ClaudIA decide não ativar a chamada. ::: Como criar uma ferramenta As ferramentas são configuradas no espaço de trabalho da ClaudIA, dentro da configuração do agente. Cada ferramenta representa uma chamada de API. A configuração tem três blocos: Bloco 1 — Declaração de variáveis Define quais dados a ClaudIA extrairá da conversa para a chamada: - Nome: cpf, codigo_pedido, email - Descrição: "CPF do cliente, 11 dígitos, apenas números" A descrição instrui a IA sobre o que coletar e em qual formato. Se o dado já estiver no histórico, a ClaudIA o extrai automaticamente. Bloco 2 — Chamada de API - Endpoint — URL - Método — GET, POST, PATCH - Headers — ex: Authorization - Corpo / Parâmetros — usando as variáveis do Bloco 1 Bloco 3 — Configuração da resposta - Resposta completa — toda a resposta da API - Resposta filtrada (JSON específico) — útil quando a API retorna dados sensíveis (tokens, IDs internos, dados bancários) A descrição da ferramenta É um dos campos mais importantes: é por ela que o especialista escolhe a ferramenta certa, na hora certa, com os dados certos. Escreva uma frase de propósito e três blocos curtos: - O que faz, em linguagem de negócio (não "chama o endpoint de orders") - Quando usar: a situação que justifica a chamada - Quando não usar: a ferramenta vizinha que é fácil de confundir com esta - O que devolve: os resultados possíveis, com nome. Exemplo: encontrou um, encontrou vários, não encontrou, cliente não existe A descrição de cada variável também conta: diga o que é o dado, o formato (ex: "código de pedido com 6 dígitos, formato #XXXXXX") e de onde tirar quando há mais de uma origem possível na conversa. Exemplos completos em Boas práticas para criar um Agente Especialista. Boas práticas :::success - Escreva descrições precisas — controlam quando cada ferramenta é usada - Especifique o formato dos parâmetros — quantidade de dígitos, prefixo, tipo - Use resposta filtrada para dados sensíveis e para devolver só os campos que o especialista usa - Reúna o material antes de começar — veja O que preparar antes de montar um Agente Especialista - Refine com base em casos reais — os especialistas melhoram com o uso :::

Última atualização em Oct 14, 2026

Como criar agentes com linguagem natural (AI Companion)

Quando usar - Você quer criar agentes do zero sem configurar tudo manualmente - Você quer migrar um fluxo de Fluxo Controlado/Typebot existente para Agentes Especialistas - Você prefere descrever em linguagem natural o que precisa em vez de configurar campos Pré-requisitos - Acesso à área de Agentes Especialistas no Painel da ClaudIA - (Para migração) Um fluxo de Fluxo Controlado/Typebot já existente no seu workspace (o Companion lista automaticamente) - (Recomendado) Dados das APIs prontos: URL, método, headers, parâmetros Sobre este artigo O AI Companion é um sistema de "agentes que criam agentes". Em vez de configurar manualmente cada especialista, cada ferramenta e cada Supervisor, você descreve em linguagem natural o que precisa — e o Companion cria toda a estrutura de especialistas para você. Você acessa pela tela de agentes: - Cloud Chat: - OAP: O que o Companion cria | Componente | O que é | Exemplo | | --- | --- | --- | | Tools | Ferramentas que chamam APIs externas | Tool que consulta status de pedido via GET | | Especialistas | Agentes com descrição, instruções e ferramentas | Agente de rastreamento de pedidos | | Supervisor | Orquestrador que roteia e formata respostas | Supervisor com tom amigável e informal | Ao final, você tem um conjunto completo de especialistas — pronto para testar. Como funciona o processo Fase 1 — Levantamento de requisitos O Companion conduz uma conversa para entender: - APIs — endpoints, métodos, headers, parâmetros - Cenários — sucesso, erro, exceções - Tom de voz do atendimento - Quando escalar para humano :::error Nessa etapa não passe API tokens reais. Use placeholders genéricos (ex: TOKEN_API_KEY) e edite o valor verdadeiro depois, direto na tela de Ferramentas. ::: Fase 2 — Criação das tools Com base na spec, o Companion cria automaticamente as tools — URL, método, headers e parâmetros. Fase 3 — Criação dos agentes e Supervisor O Companion cria os especialistas com descrição e instruções, vincula as ferramentas e monta o Supervisor. Acompanhando a análise Análises do Companion — principalmente as do migrador de fluxos — podem levar alguns minutos. Pra você não ficar no escuro durante esse tempo: - Durante o processamento, um indicador inline mostra a etapa atual e o tempo decorrido (ex: "Etapa 3 · 2:14") - A sessão fica salva no navegador por até 24h — pode recarregar a página, fechar a aba ou voltar mais tarde que continua do mesmo ponto - Se você abrir o AI Companion em outra aba, a conversa sincroniza automaticamente - Se o stream for interrompido (queda de rede, reload), a mensagem incompleta aparece marcada visualmente — você sabe que aquela linha ficou pela metade - Botão "Start over" disponível pra descartar a sessão atual e recomeçar do zero quando quiser Dois modos de uso Ao abrir o AI Companion, aparece um modal de início com duas opções: Criar do zero Você descreve o que precisa e o Companion levanta os requisitos. Use quando não tem fluxo existente. Migrar um fluxo de Fluxo Controlado/Typebot Você seleciona um Fluxo Controlado/Typebot da lista do seu workspace (o Companion lista automaticamente). O JSON do fluxo é carregado e o Companion analisa a estrutura: - Webhooks viram tools - Condicionais viram cenários - Mensagens viram tom de voz Use quando quer modernizar um fluxo que já existe. :::info A escolha do modo (criar do zero ou migrar) também aparece quando você clica em Start over no meio de uma conversa — você não cai mais num confirm dialog, mas no mesmo modal de início. ::: O que você precisa fornecer Para criar do zero - O que o especialista resolve, em uma frase — se precisar de "e", provavelmente são dois especialistas - Dados das APIs — URL, método HTTP, headers, parâmetros e os campos do retorno que o atendimento realmente usa - Todos os resultados possíveis de cada consulta, incluindo os ruins — encontrou um, encontrou vários, não encontrou, status inesperado, erro - Regras de negócio — o que concluir de cada resultado e o veredito dos casos ambíguos - Especialistas vizinhos — o que é deste especialista e o que é de outro - Dez frases reais de clientes — cinco que devem cair neste especialista e cinco que não devem - Regras de transferência ancoradas em dado — "se o status for X, transferir", e não "se o cliente estiver irritado". Se não houver nenhum caso, diga isso - Tom de voz — como o Supervisor deve se comunicar (só no primeiro especialista do projeto) O checklist completo está em O que preparar antes de montar um Agente Especialista. :::info O Companion vai perguntar o que estiver faltando — mas quanto mais contexto, mais rápido e preciso o resultado. ::: Para migrar um fluxo existente - Fluxo Controlado selecionado — escolhido na lista do workspace dentro do modal de início - Contexto adicional — regras de negócio que não estão explícitas no fluxo O que o Companion não faz :::warning - Não modifica agentes existentes — ele cria novos. Para editar, use o OAP - Não cria APIs — ele cria tools que chamam APIs (a API precisa existir) - Não configura base de conhecimento — Companion monta os especialistas e o Supervisor; conteúdos da base são configurados separadamente - Não garante que a API funciona — se o endpoint estiver errado/offline, a tool falha ::: Se algo der errado O Companion executa em ordem: spec → tools → agentes. Se uma fase falhar: - Não retenta automaticamente (evita duplicação) - Informa o erro e pede para iniciar nova conversa - Componentes criados com sucesso antes da falha permanecem — você pode visualizá-los/removê-los manualmente no OAP Boas práticas :::success - Seja específico com APIs — endpoints completos, headers, formato de parâmetros - Descreva cenários reais — em vez de "trate erros", diga "quando o pedido não for encontrado, peça novamente e explique o formato (#XXXXXX)" - Um fluxo por conversa — não misture múltiplos fluxos na mesma conversa - Revise antes de publicar — abra cada agente no OAP e revise prompts, descriptions e tools - Teste no Playground — antes de produção, teste com cenários reais ::: Erro: "Projeto não configurado" Se ao abrir o AI Companion aparecer "Projeto não configurado", é porque o seu usuário do Painel da ClaudIA não tem nenhum projeto atribuído no ambiente atual — não é uma falha do sistema. Verifique, nesta ordem: 1. Confirme que você está no ambiente/conta correto (o seletor de projeto usa o ambiente ativo). 2. Confirme que seu usuário tem ao menos um projeto atribuído. Se você acabou de receber acesso, peça a um administrador para vincular seu usuário a um projeto. 3. Saia e entre de novo (logout/login). A lista de projetos é carregada no login — se o acesso foi concedido agora, ela só aparece depois de reentrar. 4. Se ainda assim persistir, fale com o administrador/suporte da sua conta. Observações - Para o Supervisor: Como configurar o Supervisor - Para revisar o que o Companion gerou: Como escrever a descrição e as instruções de um Agente Especialista - Para boas práticas: Boas práticas para criação de agentes - Para conectar tools externas: Como conectar ferramentas externas via MCP Servers - Para navegar pela interface: Como navegar pela interface dos Agentes Especialistas - Para decidir entre Fluxo Controlado e Agentes Especialistas: Quando usar Fluxo Controlado ou Agentes Especialistas (comparativo)

Última atualização em Oct 14, 2026

Como auditar conversas em que um Agente Especialista foi acionado

Quando usar - Você quer auditar o comportamento dos agentes em produção - Você quer ver quais conversas acionaram Agentes Especialistas - Você quer priorizar tickets com muitas chamadas ou que terminaram em N2 Pré-requisitos - Acesso ao Painel da ClaudIA com os Agentes Especialistas habilitados - Período de tempo com chats em que algum Agente Especialista foi acionado Sobre este artigo A aba Uso Agêntica dentro do Dashboard lista todos os chats em que algum Agente Especialista foi acionado no período selecionado. Serve para auditar o comportamento dos agentes em produção — ver quais conversas dispararam chamadas, quantas foram, e em que nível foram encerradas. Como acessar Etapa 1 — Acessar o Painel da ClaudIA Acesse cloudchat.cloudhumans.com. Etapa 2 — Abrir o Dashboard No menu lateral, clique em Dashboard. Etapa 3 — Aba Uso Agêntica Na barra de abas no topo, vá até a última aba à direita: Uso Agêntica. Etapa 4 — Filtrar por período Ajuste com Data Inicial e Data Final. Aba Uso Agêntica O que cada coluna significa | Coluna | Significado | | --- | --- | | cloud_chat_url | Link direto para o chat no Painel da ClaudIA. Clicar abre a conversa completa | | projectname | Projeto ao qual o chat pertence | | first_agentic_date | Data da primeira chamada de um especialista naquele chat | | agentic_calls | Quantas vezes os especialistas foram chamados na conversa | | level | Nível em que a conversa finalizou | Como usar para auditoria :::success - Priorize chats com muitas agentic_calls e nível N2 — múltiplas chamadas em uma mesma conversa podem indicar loops, falhas de tool, ou que o agente não conseguiu resolver de primeira - Use o first_agentic_date para focar em casos recentes ou cruzar com mudanças de configuração que você fez no agente - Abra o chat pelo cloud_chat_url para ver a conversa completa do agente ::: Observações - Para boas práticas de auditoria: Quais as melhores práticas para auditar a ClaudIA - Para entender as razões de transferência: Como funciona a ClaudIA e o processo de auditorias - Para entender os Agentes Especialistas: O que são os Agentes Especialistas e como funcionam

Última atualização em Oct 14, 2026

Como navegar pela interface dos Agentes Especialistas

Quando usar - Você é novo na tela de Agentes Especialistas e quer entender o que cada parte faz - Você precisa criar, testar, publicar ou manter agentes - Você quer entender as três abas (Agentes, Ferramentas, Servidores MCP) Pré-requisitos - Acesso à área de Agentes Especialistas no Painel da ClaudIA - (Recomendado) Conhecimento dos conceitos — ver O que são os Agentes Especialistas Sobre este artigo Este guia explica, tela por tela, como usar a área de Agentes Especialistas — onde você cria, testa, publica e mantém os agentes que vão atender seus clientes. O foco aqui é navegação e uso da interface (para conceitos, use os outros artigos). https://www.loom.com/share/8fa6d0df23b94549ac1ef6fd28b574d5 As três abas da plataforma A área de Agentes Especialistas é dividida em três abas no menu lateral: 1. Agentes — onde você cria e gerencia o Supervisor e os Especialistas 2. Ferramentas (Tools) — onde você cria e configura as chamadas de API que os especialistas podem usar 3. Servidores MCP — onde você gerencia conexões via Model Context Protocol que disponibilizam tools para a plataforma As três abas Aba Agentes Lista todos os agentes do projeto, dividida em duas seções: - Supervisores — o orquestrador (normalmente um só). Mostra quantos especialistas estão vinculados - Especialistas — os Agentes Especialistas. Cada linha mostra nome, trecho da descrição e quantas tools estão ativas Filtro por projeto (workspace) No canto superior direito, antes do botão de criar, existe um seletor de projeto. Cada conta pode ter mais de um workspace. :::info Se você só vê um projeto ou o seletor aparece desabilitado, é porque sua conta tem apenas um workspace disponível — comportamento normal. ::: Os dois caminhos para criar um agente 1. Montar com AI Companion (botão laranja, à esquerda) — abre um modal de início com duas opções: começar do zero ou migrar um Fluxo Controlado existente do workspace. Em ambos os casos, o Companion conduz a criação em linguagem natural. 2. + Criar (botão laranja, à direita) — abre o formulário manual para criar um especialista ou Supervisor. Recomendado para quem já entende a estrutura. :::success Os dois caminhos coexistem — você pode criar a base com o Companion e refinar manualmente. ::: Ações em cada linha À direita de cada agente: 1. Testar (Playground) — abre o Playground encaixado para conversar com o agente em modo teste 2. Duplicar — cria uma cópia para editar sem mexer no original (útil para testar variações de prompt) 3. Editar — abre o formulário do agente 4. Deletar — remove o agente :::warning Se for um especialista vinculado ao Supervisor, é preciso desvinculá-lo antes de deletar. ::: Criando um especialista manualmente Ao clicar em + Criar → Especialista, abre o modal com quatro campos: Modal Criar especialista 1. Nome do especialista — identifica na lista. Use algo descritivo como "Especialista em Status de Pedidos". Não aparece para o cliente. 2. Descrição — texto que o Supervisor lê para decidir quando chamar. A regra de roteamento mora aqui. Use linguagem do cliente. 3. Instruções de comportamento — o que o especialista deve fazer quando acionado. 4. Tools — lista de ferramentas disponíveis. Ative apenas as que o especialista precisa. Selecionar todas liga todas de um servidor de uma vez. Após salvar, o especialista vai para a seção "Especialistas" e fica pronto para ser vinculado ao Supervisor. Para o Supervisor, o fluxo é parecido com campos próprios (instruções gerais e tom de voz, especialistas vinculados). Criando com AI Companion Ao clicar em Montar com AI Companion, a tela troca para um chat. Você descreve em linguagem natural e o Companion conduz a conversa. Tela do Companion :::error Não cole tokens reais ou API keys aqui — use placeholders genéricos (ex: TOKEN_API_KEY) e edite o valor verdadeiro depois, direto na tela de Ferramentas. ::: Testando no Playground Para abrir, clique no ícone do balãozinho na linha do agente. Playground No topo do painel direito: 1. Seletor de agente — troca o agente sem fechar o painel 2. Reiniciar conversa — limpa o histórico (use sempre que terminar um caso de teste) No corpo da conversa, sempre que o agente chama uma tool, aparece um bloco Saída da tool expansível mostrando o nome, o JSON cru e o call_id. O toggle Ocultar chamadas de tool mostra só a conversa do ponto de vista do cliente. Aba Ferramentas Lista todas as tools criadas no projeto, com nome, descrição curta, número de parâmetros, criação e atualização. Aba Ferramentas Criando uma ferramenta Clique em + Criar ferramenta: Modal criar tool 1. Nome — usado pelo agente internamente. Sem espaços, prefira snake_case (ex: consultar_endereco_por_cep) 2. Descrição da ferramenta — campo mais importante. É com base nela que o agente decide se usa essa tool durante o reasoning. :::warning Descrições genéricas geram chamadas erradas e silenciosas. Especifique o que a tool faz, qual API consome, quais parâmetros precisa receber e em qual formato. ::: Após criar, a ferramenta abre no editor visual de Fluxos Controlados onde você monta a chamada de API. Observações - Para conceitos: O que são os Agentes Especialistas e como funcionam - Para criar com IA: Como criar agentes com linguagem natural (AI Companion) - Para o Supervisor: Como configurar o Supervisor - Para escrever especialistas: Como escrever a descrição e as instruções de um Agente Especialista - Para servidores MCP: Como conectar ferramentas externas via MCP Servers

Última atualização em Oct 14, 2026

Treinamento: visão geral da criação de Agentes Especialistas

Quando usar - Você é novo nos Agentes Especialistas e quer um treinamento completo guiado em vídeo - Você quer entender, em visão geral, como os Agentes Especialistas decidem e como se cria uma atuação - Você vai criar sua primeira atuação e quer ver o passo a passo antes de mergulhar nos artigos específicos Sobre este artigo Aqui você encontra o vídeo de overview da criação de atuação com Agentes Especialistas, explicando a mudança de fluxos controlados para uma arquitetura conversacional com agentes, como a decisão acontece e como criar uma atuação do zero. :::info Se você ainda não conhece os conceitos básicos, comece por O que são os Agentes Especialistas e como funcionam e depois volte para este treinamento. ::: Vídeo de treinamento https://www.loom.com/share/0681c79396dd48cdb342a85bdce4432e O que você vai ver no vídeo A mudança de fluxos controlados para arquitetura conversacional A operação de atendimento sai de fluxos fixos (controlados, no estilo de Fluxo Controlado) para uma arquitetura conversacional com agentes. Os fluxos fixos eram mais engessados, mais difíceis de manter e podiam gerar loops quando o cliente saía do escopo previsto. Na nova arquitetura, a ClaudIA tradicional passa a ser apenas uma opção de fallback. Como a decisão acontece (o Judge) Cada mensagem do cliente chega primeiro ao Judge, que decide o caminho: 1. Acionar um Supervisor com Agentes Especialistas, ou 2. Encaminhar a conversa para a ClaudIA (fallback). Casos mais complexos são orquestrados pelo Supervisor, que controla as chamadas a APIs por meio de tools. :::info A decisão do Judge acontece em milissegundos. O tempo total da resposta depende das chamadas das tools — por exemplo, uma consulta de CEP pode ser bem rápida. ::: Como criar uma atuação do zero O vídeo também demonstra como criar um fluxo de agente do zero usando o AI Companion, montando a atuação com linguagem natural. Observações - Para se aprofundar em cada parte da arquitetura, siga os artigos: Como configurar o Supervisor dos Agentes Especialistas, Como escrever a descrição e as instruções de um Agente Especialista e Como criar agentes com linguagem natural (AI Companion). - Em dúvida entre manter um fluxo controlado ou migrar para Agentes Especialistas? Veja Quando usar Fluxo Controlado ou Agentes Especialistas (comparativo). - Para conhecer a tela onde tudo isso é montado: Como navegar pela interface dos Agentes Especialistas.

Última atualização em Oct 14, 2026

Como investigar o motivo de uma resposta do Agente

Quando usar - Você quer entender por que o Agente respondeu de determinada forma em uma conversa específica. - Você suspeita que o Agente usou o conteúdo errado, alucinou ou tomou uma decisão inesperada. - Você já identificou um problema e quer sair direto com uma causa raiz e uma sugestão de correção. Como funciona Duas funcionalidades ajudam nessa investigação: a auditoria direto no ticket e a investigação via AI Companion. Auditoria de conversas dentro do ticket Direto na tela da conversa, você consegue ver o raciocínio completo por trás de uma resposta gerada por um agente especialista. Sempre que um agente especialista for acionado, aparece um ícone de lupa laranja ao lado do balão de mensagem correspondente. Ao clicar nesse ícone, abre uma janela com os detalhes de todo o processo: - Como o Judge raciocinou para escolher aquele agente especialista; - Como o agente especialista se comportou durante o atendimento; - Como o supervisor avaliou e utilizou o retorno do agente especialista. Você também tem acesso ao contexto que foi analisado e à lógica que levou à mensagem enviada — ou seja, a justificativa completa daquela interação específica. :::info Onde encontrar: dentro de qualquer conversa no Cloud Chat em que um agente especialista tenha sido acionado, procure pelo ícone de lupa laranja ao lado da mensagem. ::: Investigar uma conversa pelo AI Companion Quando você quer ir além do "o que aconteceu" e já sair com uma correção pronta, use o AI Companion para investigar a conversa em linguagem natural. 1. Acesse ClaudIA > Agentes > Montar com AI Companion > Investigar uma conversa. 2. Cole a URL da conversa que deseja investigar. 3. Uma tela de chat com o AI Companion será aberta. Ali você pode adicionar contexto sobre o que aconteceu e perguntar, por exemplo, "por que isso aconteceu?" — ou direcionar a análise da forma que preferir. 4. Se precisar de mais informações, o AI Companion vai te pedir. Caso contrário, ele já retorna com a causa raiz (ou hipóteses, quando não houver certeza absoluta) e uma sugestão de ajuste (fix). 5. A partir da análise, você pode pedir para o AI Companion aplicar o ajuste e publicar direto em produção, ou aplicar o ajuste como rascunho. :::success Opção recomendada: aplicar como rascunho. Isso permite revisar as mudanças no prompt antes de publicar manualmente o agente ajustado. ::: :::info Onde encontrar: no menu ClaudIA, acesse Agentes e clique em Montar com AI Companion. ::: Veja as duas funcionalidades na prática no vídeo abaixo. https://www.loom.com/share/c43d64062f844244b2249473b864b451 Observações - As duas funcionalidades podem ser usadas em conjunto: comece pela auditoria no ticket para entender o "o quê" e use o AI Companion quando quiser ir direto para a causa raiz e uma correção. - O vídeo acima mostra as duas funcionalidades na prática.

Última atualização em Aug 05, 2026

Como o Supervisor decide qual Agente Especialista responde

Quando usar - Você quer entender a diferença entre o Supervisor e os Agentes Especialistas - Um atendimento foi transferido para o especialista errado (ou não foi transferido quando deveria) - Você ajustou uma instrução no Supervisor e ela não mudou o comportamento do especialista - Você quer saber por que a ClaudIA acionou (ou não acionou) um Agente Especialista numa conversa específica Sobre este artigo Em projetos que usam Agentes Especialistas, o atendimento não é conduzido por um único agente genérico: existe um Supervisor, que conduz a conversa, e um ou mais Agentes Especialistas, cada um focado em um assunto (por exemplo, cancelamento, status de pedido, cobrança). Quando identifica que o assunto é de um especialista, o Supervisor transfere a condução da resposta para ele. Como funciona Como o Supervisor decide qual especialista acionar O Supervisor não segue uma lista fixa de regras "se o cliente disser X, chame o especialista Y". A decisão é feita a partir da descrição de cada Agente Especialista — é esse texto que diz ao Supervisor quando aquele especialista deve ser chamado. Por isso, a qualidade da descrição impacta diretamente a precisão do roteamento: uma descrição vaga ou ambígua leva a acionamentos incorretos ou a especialistas que nunca são chamados. :::info Se dois especialistas têm descrições parecidas, o Supervisor pode confundir os dois. Deixe cada descrição o mais específica e exclusiva possível. ::: Como escrever e testar uma boa descrição - Um especialista, uma responsabilidade. Se você precisa de "e" para descrever o que ele resolve, provavelmente são dois especialistas. - Use o formato executa / não executa / acione quando / não acione quando / teste final, com o destino de cada assunto vizinho. O modelo está em Templates para escrever um Agente Especialista. - Use a linguagem do cliente, não termos internos. - Faça o teste das dez frases: separe cinco frases reais de clientes que devem cair neste especialista e cinco que não devem, de preferência casos de fronteira. Lendo só a descrição, cada uma é decidida corretamente? Se alguma fica em dúvida, a descrição ainda não está pronta. Quando um especialista não é acionado como esperado, o problema quase sempre está na descrição dele ou na do vizinho, e não nas instruções. Por que um ajuste no Supervisor não muda a resposta do especialista Uma dúvida comum é adicionar uma instrução na configuração do Supervisor (por exemplo, "sempre informe o prazo em dias úteis") e perceber que o Agente Especialista continua respondendo do jeito antigo. Isso acontece porque a configuração do Supervisor só influencia a decisão de para quem transferir — ela não é repassada como instrução para o especialista escolhido. Se o comportamento que precisa mudar acontece dentro da resposta do especialista (o texto que ele manda, quando ele escala para humano, etc.), a regra precisa ser adicionada na configuração daquele Agente Especialista específico, e não na do Supervisor. Usando o AI Companion para escrever a descrição de um especialista Na tela de Agentes do Painel da ClaudIA, o AI Companion ajuda a escrever e refinar a descrição/instrução de um Agente Especialista a partir de uma explicação em linguagem natural do que ele deve fazer. É a ferramenta recomendada quando o roteamento do Supervisor está ambíguo ou quando um especialista está respondendo fora do esperado: em vez de editar o texto manualmente por tentativa e erro, descreva o comportamento desejado para o AI Companion e revise a sugestão gerada. Conferindo a decisão do Supervisor numa conversa Cada atendimento tem uma auditoria de raciocínio disponível no Painel da ClaudIA, mostrando se o Supervisor acionou um especialista naquela conversa e qual foi o motivo considerado na decisão. Use essa auditoria para confirmar, conversa a conversa, se o roteamento aconteceu como esperado antes de decidir ajustar a descrição de um especialista. Observações - Para testar mudanças de roteamento antes de publicar, use o Playground — ele permite simular o Supervisor e cada especialista isoladamente, sem impactar clientes reais. - Para o passo a passo de criar, vincular e publicar um Agente Especialista, veja "Como criar, editar e publicar um Agente Especialista".

Última atualização em Oct 15, 2026

Como criar, editar e publicar um Agente Especialista

Quando usar - Você quer criar um novo Agente Especialista para um assunto específico - Você editou um especialista e ele "não aparece" ou não está sendo acionado - Você não sabe a diferença entre um especialista em rascunho e um publicado - Você quer testar um Agente Especialista antes de colocá-lo no ar Pré-requisitos - Acesso de administrador ao Painel da ClaudIA do projeto - Um Supervisor já configurado no projeto (o Agente Especialista precisa estar vinculado a ele para entrar em produção) Sobre este artigo Todo Agente Especialista passa por um ciclo de vida: ele é criado como rascunho, é vinculado ao Supervisor, testado no Playground e só então publicado para atender clientes de verdade. Este artigo explica cada uma dessas etapas e os motivos mais comuns de um especialista "sumir" ou não ser acionado. Passo a passo Etapa 1 — Criar o Agente Especialista Na tela de Agentes do Painel da ClaudIA, crie um novo especialista com um nome e uma descrição claros (veja "O que são Agentes Especialistas e como o Supervisor decide quem responde" para dicas de como escrever essa descrição). Ao ser criado, ele fica em rascunho — só visível para configuração, ainda não é usado em nenhum atendimento real. Etapa 2 — Vincular ao Supervisor Para o especialista poder ser acionado, ele precisa estar na lista de especialistas do Supervisor. Esse vínculo é feito na configuração do próprio Supervisor, adicionando o novo Agente Especialista à lista. :::warning ::: Etapa 3 — Testar no Playground Antes de publicar, teste o novo especialista no Playground. No seletor do Playground, o grupo Especialistas permite testar o especialista isoladamente, e o grupo Supervisores permite testar o fluxo completo (Supervisor decidindo se aciona ou não o novo especialista). Nenhuma mensagem enviada no Playground chega a clientes reais. Etapa 4 — Publicar Enquanto estiver em rascunho, o Agente Especialista não pode ser usado em produção — ele precisa ser publicado primeiro. Depois de publicado, hoje você precisa acionar alguém do time pelo Suporte para ativar ele em produção. Observações - "Criei o especialista mas ele não aparece/não é acionado" — na grande maioria dos casos, é uma destas duas situações: (1) ele ainda está em rascunho e não foi publicado, ou (2) ele não está (mais) vinculado ao Supervisor certo. Confira essas duas coisas antes de abrir um chamado de suporte. - "Apareceu um erro dizendo que o Supervisor está bloqueado" — isso normalmente é concorrência: outra pessoa (ou outra aba) está editando o mesmo Supervisor ao mesmo tempo. Aguarde alguns segundos e tente novamente. - Depois de publicado, use a auditoria de conversas para confirmar que o especialista está sendo acionado como esperado — veja "Ativação gradual (Teste A/B) e auditoria de um Agente Especialista".

Última atualização em Oct 15, 2026

Como funciona o Agente de Q&A e como configurá-lo

Quando usar - Você quer criar um especialista que responda a um tema com base em conteúdo, sem executar ações - A ClaudIA mistura informações de um tema denso (técnico, com vocabulário próprio) com o restante da base - Você tem documentação extensa já pronta — central de ajuda, documentação técnica, manual — e quer que a ClaudIA responda com base nela - Um Agente de Q&A está sendo acionado para assuntos que não são dele, ou responde que não encontrou algo que existe Pré-requisitos - Um Supervisor já configurado no projeto — o Agente de Q&A precisa estar vinculado a ele para entrar em produção - O conteúdo do tema: conteúdos já escritos ou os links da documentação para importar Sobre este artigo O Agente de Q&A é um Agente Especialista que responde consultando apenas as bases de conhecimento selecionadas para ele. Ele serve para isolar um tema denso e fazer a ClaudIA responder esse tema com mais precisão, sem misturá-lo com o restante da base do projeto. :::info Agente de Q&A ou especialista com ferramentas? O especialista com ferramentas consulta sistemas e executa ações, como rastrear um pedido ou emitir uma segunda via. O Agente de Q&A só consulta conhecimento: ele não acessa dados da conta do cliente nem executa nada. ::: Como funciona O caminho de uma mensagem O Agente de Q&A segue a mesma arquitetura dos demais Agentes Especialistas: 1. Judge — compara a mensagem do cliente com as descrições dos agentes. Se nenhum se aplica, a ClaudIA responde pelo atendimento padrão, com a base de conhecimento do projeto. 2. Supervisor — seleciona o Agente de Q&A quando o assunto é dele. 3. Agente de Q&A — pesquisa na base dele por significado, não por palavra exata, e pode fazer mais de uma busca para montar a resposta. Depois devolve o que encontrou ao Supervisor. 4. Supervisor — escreve a resposta final com o tom de voz do projeto. Fluxo: Judge → Supervisor → Agente de Q&A → busca na base → Supervisor → resposta ao cliente :::warning O agente só sabe o que está nas bases dele. Se um conteúdo não está lá, ele não tem como responder — e pode concluir, errado, que aquilo não existe. Exemplo: um agente com a documentação técnica da API não sabe quais integrações prontas o produto oferece se essa lista estiver apenas no site comercial. ::: Os campos de configuração Na tela de Agentes do Painel da ClaudIA, use Criar e escolha o agente de Q&A. Três campos definem o comportamento dele: | Campo | O que define | | --- | --- | | Nome | Como o agente aparece no painel. Use o tema, de forma direta. | | Descrição | Quando o agente é acionado. É o campo mais importante — veja a próxima seção. | | Bases de conhecimento | Tudo o que o agente sabe. Ele responde apenas com o conteúdo das bases selecionadas; é possível selecionar mais de uma. | Como escrever a descrição A descrição é o texto que o Supervisor usa para decidir se e quando acionar o agente. Use o mesmo formato dos demais Agentes Especialistas: O QUE FAZ: <1-3 frases: o tema, o tipo de dúvida que o agente responde e com base em quê.> QUANDO ACIONAR: <Os pedidos do cliente que disparam este agente, na linguagem do cliente.> QUANDO NÃO ACIONAR: <Os temas vizinhos, que parecem próximos mas não são deste agente.> :::info E os pré-requisitos de invocação? No Agente de Q&A eles raramente se aplicam, porque o agente só consulta conhecimento. A exceção é quando a resposta certa depende de um dado do cliente — por exemplo, a versão do produto que ele usa. Nesse caso, declare esse dado para o Supervisor coletá-lo antes de acionar o agente. ::: Exemplo — Agente de Q&A da documentação técnica da API: O QUE FAZ: Responde dúvidas técnicas de quem está integrando com a API do produto, consultando a documentação técnica na base de conhecimento. Explica endpoints, campos, autenticação, webhooks e códigos de erro, e cita o link da documentação que sustenta a resposta. QUANDO ACIONAR: Cliente já decidiu construir a integração via API e pergunta como implementar: endpoint, requisição, token de acesso, ambiente de testes, webhook, código de erro HTTP — ou cola trechos de código ou JSON. QUANDO NÃO ACIONAR: - Cliente pergunta se existe integração pronta com alguma ferramenta — isso é assunto da página de integrações, não da API. - Dúvida sobre uso da plataforma pela interface, plano, contrato ou cobrança. - Consulta ao status de algo específico da conta do cliente — o agente não acessa a conta. Três cuidados que fazem diferença: - Evite gatilhos ambíguos. Uma palavra que aparece em vários temas — como "integração", "pedido" ou "documento" — faz o agente ser acionado sempre que ela surge. Prefira expressões que descrevam a intenção. - Descreva a intenção, não só palavras. "Quero integrar com a ferramenta X" e "como faço a autenticação na API" usam o mesmo vocabulário, mas são dúvidas diferentes. - Não repita as regras de roteamento no Supervisor. A descrição já faz esse papel; repetir cria duas fontes de verdade. :::success O AI Companion ajuda a escrever e revisar a descrição a partir de uma explicação em linguagem natural. Veja Como criar agentes com linguagem natural (AI Companion). ::: Como montar a base do agente O agente responde apenas com o que está nas bases selecionadas. Há duas formas de alimentar uma base: | Forma | Como funciona | Quando usar | | --- | --- | --- | | Fonte de conteúdo | Você cadastra um link; a ClaudIA lê a página e a transforma em conteúdo. É possível programar atualização periódica. | Documentação que já existe em um site: central de ajuda, documentação técnica, manual | | Conteúdo customizado | A equipe escreve a pergunta e a resposta | Regras, exceções e respostas que não estão em nenhuma página | Cada conteúdo é marcado como N1, quando a ClaudIA resolve, ou N2, quando ela transfere para o time humano. Boas práticas: - Título com as várias formas de perguntar. A busca é por significado, e o título pesa nela. Exemplo: "Como gerar o token de acesso / Onde crio a chave da API / Meu token não funciona". - Um assunto por conteúdo. Evite dois conteúdos sobre o mesmo tema com informações diferentes. - Resposta objetiva, com o link da fonte quando houver. - Base dedicada ao tema. Selecionar a base principal do projeto inteira faz o agente saber de tudo — e perde-se o motivo de ter um especialista. - Rede de segurança na base principal. O acionamento não é 100% previsível. Mantenha na base principal uma versão curta das respostas mais comuns do tema, para quando a pergunta seguir pelo atendimento padrão. Quando vale criar um Agente de Q&A | Vale criar um Agente de Q&A | Basta um conteúdo na base principal | | --- | --- | | Tema técnico, com vocabulário próprio | Pergunta pontual ou simples | | Documentação extensa já pronta, como uma central de ajuda ou documentação técnica | Tema que a ClaudIA já responde bem hoje | | Tema em que a ClaudIA mistura informações de assuntos diferentes | Poucas respostas, que cabem em alguns conteúdos | Se a dúvida exige consultar dados do cliente ou executar uma ação, o caminho é um especialista com ferramentas — veja Como escrever a descrição e as instruções de um Agente Especialista. Como testar e publicar O Agente de Q&A segue o mesmo ciclo de vida dos demais especialistas: rascunho, vínculo ao Supervisor, teste e publicação. O passo a passo completo está em Como criar, editar e publicar um Agente Especialista. No Playground, teste em dois níveis: 1. Grupo Especialistas — o agente isolado: confira se ele responde bem com base no conteúdo da base. 2. Grupo Supervisores — o fluxo completo: confira se o Supervisor aciona o agente nas perguntas certas e não aciona nas perguntas de temas vizinhos. :::info As perguntas de temas vizinhos são as mais reveladoras. São elas que mostram se o QUANDO NÃO ACIONAR está bem escrito. ::: Depois de publicado, o agente normalmente entra no ar de forma gradual. Veja Ativação gradual (Teste A/B) e auditoria de um Agente Especialista. Erros comuns - Descrição que promete o que a base não tem. Se a descrição cobre um tema sem conteúdo na base, o agente responde de forma vaga ou incorreta. - "QUANDO NÃO ACIONAR" fraco. Sem ele, o Supervisor aciona o agente sempre que uma palavra do tema aparece, mesmo em dúvidas de outro assunto. - Instrução de comportamento no Supervisor. A configuração do Supervisor só influencia a decisão de para quem transferir — ela não é repassada ao Agente de Q&A. O tom de voz da resposta final, esse sim, vem do Supervisor. - Ajuste sem reteste. Alterar a descrição ou a base pode mudar também respostas que já estavam boas. Depois de cada ajuste, reteste inclusive esses casos. Observações - Por ser um modelo de linguagem, o agente pode errar em uma parcela pequena dos casos. Uma base bem cuidada e respostas com o link da fonte reduzem esse risco e deixam cada resposta auditável. - Para conferir, conversa a conversa, se o Supervisor acionou o agente e por quê, veja Como auditar conversas em que um Agente Especialista foi acionado e Como investigar o motivo de uma resposta do Agente. - Para entender a decisão de roteamento em detalhe, veja Como o Supervisor decide qual Agente Especialista responde. - Para boas práticas gerais de especialistas, veja Boas práticas para criar um Agente Especialista.

Última atualização em Oct 14, 2026

Especialista de comentários do Instagram: como montar e boas práticas

Quando usar - Você quer que a ClaudIA responda aos comentários públicos dos posts do seu Instagram. - Você quer resolver dúvidas simples ali mesmo, nos comentários, e levar reclamações para o Direct. - Você vai montar o agente de comentários e quer saber o que preparar antes. Pré-requisitos :::warning A resposta a um comentário fica pública: todo mundo que abre o post lê o que a marca respondeu. Combine a data de ativação com o nosso time e avise quem cuida das suas redes sociais antes de ligar o agente. ::: Antes de montar o agente, tenha em mãos: 1. Instagram conectado ao Cloud Chat, com o recebimento de comentários ativo na caixa de entrada. 2. Manual de marca para o Instagram. Como a marca se posiciona, como fala, se usa emoji, se usa gíria e o que nunca pode soar (por exemplo: corporativo ou defensivo). 3. Lista de fatos oficiais. São as informações que o agente pode afirmar em público, como garantia, regiões de entrega, tabela de tamanhos e onde comprar. Ele não afirma nada que esteja fora dessa lista. 4. Comentários reais de cada tipo, tirados dos seus posts: dúvidas, reclamações e elogios. Se o seu time já respondeu a algum deles, inclua também a resposta. 5. O que nunca dizer ou pedir em público. Por exemplo: dados pessoais, número de pedido, promessa de troca ou reembolso, prazos que vocês não garantem. 6. Um time para receber as transferências. Quando o agente transfere um comentário, alguém do seu time precisa identificar a pessoa e falar com ela pelo Direct. Sobre este artigo Este artigo explica como o agente de comentários funciona, que configurações mudam no projeto, como o prompt é organizado e quais cuidados tomar com respostas públicas. Como funciona O que é o agente de comentários? É um Agente Especialista da ClaudIA, dedicado aos comentários dos posts. Cada comentário passa pelo mesmo caminho: 1. A ClaudIA recebe o comentário e aciona o especialista. 2. O especialista identifica o tipo do comentário e decide o desfecho: encerrar o atendimento ali mesmo ou transferir para o seu time. 3. O especialista escreve a resposta e devolve tudo para a ClaudIA. 4. A ClaudIA publica a resposta no comentário. O especialista tem duas ações: encerrar o atendimento, quando o comentário se resolve ali mesmo, e transferir para o time humano, quando o caso precisa de uma pessoa. Que configurações mudam no projeto? O agente de comentários fica num projeto da ClaudIA só para ele, separado do atendimento por Direct. Comentário não é conversa: recebe uma resposta e pronto. Por isso várias configurações do atendimento padrão ficam desligadas nesse projeto: | Configuração | Como fica | Por quê | | --- | --- | --- | | Quebra de mensagens | Desligada | Cada comentário recebe uma resposta só, dentro do limite de caracteres do Instagram. | | Saudação | Desligada | A resposta pública vai direto ao ponto. | | Clarificação | Desligada | O agente responde ou transfere, sem fazer perguntas no comentário. | | Transferir atendimento (N2) | Desligada | Quem decide transferir é o especialista, conforme o tipo de comentário. | | Fechamento com ClaudIA (N1) | Desligado | Quem encerra é o especialista, e nenhuma mensagem de encerramento sai em público. | | Mensagens automáticas de transferência, encerramento e follow-up | Desligadas | Nenhuma mensagem extra pode aparecer embaixo do post. | Na caixa de entrada do Instagram, os comentários vão para o projeto de comentários. O Direct e as respostas a stories continuam no projeto que você já usa. Combine essa separação com o nosso time. Como o agente decide o que fazer com cada comentário? O agente trabalha com quatro cenários: | Cenário | Quando acontece | O que o agente faz | Desfecho | |---|---|---|---| | Dúvida com resposta nos fatos oficiais | Pergunta sobre produto ou marca cuja resposta está na lista de fatos oficiais | Responde com segurança, usando só o que está na lista | Encerra | | Dúvida sem resposta ou caso individual | A resposta não está na lista, ou depende de um pedido, de uma troca ou de outro caso específico | Acolhe a pessoa, não inventa nada e convida para o Direct | Transfere | | Reclamação ou frustração | Insatisfação, crítica ou relato de problema | Responde seguindo a regra dos 3 passos e convida para o Direct | Transfere na hora | | Elogio ou interação | Elogio, emoji, brincadeira, comentário em post com influenciador | Responde em poucas palavras, com carinho, entrando no clima do comentário | Encerra | Duas regras valem para todos os cenários: - Se o comentário pode ser lido como dúvida ou como reclamação, o agente trata como reclamação. - Se o agente fica em dúvida entre responder ou transferir, ele transfere. Qual é a regra dos 3 passos para reclamações? Toda resposta a uma reclamação precisa: 1. Mostrar que ouviu e ter empatia. Exemplo: "Poxa, sentimos muito que isso aconteceu." 2. Pedir desculpas, mesmo que ainda não se saiba de quem foi a falha. A marca responde com humildade e não se defende. 3. Levar para o privado. Exemplo: "Chama a gente no Direct" ou "Vamos te chamar no Direct". A pessoa nunca fica sem retorno. O texto é escrito na hora e muda a cada comentário. O que não pode é faltar um dos três passos. Se preferir uma mensagem fixa para todas as reclamações, coloque o texto exato no prompt. Como a descrição do especialista é organizada? A descrição é o que a ClaudIA lê para decidir quando acionar o especialista. Ela tem três blocos: | Bloco | O que escrever | | --- | --- | | O que faz | Analisa os comentários públicos dos posts, identifica o tipo, decide entre encerrar e transferir e escreve a resposta. | | Quando acionar | Sempre que houver um comentário de post para responder, qualquer que seja o assunto: dúvida, elogio, reclamação, crítica, pergunta sobre pedido, sugestão. | | Quando não acionar | Só quando a mensagem não é um comentário de post, como uma mensagem no Direct. | Não limite o especialista por assunto. Ele cobre qualquer tema que apareça nos comentários. O que o separa dos outros agentes é o canal. Como o prompt do especialista é organizado? | Seção | O que vai nela | | --- | --- | | Papel | Quem é o agente e o que ele devolve para a ClaudIA: o tipo do comentário, o desfecho, a resposta escrita e o motivo da decisão em uma linha. | | Objetivo | Por que todo comentário merece resposta. Quem chega ao perfil lê as respostas antes de virar cliente. | | Ações | Quando encerrar e quando transferir. O agente executa a ação sem pedir autorização. | | Conhecimento | O posicionamento da marca e a lista de fatos oficiais. Só é fato o que está nessa lista. | | Cenários | Cada cenário com três partes: quando acontece, o que fazer e por quê. | | Regra dos 3 passos | Como responder a reclamações. | | Regras críticas | O que nunca fazer em público. | | Tratamento de erro | Se uma ação falhar, tentar mais uma vez e, se continuar falhando, avisar a ClaudIA. Na dúvida entre dúvida e reclamação, tratar como reclamação. | | Fora do escopo | O que o agente não faz: atender pelo Direct, resolver a reclamação sozinho, afirmar o que não está na lista de fatos oficiais. | Escreva o "por quê" de cada cenário. Quando o agente entende o motivo de uma regra, ele acerta também os comentários que não estão nos exemplos. Boas práticas para respostas públicas - Responda a todos os comentários, positivos e negativos. Uma reclamação sem resposta atrai outras. - Não peça dados pessoais nem de pedido no comentário. Número do pedido, CPF, e-mail, telefone e endereço ficam para o Direct. - Não invente nada. Fato, política, prazo, preço, tamanho e disponibilidade só podem vir da lista de fatos oficiais. Uma afirmação errada em público vira print. - Não se defenda nem exponha o cliente, mesmo quando ele estiver errado. - Não prometa solução numa reclamação. Nada de "vamos trocar" ou "vamos reembolsar": quem resolve é o seu time, no privado. - Seja breve e varie as respostas a elogios. A mesma frase repetida em todos os comentários soa automática. Como testar antes de ligar? 1. Rode no ambiente de testes os comentários reais da sua lista, pelo menos um de cada cenário. 2. Para cada um, confira: - Se o cenário identificado está certo. - Se o desfecho está certo (encerrou ou transferiu). - Se o tamanho e o tom estão adequados. - Se a resposta usa só o que está na lista de fatos oficiais. - Nas reclamações, se os 3 passos aparecem. 3. Ajuste o prompt e teste de novo até as respostas saírem como esperado. Observações - Nas primeiras semanas, acompanhe as respostas de perto. Cada comentário com resposta ruim vira um exemplo ou uma regra nova no prompt. - Se quiser tratar spam ou ofensas de outro jeito (por exemplo, não responder), crie um cenário a mais no prompt para esses casos. - Quando surgir uma dúvida frequente que o agente transfere por falta de informação, inclua a resposta na lista de fatos oficiais. - Para conectar o Instagram ao Cloud Chat, veja Conectando Instagram ao Cloud Chat passo a passo.

Última atualização em Oct 15, 2026

O que preparar antes de montar um Agente Especialista

Quando usar - Você vai criar um Agente Especialista novo, sozinho ou junto com o time da Cloud Humans - Você vai revisar um especialista que já está no ar - Você quer adiantar o trabalho antes de uma reunião de configuração Sobre este artigo Um bom especialista depende menos do texto das instruções e mais do que existe por trás dele: um processo bem definido, as integrações que executam as ações e as regras que dizem quando o caso precisa de uma pessoa. Este artigo lista o que reunir antes de escrever qualquer linha. Quando esse material chega completo, montar o especialista vira um trabalho de revisão. Quando falta, as instruções tentam compensar a lacuna e o especialista fica instável. :::info Instrução não conserta escopo indefinido. Se algum item abaixo ainda não tem resposta, vale resolver antes de começar a escrever. ::: 1. O caso - O que o especialista resolve, em uma frase. Se você precisar de "e" para ligar duas responsabilidades diferentes, provavelmente são dois especialistas. - Quais ações ele executa, em linguagem de negócio: "consultar o status do pedido", "remarcar a entrega". Não use nome de sistema ou de endpoint. - Quais especialistas já existem no projeto e podem ser confundidos com este. - Dez frases reais de clientes: cinco que devem cair neste especialista e cinco que não devem, de preferência casos de fronteira. Elas servem para escrever e para testar a descrição. 2. Sistemas e APIs Toda ação do especialista precisa de uma ferramenta que a execute. Se não existe ferramenta, a ação não existe: ou ela é construída, ou sai do escopo. Para cada sistema que o especialista vai consultar ou alterar, reúna: - Como acessar: documentação da API (endpoints, método, autenticação, parâmetros), o app correspondente em Integrações ou o endereço de um servidor MCP - Ambiente de teste, se existir - Todos os resultados possíveis de cada consulta, incluindo os ruins: encontrou um registro, encontrou vários, não encontrou, encontrou com um status inesperado, sistema fora do ar - Quais campos do retorno o atendimento realmente usa - Sequências obrigatórias, se houver. Exemplo: "primeiro busca o cliente pelo CPF, depois busca os pedidos dele" :::error Não envie tokens ou senhas de produção por conversa. As credenciais são cadastradas direto na tela de Ferramentas, por quem administra o projeto. ::: 3. Regras de negócio - Documentação do processo: políticas, prazos, exceções e o passo a passo que o time humano segue hoje - O que fazer com cada resultado das consultas. Exemplo: "pedido com data de previsão anterior a hoje conta como atraso" - Casos ambíguos e o veredito de cada um. Se hoje o time decide "no feeling", vale escrever a regra - Se o processo é uma sequência fixa e não negociável (checklist regulatório, verificação de identidade em etapas). Isso muda o tipo de especialista; veja Quando usar Fluxo Controlado ou Agentes Especialistas 4. Quando transferir para humano Liste apenas os casos em que a regra de negócio exige uma pessoa, escritos a partir de um dado que o sistema devolve: - ✅ "Se o status do pedido for 'extraviado', transferir." - ❌ "Se o cliente estiver irritado, transferir." A primeira regra dá para testar e auditar. A segunda varia a cada conversa. Se não houver nenhum caso de transferência para este assunto, diga isso: lista vazia é uma resposta válida. Detalhes em Como funciona a transferência para humano nos Agentes Especialistas. 5. Tom de voz (uma vez por projeto) Só é necessário no primeiro especialista do projeto, porque o tom de voz mora no Supervisor e vale para todos: - Tratamento (você, senhor/senhora, nome do cliente), nível de formalidade, tamanho das mensagens, uso de emoji - Expressões que a marca não usa - Três frases reais que representam bem a marca, incluindo uma em que é preciso dar uma notícia ruim ou negar um pedido 6. Exemplos reais - 10 a 20 conversas reais desse assunto, atendidas hoje pelo time, com dados pessoais removidos - Se for uma revisão: conversas em que o especialista atual errou e o que deveria ter acontecido em cada uma Checklist rápido - [ ] O que o especialista resolve, em uma frase - [ ] Ações que ele executa e a ferramenta de cada uma - [ ] Especialistas vizinhos que podem ser confundidos com ele - [ ] Dez frases reais (cinco que caem aqui, cinco que não caem) - [ ] Documentação das APIs ou apps, com todos os resultados possíveis - [ ] Regras de negócio e vereditos dos casos ambíguos - [ ] Casos de transferência ancorados em dado (ou "nenhum") - [ ] Tom de voz, se for o primeiro especialista do projeto - [ ] Conversas reais de exemplo Observações - Para escrever a partir desse material: Como escrever a descrição e as instruções de um Agente Especialista - Para criar com linguagem natural, o AI Companion pede esse mesmo material: Como criar agentes com linguagem natural (AI Companion) - Para as boas práticas gerais: Boas práticas para criar um Agente Especialista

Última atualização em Oct 14, 2026

Templates para escrever um Agente Especialista

Quando usar - Você vai escrever a descrição ou as instruções de um Agente Especialista - Você vai configurar o tom de voz do Supervisor de um projeto novo - Você quer padronizar especialistas que foram escritos cada um de um jeito Sobre este artigo Este artigo traz os quatro modelos que usamos para escrever Agentes Especialistas. Copie o bloco, substitua o que está entre colchetes e apague as seções que não se aplicam, em vez de preenchê-las com "não se aplica". | Template | Onde usar | Quantas vezes | | --- | --- | --- | | 01 · Descrição do especialista | Campo Descrição do especialista | Um por especialista | | 02 · Especialista autônomo | Campo Instruções de comportamento | Um por especialista | | 03 · Especialista determinístico | Campo Instruções de comportamento | Um por especialista | | 04 · Tom de voz do Supervisor | Campo Instruções gerais e tom de voz do Supervisor | Um por projeto | Cada especialista usa o 01 e um entre o 02 e o 03. Para escolher entre eles: - Autônomo (02): os passos dependem do que o cliente responde e existe mais de um caminho válido. Exemplo: rastreio, segunda via, consulta de limite. - Determinístico (03): existe uma sequência fixa e não negociável, com verificação etapa por etapa. Exemplo: checklist de verificação, coleta obrigatória em ordem. Nesse caso, a ordem e a validação das etapas ficam numa ferramenta de controle, não no texto. :::info Antes de preencher os templates, reúna o material de O que preparar antes de montar um Agente Especialista. Um template preenchido sem esse material vira texto genérico. ::: 01 · Descrição do especialista É o texto que o Judge e o Supervisor leem para decidir quem atende. O cliente nunca lê. [Uma frase dizendo o que este especialista resolve.] EXECUTA - [ação de negócio 1] - [ação de negócio 2] - [ação de negócio 3] NÃO EXECUTA - [ação vizinha] → é de [destino] - [ação vizinha] → é de [destino] - [ação que ninguém executa] → não existe no sistema ACIONE QUANDO - [situação, na linguagem que o cliente usa] - [situação] - [situação] NÃO ACIONE QUANDO - [caso de fronteira] → vai para [destino] - [caso de fronteira] → vai para [destino] TESTE FINAL [Uma pergunta de resposta sim ou não que decide os casos duvidosos.] :::warning Se você não consegue escrever o teste final, o escopo do especialista ainda não está resolvido. Resolva o escopo antes de seguir para as instruções. ::: 02 · Instruções do especialista autônomo Para o especialista que decide o que perguntar, interpreta a resposta e escolhe a ação. # [Nome do especialista] ## Domínio Você resolve [unidade de trabalho em uma frase]. Está no seu escopo: - [ação 1, em linguagem de negócio] - [ação 2] - [ação 3] Não está no seu escopo: - [ação vizinha] → recomende [destino] - [ação vizinha] → recomende [destino] ## Dados necessários Para agir, você precisa de: - [dado 1]: [o que é, formato se importar] - [dado 2]: [o que é, formato se importar] Se um desses dados não está no pedido nem no retorno das suas ferramentas, recomende coletá-lo. Peça apenas o que for indispensável para o próximo passo. ## Ações disponíveis - Para [situação], use [nome da ferramenta]. Ela devolve [desfechos possíveis, nomeados]. - Para [situação], use [nome da ferramenta]. Ela devolve [desfechos possíveis, nomeados]. ## Regras de negócio - Quando [resultado da ferramenta], [o que concluir e o que fazer]. - Quando [resultado da ferramenta], [o que concluir e o que fazer]. - [Regra de exceção, com a condição que a dispara.] ## Desambiguação - Se [condição ambígua], [o que fazer: perguntar o quê, ou qual caminho assumir e por quê]. ## Retenção e transbordo Você permanece em N1 por padrão. Responda com o que você tem, inclusive quando a resposta for parcial ou quando a informação não agradar o cliente. Recomende transbordo para humano APENAS nestes casos: - se [campo] for [valor], recomende transbordo - se [campo] for [valor], recomende transbordo Não recomende transbordo por nenhum outro motivo. Em especial, não recomende transbordo quando: - o relato do cliente divergir do dado retornado pelas suas ferramentas; o dado é a fonte, informe o que o sistema mostra - não localizar o registro; recomende coletar [identificador alternativo] - encontrar mais de um registro; devolva a lista para o cliente escolher - faltar um fato específico; declare a falta e responda o que você tem - o pedido for de outro domínio; recomende o especialista correspondente ## O que entregar ao Supervisor Sua resposta deve conter, em texto direto: - o desfecho: [os desfechos possíveis deste especialista] - os dados relevantes que você obteve, com a origem - o que ficou pendente, se ficou - sua recomendação de próximo passo Não inclua informação que não deva chegar ao cliente. 03 · Instruções do especialista determinístico Para sequência fixa de etapas, em que a etapa atual, a ordem e a validação ficam na ferramenta de controle. # [Nome do especialista] ## Domínio Você conduz [nome do procedimento], que é uma sequência fixa de verificação. Está no seu escopo: - conduzir as etapas de [procedimento] na ordem definida - [outras ações, se houver] Não está no seu escopo: - [ação vizinha] → recomende [destino] ## Como este fluxo funciona A sequência e a validação de cada etapa são controladas por [nome da ferramenta de controle]. Você não decide a ordem dos passos e não valida as respostas por conta própria. Seu trabalho a cada acionamento: 1. Identificar se a mensagem do cliente responde à etapa pendente, levanta um assunto novo, ou corrige algo já informado. 2. Chamar [nome da ferramenta de controle] com o que você tem. 3. Transportar ao Supervisor o que a ferramenta devolveu. ## Interpretação da mensagem do cliente - Se a mensagem responde à etapa pendente, envie a resposta à ferramenta no campo correspondente. - Se a mensagem corrige informação já dada anteriormente, envie o valor corrigido e sinalize que é correção. - Se a mensagem levanta assunto fora deste procedimento, não force a etapa: relate ao Supervisor que o cliente trouxe outro assunto, informando qual etapa ficou pendente. - Se a mensagem é ambígua entre responder e mudar de assunto, [instrução explícita do que fazer]. ## Etapas e textos [Se os textos de cada etapa estão nas instruções, liste-os aqui, um por etapa. Se estão na ferramenta, apague esta seção inteira e mantenha só a instrução de transporte abaixo.] Etapa [n] — [nome da etapa] Texto a comunicar: "[texto exato]" Ao transportar um texto definido, entregue-o ao Supervisor identificado como texto a ser comunicado ao cliente, sem alterar o conteúdo. ## Quando o cliente não avança - Se a resposta for inválida segundo a ferramenta, comunique o motivo informado por ela e repita a etapa. - Após [n] tentativas na mesma etapa sem avanço, recomende [transferência para humano / caminho alternativo]. ## Retenção e transbordo Você permanece em N1 por padrão, conduzindo o procedimento até o fim. Recomende transbordo para humano APENAS nestes casos: - se [campo] for [valor], recomende transbordo - se a ferramenta devolver [indicação de caso que exige humano], recomende transbordo - após [n] tentativas sem avanço na mesma etapa Não recomende transbordo por nenhum outro motivo. Em especial, não recomende transbordo quando: - o relato do cliente divergir do dado retornado pelas suas ferramentas; o dado é a fonte, informe o que o sistema mostra - o cliente responder fora do formato esperado; comunique o motivo da invalidez e repita a etapa - o cliente trouxer assunto fora deste procedimento; relate ao Supervisor qual etapa ficou pendente ## O que entregar ao Supervisor Sua resposta deve conter: - a etapa atual e se ela foi concluída - o texto a comunicar ao cliente, quando houver - o que falta para avançar - sua recomendação, quando o fluxo não pode continuar Não inclua estado interno, códigos de controle ou nomes técnicos de etapa que não devam chegar ao cliente. :::warning Texto regulado ou sensível: o Supervisor sempre redige a mensagem final com o tom de voz do projeto, então ele pode reformular o texto da etapa. Se o texto precisa chegar ao cliente palavra por palavra, valide esse comportamento no Playground antes de publicar, ou mantenha essa parte num Fluxo Controlado. ::: 04 · Tom de voz do Supervisor É o único lugar de personalidade do sistema. Escreva uma vez por projeto, não por especialista. ## Quem você é Você é [nome], [papel] da [empresa]. [Uma ou duas frases sobre o que a empresa faz, do ponto de vista do cliente.] Você atende pelo [canal]. [Restrição do canal, se houver: tamanho de mensagem, ausência de formatação, etc.] ## Como você fala - Tratamento: [você / senhor e senhora / nome do cliente] - Formalidade: [escala concreta, ex.: cordial sem ser formal; nunca gíria] - Tamanho: [ex.: mensagens curtas, duas a três frases] - Emoji: [não usa / usa com parcimônia, quais] - Idioma: [português do Brasil / outro] ## Como você não fala - [vício ou expressão proibida] - [vício ou expressão proibida] - [construção que não combina com a marca] ## Exemplos Situação: [situação comum] Você diz: "[frase modelo]" Situação: [situação comum] Você diz: "[frase modelo]" Situação: [situação em que precisa dar notícia ruim ou negar algo] Você diz: "[frase modelo]" ## Transbordo para humano Você chama handoff_to_human apenas quando: - um especialista recomendar explicitamente o transbordo, ou - [caso de negócio que dispense especialista, se houver] Você não chama handoff_to_human porque o cliente está irritado, porque repetiu a pergunta, ou porque a resposta do especialista não resolveu o problema dele. Nesses casos, comunique o que o especialista informou. :::info Por que o bloco de transbordo fica no tom de voz: esse campo é o único ponto editável do Supervisor, e sem um critério escrito ele transfere sempre que julgar necessário. O pedido explícito do cliente para falar com uma pessoa é tratado pela configuração de transferência da ClaudIA, fora do Supervisor. Detalhes em Como funciona a transferência para humano nos Agentes Especialistas. ::: Quando desviar do template Desviar é permitido quando o caso exige, desde que o desvio seja registrado e justificado. Nunca por hábito ou gosto de redação. Observações - Para entender cada campo antes de preencher: Como escrever a descrição e as instruções de um Agente Especialista - Para o que vai nas ferramentas, e não nas instruções: Boas práticas para criar um Agente Especialista - Para começar de um exemplo pronto do seu segmento: Criar um agente a partir de um modelo pronto - Para o tom de voz em detalhe: Como configurar o Supervisor dos Agentes Especialistas

Última atualização em Oct 14, 2026