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

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

Última atualização em Oct 14, 2026

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.

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

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.>

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.

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.

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