> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/configuracao-administrador/automacao/agentes-de-ia.md).
# Agentes de IA
Os **Agentes de IA** atendem seus clientes automaticamente antes da equipe humana. Cada agente responde com base no conteúdo que você cadastra (a sua base de conhecimento), segue o tom de voz que você definir, pode agir sozinho no funil e nas etiquetas do contato, consultar automações externas, servidores MCP e outros agentes, e transfere a conversa para o destino certo quando o assunto exige um atendente.
Este artigo mostra como criar um agente do zero ou a partir de um modelo pronto, cadastrar a base de conhecimento, configurar ações e ferramentas, definir o roteamento, conferir tudo no mapa do agente e acompanhar os atendimentos feitos por ele.
{% hint style="info" %}
**Pré-requisitos:**
* Acesso de **Administrador** na instalação do Z-PRO.
* Uma **chave de API** de um provedor de IA compatível com o padrão OpenAI (OpenAI, ou serviços como LiteLLM, LocalAI e Ollama). A conta e os créditos do provedor são de responsabilidade do assinante.
* Pelo menos uma **fila** já criada no painel para receber as transferências.
* Se for usar a aba **Ferramentas** para consultar sistemas externos: o **endereço (webhook)** da automação já publicado e pronto para receber requisições.
* Se for usar o bloco **Agenda**: uma página de agendamento já criada no Z-PRO.
* Se for usar **Servidores MCP**: o endereço do servidor MCP (n8n, Zapier, Make ou outro) e, se ele exigir, os dados de autenticação.
{% endhint %}
***
**Como funciona**
Depois de ativo e vinculado a um canal (ou a uma interação de Chat Flow), o agente:
* Recebe as mensagens do cliente e responde usando o **tom de voz e as instruções** definidos no perfil.
* Consulta a **base de conhecimento** (artigos e fontes importadas) para montar as respostas.
* Pode **etiquetar o contato**, **movê-lo no funil** ou **criar uma oportunidade no funil** sozinho, no meio da conversa, sem interromper o atendimento.
* Pode **acionar uma automação externa** (webhook) ou uma **ferramenta de um servidor MCP** quando o cliente pede algo que exige consulta, e usar a resposta recebida para responder ao cliente.
* Pode **consultar outro agente de IA** antes de responder (por exemplo, um agente especialista em preços). Quem responde ao cliente continua sendo o agente principal.
* Pode **consultar e reservar horário direto na Agenda** do Z-PRO e **agendar o envio de uma mensagem para depois**.
* Pode **registrar dados na ficha do contato** com as informações que o cliente informar durante a conversa, e **deixar uma anotação no próprio atendimento**.
* Pode **avisar a equipe** (fila e/ou atendentes específicos) e **parar de atender um contato sozinho** (ação **Parar a IA para este contato**) quando resolve a solicitação sem precisar de um humano — a conversa vai para a **Fila de emergência** e a IA para de responder aquele contato até alguém desbloquear o chatbot no cadastro dele.
* **Transfere para a equipe** quando identifica um assunto que precisa de humano, quando o cliente digita a **palavra de saída** ou quando você configurou um destino específico para aquele tema; o destino pode ser uma **fila**, um **atendente**, um **Chat Flow** que assume a conversa na hora ou **outro agente de IA**.
* Ao transferir para um atendente, pode **reservar o cliente com o mesmo destino por um tempo determinado**, para se ele voltar logo depois, a conversa ir direto pra lá sem passar pela IA de novo.
* Ao encerrar sozinho, escolhe um **motivo** entre os que você cadastrou (ou fecha sem motivo, se nenhum estiver configurado).
* Registra um **resumo da conversa** como nota interna no ticket ao transferir (se a opção estiver ligada).
{% hint style="warning" %}
**Atenção ao consumo:** cada resposta do agente consome créditos/tokens na conta do provedor de IA (OpenAI, etc.). O custo é cobrado diretamente pelo provedor — monitore o uso no painel dele.
{% endhint %}
{% hint style="info" %}
**Novidade:** a tela de Agentes de IA ganhou **Modelos prontos** (cria um agente pronto em poucos cliques), **Servidores MCP** (conecta ferramentas de n8n, Zapier, Make e outros) e o **Mapa do agente** (visão de tudo o que foi montado). Na aba **Ferramentas** entrou o bloco **Consultar outros agentes**, e no **Roteamento** os destinos agora também podem ser um **Atendente** ou **Outro agente de IA**.
{% endhint %}
***
### Etapa 1: Abrir a tela de Agentes de IA
1. No menu lateral, abra o grupo **Automação**.
2. Clique em **Agentes de IA**.
A tela lista os agentes já criados. Cada cartão mostra o nome, a descrição e o status (**Ativo** ou **Inativo**), além dos botões:
| Botão | O que faz |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| **Mapa** | Abre o mapa do agente, uma visão só de leitura de tudo o que foi montado (ver Etapa 9). |
| **Duplicar** (ícone de cópia) | Cria uma cópia do agente, útil para montar uma variação sem começar do zero. |
| **Editar** (lápis) | Abre o agente para alteração. |
| **Excluir** (lixeira) | Remove o agente. |
No canto superior direito ficam três botões:
* **Servidores MCP:** cadastra servidores MCP que os agentes podem usar (ver Etapa 7).
* **Modelos prontos:** cria um agente a partir de um modelo (ver a seguir).
* **Novo Agente:** cria um agente do zero.
Para criar do zero, clique em **Novo Agente**.
A janela **Novo Agente de IA** tem seis abas: **Perfil**, **Provedor**, **Conhecimento**, **Roteamento**, **Ações** e **Ferramentas**.
{% hint style="info" %}
As abas **Conhecimento**, **Roteamento**, **Ações** e **Ferramentas** ficam bloqueadas até você salvar o agente pela primeira vez. Preencha **Perfil** e **Provedor**, clique em **Salvar** e reabra o agente em **Editar** para completar o restante.
{% endhint %}
**Atalho: criar a partir de um modelo pronto**
Em vez de começar do zero, você pode partir de um modelo com instruções e perguntas de exemplo já montadas.
1. Clique em **Modelos prontos**.
2. Na aba **Um agente**, escolha o modelo e clique em **Continuar**:
| Modelo | Para quê |
| --------------- | ------------------------------------------------------------------------------------------- |
| **Recepção** | Dá as boas-vindas, entende o que o cliente precisa e encaminha para o setor certo. |
| **Vendas** | Apresenta produtos e serviços, tira dúvidas de compra e deixa o cliente pronto para fechar. |
| **Suporte** | Ajuda a resolver dúvidas e problemas com produtos ou serviços, passo a passo. |
| **Financeiro** | Esclarece dúvidas sobre boletos, pagamentos, faturas e segunda via. |
| **Agendamento** | Ajuda o cliente a marcar, remarcar ou cancelar horários. |
| **Pós-venda** | Acompanha pedidos, cuida de trocas e devoluções e ouve a opinião do cliente. |
3. Preencha:
| Campo | O que preencher |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome da empresa** *(obrigatório)* | Aparece nas instruções e nas perguntas de exemplo. Dá para mudar depois no editor. |
| **Conexão de IA** | **Mesma conexão de outro agente:** usa a mesma chave, endereço e modelo de um agente que você já tem (a chave não é exibida). **Informar a chave:** cadastra uma chave nova. |
| **Fila de emergência** *(obrigatório)* | Se a IA falhar (inclusive por chave inválida ou sem crédito), a conversa vai para esta fila em vez de ficar sem resposta, com uma nota no ticket explicando o motivo. |
4. Clique em **Criar**.
{% hint style="warning" %}
As **perguntas de exemplo** do modelo entram **desativadas**. Antes de colocar o agente para atender, abra a aba **Conhecimento**, complete as partes entre colchetes (ex.: `[horário de atendimento]`) e ative cada uma.
{% endhint %}
Depois de criado, o agente pode ser ajustado normalmente pelas Etapas 2 a 8.
***
### Etapa 2: Preencher o Perfil
Na aba **Perfil**, defina a identidade e o comportamento do agente:
| Campo | O que preencher |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Nome** *(obrigatório)* | Nome interno do agente (ex: "Pré-atendimento Comercial"). |
| **Ativo** | Liga ou desliga o agente. Deixe desligado enquanto configura. |
| **Descrição** | Texto curto para a equipe saber para que serve este agente. |
| **Tom de voz e instruções** | Descreva a personalidade, o que o agente pode e não pode dizer e como tratar o cliente. Ex: *"Você é o atendente virtual de um pet shop. Seja simpático, use linguagem simples e responda dúvidas sobre produtos e serviços."* |
| **Palavra de saída** | Palavra que, digitada **exatamente** pelo cliente, faz o agente parar e mandar a conversa para a equipe (ex: `atendente`). |
***
### Etapa 3: Configurar o Provedor de IA
Na aba **Provedor**, informe as credenciais do modelo de linguagem e ajuste o comportamento do modelo:
| Campo | O que preencher |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chave da IA** *(obrigatório)* | A chave de API do provedor (formato `sk-...`). Fica guardada com segurança no servidor. Ao editar um agente já salvo, o campo mostra "Chave atual mantida" — só preencha para trocar. |
| **URL Base da API (OpenAI)** | Deixe **em branco** para usar a OpenAI oficial. Para LiteLLM, LocalAI ou Ollama, informe a URL completa **incluindo `/v1`**. |
| **Modelo** | Identificação técnica do modelo que responderá (ex: `gpt-4o-mini`). |
| **Mensagens lembradas** | Quantas mensagens anteriores da conversa o agente considera em cada resposta. Padrão: `20`. |
| **Criatividade** | Controla a variação das respostas. `0` deixa as respostas mais previsíveis; valores maiores tornam as respostas mais variadas. |
{% hint style="info" %}
Para gerar a chave da OpenAI, acesse `platform.openai.com`, vá em *API Keys* e crie uma nova. Use o nome de modelo exatamente como o provedor documenta.
{% endhint %}
Clique em **Salvar**. O agente aparece na lista como **Inativo**.
***
### Etapa 4: Montar a base de conhecimento
Reabra o agente em **Editar** e vá até a aba **Conhecimento**.
1. Ative **Usar base de conhecimento**. Com ela ligada, o agente responde usando os artigos e fontes abaixo como fonte principal.
2. *(Opcional)* Ative **Busca inteligente** para o agente entender sinônimos e o sentido da pergunta, não só as palavras exatas. Essa busca usa a mesma chave de IA do agente.
**Adicionar artigos**
1. Clique em **Adicionar artigo**.
2. Preencha o **Título** e o **Conteúdo** *(obrigatório)* — escreva a informação como você explicaria ao cliente.
3. Deixe o artigo **Ativo** e clique em **Salvar**.
4. Repita para cada dúvida frequente ou informação do negócio.
**Importar fontes prontas**
No bloco **Fontes importadas** você aproveita conteúdo que já existe:
* **Adicionar documento** — PDF, DOCX, XLSX, CSV ou TXT, até **10 MB**. O texto do arquivo é lido e indexado; documentos digitalizados (imagem, sem texto) **não** são aceitos.
* **Adicionar link** — uma página do seu site.
* **Importar FAQ (CSV)** — uma planilha de perguntas e respostas.
Clique em **Salvar**.
***
### **Etapa 5: Definir o Roteamento**
Na aba **Roteamento**, você diz para onde a IA encaminha cada assunto.
1. Ative **Transferência inteligente** para a IA identificar o assunto da conversa e transferir para o destino certo no momento adequado.
2. Clique em **Adicionar destino** e preencha, para cada destino:
| Campo | O que preencher |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rótulo** *(obrigatório)* | Nome do destino (ex: "Financeiro"). |
| **Tipo** | **Fila**, **Atendente**, **Fluxo** ou **Outro agente de IA**. |
| **Fila de destino** *(obrigatório se Tipo = Fila)* | A fila que receberá a conversa. |
| **Atendente** *(obrigatório se Tipo = Atendente)* | O atendente que receberá a conversa. |
| **Fluxo** *(obrigatório se Tipo = Fluxo)* | O Chat Flow que assume a conversa, começando na hora. Nesse tipo de destino a IA **não envia mensagem de despedida**. |
| **Agente de IA** *(obrigatório se Tipo = Outro agente de IA)* | O agente que assume a conversa a partir daí. A opção só fica disponível quando existe pelo menos outro agente criado. |
| **Quando transferir** *(obrigatório)* | Explique em que situação a conversa vai para cá. A IA lê essa descrição para decidir. Ex: *"pagamentos, boletos, notas fiscais e cobranças"*. |
| **Mensagem ao transferir** *(opcional)* | Mensagem enviada ao cliente só depois que a transferência para este destino acontece de verdade, nos casos em que o agente não escreve mais nada. |
3. Adicione quantos destinos precisar.
4. Mantenha **Resumo automático na transferência** ligado para o agente registrar um resumo da conversa como **nota interna** para a equipe.
5. Em **Mensagem padrão ao transferir**, escreva a mensagem usada para os destinos que não têm mensagem própria (ex.: *"Vou te passar para a nossa equipe. Só um instante!"*). Evita que o cliente fique sem resposta na hora da transferência.
6. Em **Fila de emergência**, escolha a fila que recebe a conversa **se a IA falhar**, inclusive por chave inválida ou sem crédito no provedor. Em vez de o cliente ficar sem resposta, a conversa vai para essa fila com uma **nota no ticket explicando o motivo** da falha.
**Ao encerrar**
Defina os motivos que o agente pode escolher ao usar a ação **Parar a IA para este contato** (aba **Ações** — ver Etapa 6), que envia a conversa para a **Fila de emergência** e bloqueia a IA para aquele contato.
Em **Motivos que a IA pode escolher**, aparecem as **demandas** já cadastradas no painel (ex.: "Venda fechada", "Sem resposta", "Avaliação agendada"). Marque a caixa de cada motivo que a IA pode usar.
{% hint style="info" %}
Os motivos não são criados aqui. Para incluir um motivo novo, cadastre-o primeiro como demanda. Veja Demanda.
{% endhint %}
{% hint style="info" %}
Ao encerrar o atendimento, a IA escolhe um destes motivos. Sem nenhum selecionado, o atendimento fecha **sem motivo**.
{% endhint %}
**Depois de transferir para um atendente**
Configure se, quando o cliente voltar logo depois de ser atendido, a conversa deve ir direto para o mesmo lugar — sem passar pela IA de novo.
1. Ative **Reservar o cliente por um tempo**.
2. Em **Prazo**, defina o número e a unidade (ex: `1` **Horas**).
3. Em **Para onde vai**, escolha o destino: **Último atendente**, **Quem encerrou**, **Uma fila**, **Um atendente** ou **Um fluxo**.
{% hint style="info" %}
Se o atendente encerrar e o cliente voltar dentro do prazo definido, a conversa vai direto para o destino escolhido, sem passar pela IA.
{% endhint %}
Clique em **Salvar**.
***
### **Etapa 6: Configurar Ações**
Na aba **Ações**, você define o que o agente pode fazer durante a conversa além de responder: mexer no funil e nas etiquetas do contato, criar oportunidade, deixar anotações, avisar a equipe e parar de atender um contato sozinho.
O agente executa estas ações sozinho durante a conversa, quando a situação descrita em **Quando usar** acontecer.
{% hint style="info" %}
**Novidade (v4.0.5.6, 23/09/2026):** a aba **Ações** é nova — antes essas configurações não existiam. O menu **O que fazer** ganhou opções, além de mover no funil e aplicar etiqueta. Devolver a conversa a um Chat Flow e reservar o cliente com o mesmo atendente **não ficam aqui** — são configurados na aba **Roteamento** (ver Etapa 5). Consultar/reservar na Agenda e agendar mensagem também não são "ações" — são blocos da aba **Ferramentas** (ver Etapa 7).
{% endhint %}
1. Clique em **Adicionar ação**.
2. Em **O que fazer**, escolha o tipo de ação. As opções aparecem agrupadas em dois grupos:
* **Qualificação:** Aplicar etiqueta ao contato · Mover o contato no funil · Criar oportunidade
* **Equipe:** Anotar no atendimento · Avisar a equipe · Parar a IA para este contato
3. Preencha os campos, que mudam de acordo com o que foi escolhido em **O que fazer**:
**Aplicar etiqueta ao contato**
| Campo | O que preencher |
| --------------------------- | ---------------------------------------- |
| **Destino** *(obrigatório)* | A etiqueta que será aplicada ao contato. |
**Mover o contato no funil**
| Campo | O que preencher |
| --------------------------- | ------------------------------------------------- |
| **Destino** *(obrigatório)* | A etapa do funil para onde o contato será movido. |
**Criar oportunidade**
| Campo | O que preencher |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Funil** *(obrigatório)* | O funil onde a oportunidade será criada. |
| **Etapa** *(obrigatório)* | A etapa inicial da oportunidade dentro do funil escolhido. |
| **Responsável** *(obrigatório)* | O usuário dono da oportunidade. |
| **Nome da oportunidade** *(opcional)* | Se não preencher, usa o nome do contato. A IA completa este texto com o que o cliente disse. |
| **Valor** *(opcional)* | Valor estimado da oportunidade. |
{% hint style="warning" %}
Se o contato já tiver uma oportunidade aberta **nesse mesmo funil**, o agente não cria outra.
{% endhint %}
**Anotar no atendimento**
| Campo | O que preencher |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome da ação** *(obrigatório)* | Identifica esta anotação na lista (ex: "Cliente sem estoque"). |
| **Texto da anotação** | A IA completa este texto com o que o cliente disse. Aparece na aba **Notas** do atendimento — no máximo **3 anotações por atendimento**. |
**Avisar a equipe**
| Campo | O que preencher |
| ------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Nome da ação** *(obrigatório)* | Identifica este aviso na lista (ex: "Cliente sem estoque"). |
| **Fila** *(opcional)* | Fila que recebe o aviso. Deixe em "Nenhuma" se for avisar só atendentes específicos. |
| **Atendentes** *(opcional)* | Marque um ou mais atendentes que devem receber o aviso. |
| **Mensagem do aviso** *(obrigatório)* | Texto do aviso — a IA completa com o que o cliente disse. Toca **uma vez por atendimento**. |
{% hint style="warning" %}
Escolha uma **fila** ou pelo menos um **atendente** — sem um dos dois, o Z-PRO não deixa salvar a ação.
{% endhint %}
**Parar a IA para este contato**
| Campo | O que preencher |
| -------------------------------- | ---------------------------------------------------------- |
| **Nome da ação** *(obrigatório)* | Identifica esta ação na lista (ex: "Cliente sem estoque"). |
{% hint style="warning" %}
A IA passa a conversa para a **Fila de emergência** (definida na aba Roteamento) e **para de atender esse contato** — para reverter, é preciso desbloquear o chatbot no cadastro do contato.
{% endhint %}
**Campos comuns a todas as ações**
| Campo | O que preencher |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quando usar** *(obrigatório)* | Descreva a situação da conversa em que esta ação deve acontecer — é por essa frase que o agente reconhece a hora certa. Ex: *"Quando o cliente disser que quer comprar ou pedir um orçamento"*. |
| **Mensagem ao cliente** *(opcional)* | Enviada só quando o agente executa a ação sem escrever nada junto, para o cliente não ficar sem resposta. Ex: *"Perfeito, já anotei isso por aqui."* |
4. Adicione quantas ações precisar.
5. Em **Mensagem padrão das ações**, escreva uma mensagem de reserva para qualquer ação que não tenha mensagem própria — sem ela, a ação pode acontecer em silêncio.
Clique em **Salvar**.
***
### **Etapa 7: Configurar Dados e Ferramentas**
Na aba **Ferramentas**, você define o que mais o agente pode consultar e registrar: a Agenda nativa, mensagens agendadas, outros agentes, servidores MCP, automações externas e dados na ficha do contato.
**Agenda**
O agente consulta horários livres e reserva direto na Agenda do Z-PRO, sem precisar de ferramenta externa.
1. Ative **Deixar a IA consultar horários e reservar**.
2. Em **Página de agendamento** *(obrigatório)*, escolha a página de agendamento que o agente vai consultar.
3. Em **Serviços que a IA pode oferecer** *(obrigatório)*, escolha quais serviços dessa página o agente pode oferecer ao cliente.
{% hint style="info" %}
Em página com profissionais, vale o primeiro disponível na ordem da página. A Agenda só aparece em canais com telefone e fora de grupos. A confirmação, com o link para cancelar ou remarcar, é enviada pela própria página de agendamento.
{% endhint %}
**Mensagem agendada**
O agente programa o envio de uma mensagem futura quando o cliente pedir.
1. Ative **Deixar a IA agendar uma mensagem para depois**.
2. Em **Antecedência máxima (dias)**, defina o prazo mais distante que o agente pode agendar (ex: `7`).
{% hint style="info" %}
A IA só agenda quando o cliente pedir, e sempre dentro desse prazo. Nos canais oficiais, só dentro de 24 horas. A mensagem é agendada mesmo que o cliente responda antes. Se o atendimento já estiver encerrado, a resposta do cliente abre um atendimento novo.
{% endhint %}
**Consultar outros agentes**
Antes de responder, o agente pode fazer uma pergunta a outro agente de IA, por exemplo, um agente treinado só com a tabela de preços. Quem responde ao cliente continua sendo este agente.
1. Clique em **Adicionar agente**.
2. Em **Agente consultado** *(obrigatório)*, escolha o agente.
3. Em **Quando consultar**, explique em que situação consultar esse agente (ex.: *"dúvidas sobre preços, prazos de entrega ou formas de pagamento"*). A IA lê essa descrição para decidir.
{% hint style="info" %}
Cada consulta é uma chamada de IA a mais, feita com a **chave do agente consultado**. Ele responde só com as próprias instruções e base de conhecimento, **sem executar ações**. São no máximo **2 consultas por mensagem**.
{% endhint %}
**Servidores MCP**
Conecte o agente a ferramentas de um servidor MCP (n8n, Zapier, Make e outros). Primeiro o servidor é cadastrado na conta; depois você escolhe em cada agente quais servidores ele usa.
*Cadastrar o servidor:*
1. Na aba **Ferramentas**, clique em **Gerenciar servidores** (ou, na tela de Agentes de IA, em **Servidores MCP**).
2. Clique em **Adicionar servidor** e preencha:
| Campo | O que preencher |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Nome** *(obrigatório)* | Nome para identificar o servidor (ex.: "Loja", "n8n"). |
| **Autenticação** | Como o Z-PRO se identifica no servidor. Deixe em **Sem autenticação** se o servidor não exigir. |
| **Endereço do servidor** *(obrigatório)* | A URL do servidor MCP, começando com `https://`. |
| **Tempo máximo de espera (segundos)** | Quanto tempo o agente espera a resposta do servidor. Padrão: `15`. |
| **Ativo** | Liga ou desliga o servidor. |
3. Clique em **Testar** para conferir a conexão e depois em **Salvar**.
4. Com o servidor salvo, confira a lista em **Ferramentas do servidor** e **aprove** as ferramentas que os agentes podem usar.
*Usar no agente:*
1. Na aba **Ferramentas** do agente, em **Servidores MCP**, clique em **Adicionar servidor**.
2. Escolha o servidor cadastrado e salve.
{% hint style="info" %}
Alterações nos servidores MCP podem levar **até 1 minuto** para valer em todos os atendimentos.
{% endhint %}
**Ferramentas (automações externas)**
Conecte o agente a uma automação externa (webhook): quando o cliente pedir algo que exige consulta, o agente aciona a automação e responde com o resultado. A cada consulta o Z-PRO envia os dados do atendimento (contato, protocolo e o que o agente precisa saber) e usa a resposta recebida na mensagem ao cliente.
1. Clique em **Adicionar ferramenta**.
2. Preencha:
| Campo | O que preencher |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** *(obrigatório)* | Nome da ferramenta (ex: "Consultar pedido"). |
| **Senha de acesso** *(opcional)* | Enviada junto da consulta para sua automação, caso ela valide um segredo. |
| **Endereço da automação** *(obrigatório)* | URL (webhook) que recebe a consulta e devolve a resposta. Por segurança, endereços de rede interna só funcionam se liberados em **Configurações**. |
| **Quando usar** *(obrigatório)* | Explique quando acionar esta ferramenta — a IA lê essa descrição para decidir. Ex: *"quando o cliente perguntar o status de um pedido pelo número"*. |
3. Em **Informações que o agente envia**, clique em **Adicionar** para cada dado que a automação precisa receber (ex: `numero_pedido` — número do pedido informado pelo cliente) e marque **Obrigatório** quando o dado não puder faltar. Deixe a lista vazia para o agente mandar a pergunta do cliente em texto livre.
4. Adicione quantas ferramentas precisar.
**Dados a registrar**
O agente anota na ficha do contato o que o cliente informar durante a conversa, e quem assumir o atendimento depois já encontra tudo preenchido.
1. Ative **Registrar dados na ficha do contato**.
2. Clique em **Adicionar dado** e preencha a chave (ex: `email`) e a descrição do que deve ser capturado (ex: "E-mail do cliente para envio da proposta").
3. Repita para cada informação que o agente deve coletar.
{% hint style="warning" %}
**Atenção:** se alguém estiver com a ficha do contato aberta e salvar depois, o que o agente anotou nesse meio-tempo pode ser substituído.
{% endhint %}
Clique em **Salvar**.
***
### Etapa 8: Ativar e colocar o agente para atender
1. Abra o agente em **Editar**, vá à aba **Perfil** e ligue a chave **Ativo**. Salve.
2. Coloque o agente na linha de frente de uma das duas formas:
* **Em um canal:** acesse **Conexões**, edite o canal desejado e abra a seção **Agente de IA**. No campo **Agente vinculado ao canal**, escolha o agente e clique em **Salvar alterações**. Com um agente vinculado, toda conversa nova daquele canal é atendida primeiro por ele.
* **Em um fluxo:** no **Chat Flow** (menu **Automação > Chat Flow**), edite o passo em que o pré-atendimento deve começar, clique em **Adicionar interação** e escolha **Agente de IA**. No campo **Agente de IA** da interação, selecione o agente — ele assume a conversa a partir daquele ponto.
***
### **Etapa 9: Conferir o agente no Mapa**
Na tela de Agentes de IA, clique em **Mapa** no cartão do agente. O mapa é uma **visão só de leitura** de tudo o que foi montado, ligado ao agente no centro:
* **Centro:** status, modelo, início das instruções, quantas mensagens o agente lembra e se o resumo automático na transferência está ligado.
* **Canais** em que o agente atende.
* **Conhecimento:** artigos e fontes, com a quantidade de trechos de cada um, e se a busca inteligente está ligada.
* **Ferramentas**, **Ações** e **Dados a registrar**.
* **Transferência inteligente:** os destinos do roteamento e o tipo de cada um.
* **Palavra de saída.**
Blocos tracejados indicam o que não está configurado (ex.: "Nenhuma ferramenta configurada"). Para alterar algo, clique em **Editar**.
Use o mapa para revisar o agente antes de ativá-lo ou para entender rapidamente como um agente existente funciona.
***
### Etapa 10: Acompanhar os atendimentos feitos pela IA
Enquanto o agente conversa com o cliente, o ticket fica na aba **Pendentes** de **Atendimentos**, com um ícone indicando que quem está respondendo é o Agente de IA.
* A equipe pode **abrir o ticket e assumir a conversa** a qualquer momento, respondendo normalmente no lugar da IA.
* Ou pode **deixar em Pendentes**, e o agente continua atendendo sozinho.
Quando o agente transfere a conversa (pela **palavra de saída**, por identificar que o assunto exige humano, ou por um destino configurado no **Roteamento**), e o **Resumo automático na transferência** está ligado, ele registra uma **nota interna** no ticket com este formato:
* **Motivo (IA):** por que a conversa foi transferida (ex: "Cliente deseja falar com um atendente humano").
* Um resumo em texto corrido dos principais assuntos tratados na conversa.
* **Fontes usadas:** os artigos ou fontes da base de conhecimento que embasaram as respostas.
Isso permite que quem assumir o atendimento entenda o histórico sem precisar reler toda a conversa.
***
### **Resumo das Funcionalidades**
| Funcionalidade | Onde acessar |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Criar / editar / duplicar / excluir agente | Menu **Automação > Agentes de IA** |
| Criar agente ou equipe a partir de modelo | **Agentes de IA > Modelos prontos** |
| Ver tudo o que o agente tem configurado | **Agentes de IA >** botão **Mapa** no cartão do agente |
| Nome, tom de voz, palavra de saída | Aba **Perfil** do agente |
| Chave da IA, URL base, modelo, mensagens lembradas, criatividade | Aba **Provedor** do agente |
| Artigos e fontes importadas (PDF, DOCX, XLSX, CSV, TXT, link, FAQ) | Aba **Conhecimento** do agente |
| Destinos de transferência (fila, atendente, Chat Flow ou outro agente), mensagem ao transferir, resumo automático, fila de emergência | Aba **Roteamento** do agente |
| Motivos que a IA escolhe ao encerrar sozinha | Aba **Roteamento > Ao encerrar** do agente |
| Reservar o cliente pelo mesmo destino por um tempo, após transferir para um atendente | Aba **Roteamento > Depois de transferir para um atendente** |
| Aplicar etiqueta, mover no funil, criar oportunidade, anotar no atendimento, avisar a equipe, parar a IA para o contato | Aba **Ações** do agente |
| Registrar dados coletados na ficha do contato | Aba **Ferramentas > Dados a registrar** do agente |
| Consultar e reservar horário na Agenda | Aba **Ferramentas > Agenda** do agente |
| Agendar o envio de uma mensagem futura | Aba **Ferramentas > Mensagem agendada** do agente |
| Consultar outro agente antes de responder | Aba **Ferramentas > Consultar outros agentes** do agente |
| Cadastrar servidores MCP e aprovar ferramentas | **Agentes de IA > Servidores MCP** ou **Ferramentas > Gerenciar servidores** |
| Usar um servidor MCP no agente | Aba **Ferramentas > Servidores MCP** do agente |
| Conectar o agente a uma automação externa (webhook) | Aba **Ferramentas > Ferramentas** do agente |
| Vincular agente a um canal | **Conexões >** editar canal **>** seção **Agente de IA** |
| Usar agente dentro de um fluxo | **Automação > Chat Flow >** editar passo **> Adicionar interação > Agente de IA** |
| Acompanhar, assumir ou deixar a IA seguir um atendimento | **Atendimentos > Pendentes** |
***
### **Encerramento**
Com o agente ativo, o pré-atendimento roda sozinho: o cliente é respondido na hora, com o tom da sua empresa e com base no seu conteúdo, pode ter o funil e a ficha atualizados automaticamente, e só chega à equipe quando realmente precisa — já com um resumo da conversa na nota interna. Revise os artigos da base periodicamente para manter as respostas corretas.
***
### **Perguntas frequentes**
**Quem paga pelos tokens consumidos pelo agente?** Você usa a sua própria chave de API do provedor de IA — cada empresa da sua base pode inclusive ter a chave dela. O consumo é cobrado diretamente pelo provedor, na conta associada à chave usada; não há taxa adicional do Z-PRO sobre esses tokens.
**Dá para usar um provedor de IA local (on-premise)?** Sim. Informe a URL da sua LLM local no campo **URL Base da API (OpenAI)** e a chave correspondente, desde que a rota siga o padrão de API da OpenAI — o padrão adotado por LiteLLM, LocalAI, Ollama e a maioria das LLMs abertas.
**Dá para fazer vários agentes de IA trabalharem juntos (multiagentes)?** Sim, de duas formas: (1) em **Ferramentas > Consultar outros agentes**, o agente principal pergunta a outro agente antes de responder, mas continua sendo ele quem fala com o cliente; (2) no **Roteamento**, um destino do tipo **Outro agente de IA** passa a conversa para outro agente. Para orquestrar agentes externos, use **Servidores MCP** ou as **Ferramentas** (webhook).
**A base de conhecimento alimentada por link se atualiza sozinha?** Sim. Ao adicionar um link, o agente relê a página periodicamente para atualizar o conteúdo — se a informação da página mudar, a resposta do agente acompanha, sem precisar recadastrar o link.
**Consigo importar a base de conhecimento em JSON?** Ainda não — hoje os formatos aceitos são PDF, DOCX, XLSX, CSV e TXT, além de link e FAQ em CSV. Novos formatos podem ser sugeridos e votados no roadmap público da ZDG (`roadmap.zdg.com.br`).
**Em quais canais o Agente de IA pode atender?** WhatsApp (API oficial e não oficial), Instagram, Messenger, Telegram e Web Chat — os mesmos canais conversacionais do Z-PRO.
**O agente pode "alucinar" e inventar uma resposta?** Ele responde apenas com base na base de conhecimento que você cadastrou. Quando a pergunta foge do que está cadastrado, o comportamento esperado é transferir para um atendente ou fila (conforme configurado no **Roteamento**), em vez de inventar uma resposta.
**Dá para combinar o Agente de IA com um Chat Flow tradicional (menu de opções)?** Sim, nos dois sentidos. Você pode manter um Chat Flow de boas-vindas/triagem e, em um dos passos, usar a interação **Agente de IA** (ver Etapa 8) para transferir a conversa para o agente. E o agente também pode devolver a conversa para um Chat Flow: na aba **Roteamento**, crie um destino com **Tipo: Fluxo** (ver Etapa 5).
***
**Possíveis Erros e Soluções**
**O agente não responde em nenhuma conversa**
**Causa:** agente inativo ou não vinculado a um canal/fluxo. **Solução:** ligue a chave **Ativo** na aba **Perfil** e confirme o vínculo em **Conexões** (no canal) ou a interação **Agente de IA** no Chat Flow.
**As respostas ignoram os artigos cadastrados**
**Causa:** a opção **Usar base de conhecimento** está desligada, ou os artigos estão inativos. **Solução:** na aba **Conhecimento**, ative **Usar base de conhecimento** e deixe cada artigo como **Ativo**.
**Erro de autenticação / chave inválida ao testar**
**Causa:** chave da IA incorreta, sem créditos, ou **URL Base** preenchida de forma errada. **Solução:** gere uma nova chave no provedor e cole no campo **Chave da IA**. Se usa OpenAI oficial, deixe a **URL Base** em branco; se usa LiteLLM/LocalAI/Ollama, informe a URL completa **com `/v1`** no final.
**O documento importado não traz conteúdo para as respostas**
**Causa:** arquivo acima de 10 MB ou digitalizado (imagem sem texto). **Solução:** reduza o arquivo para até 10 MB e use um PDF/DOCX com texto selecionável. Documentos escaneados não são indexados.
**A IA transfere para a fila errada (ou não transfere)**
**Causa:** descrição de **Quando transferir** genérica ou ausente. **Solução:** na aba **Roteamento**, detalhe cada destino com exemplos claros de assunto. Configure também a **Fila de emergência** para não deixar a conversa sem destino em caso de falha.
**A ação de mover no funil / aplicar etiqueta não acontece**
**Causa:** descrição de **Quando usar** vaga, ou o **Destino** (etapa do funil/etiqueta) não foi selecionado. **Solução:** na aba **Ações**, detalhe a situação com exemplos concretos do que o cliente diria e confirme o **Destino** escolhido.
**A ferramenta (webhook) não é acionada**
**Causa:** descrição de **Quando usar** genérica, ou o **Endereço da automação** é um endereço de rede interna sem liberação. **Solução:** detalhe melhor a situação de uso e, se o endereço for interno, libere-o em **Configurações**.
**Um dado que a IA registrou sumiu da ficha do contato**
**Causa:** alguém abriu a ficha do contato antes e salvou depois, sobrescrevendo o que o agente havia anotado nesse meio-tempo. **Solução:** reabra a ficha, confira e reinsira o dado se necessário; evite editar a ficha manualmente enquanto a IA está atendendo o mesmo contato.
**A ação Criar oportunidade não cria uma nova oportunidade**
**Causa:** comportamento esperado — o contato já tem uma oportunidade aberta nesse mesmo funil, e o agente não cria uma segunda. **Solução:** se precisar de uma oportunidade separada, use um funil diferente ou finalize/mova a oportunidade existente antes.
**A anotação do agente não aparece na aba Notas do atendimento**
**Causa:** o atendimento já tem 3 anotações da ação **Anotar no atendimento** — esse é o limite por atendimento. **Solução:** revise as anotações existentes na aba **Notas**; remova alguma se precisar liberar espaço para uma nova.
**O atendimento encerrado pela IA não mostra nenhum motivo**
**Causa:** comportamento esperado — nenhum motivo está marcado em **Roteamento > Ao encerrar**. **Solução:** marque a caixa de cada motivo que a IA pode escolher. Se o motivo não aparecer na lista, cadastre-o antes como demanda, em Demanda.
**O destino do tipo Fluxo não aparece para escolher**
**Causa:** o campo **Fluxo** só é exibido depois de selecionar **Tipo: Fluxo** no destino — com **Tipo: Fila**, aparece o campo **Fila de destino** no lugar. **Solução:** confira o campo **Tipo** do destino antes de procurar o campo de fluxo/fila.
**A ação Avisar a equipe não salva**
**Causa:** nem **Fila** nem nenhum **Atendente** foi selecionado — pelo menos um dos dois é obrigatório. **Solução:** escolha uma fila em **Fila** ou marque pelo menos um nome em **Atendentes**.
**O agente continua respondendo um contato que deveria estar bloqueado**
**Causa:** ou a condição de **Quando usar** da ação **Parar a IA para este contato** não bateu com a conversa, ou alguém já desbloqueou o chatbot no cadastro desse contato. **Solução:** detalhe melhor o **Quando usar** da ação e confira o bloqueio no cadastro do contato.
**A ferramenta do servidor MCP não é usada pelo agente**
**Causa:** o servidor está inativo, a ferramenta não foi aprovada em **Ferramentas do servidor**, o servidor não foi adicionado na aba **Ferramentas** do agente, ou a alteração ainda não propagou. **Solução:** confira os três pontos e aguarde até 1 minuto depois de salvar.
**O teste do servidor MCP falha**
**Causa:** endereço incorreto, servidor fora do ar, autenticação errada ou resposta mais lenta que o **Tempo máximo de espera**. **Solução:** confira o **Endereço do servidor** e a **Autenticação**; se o servidor for lento, aumente o tempo de espera.
**O agente criado por modelo pronto não usa as perguntas de exemplo**
**Causa:** comportamento esperado. As perguntas de exemplo entram desativadas. **Solução:** na aba **Conhecimento**, complete as partes entre colchetes e ative cada pergunta.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://ajuda.zdg.com.br/configuracao-administrador/automacao/agentes-de-ia.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
