> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maketalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar um Agente

> Configure as informações, personalidade e comportamento do seu agente de IA

## O que é um Agente?

Um **Agente** é uma instância de IA configurada para um propósito específico. Cada agente pode ter:

* Personalidade e tom de voz próprios
* Fluxo de atendimento específico
* Base de conhecimento dedicada
* Regras de comportamento customizadas

<Tip>
  Você pode ter múltiplos agentes para diferentes finalidades: um para vendas, outro para suporte, outro para agendamentos, etc.
</Tip>

***

## Criando um novo agente

<Steps>
  <Step title="Clique em 'Novo Agente'">
    Na barra lateral esquerda do Flow Builder, clique no botão **Novo Agente**.
  </Step>

  <Step title="Escolha como começar">
    Uma tela será exibida com as opções de criação:

    <CardGroup cols={2}>
      <Card title="Em Branco" icon="file">
        Comece do zero com os 3 blocos essenciais: Início, Prompt Base e Configuração do Agente.
      </Card>

      <Card title="Template" icon="copy">
        Use um modelo pré-configurado para seu segmento (Hotel, E-commerce, Suporte) com blocos adicionais já conectados.
      </Card>
    </CardGroup>
  </Step>

  <Step title="O Flow Builder abre com os blocos iniciais">
    Após escolher, o editor visual abre com os blocos do seu agente já conectados e prontos para configuração.

    Se escolheu **Em Branco**, você verá:

    ```
    [Início] → [Prompt Base] → [Configuração do Agente]
    ```

    Se escolheu um **template**, blocos adicionais como Roteador, Cotação e Transferência já estarão presentes.
  </Step>
</Steps>

### Exportando um agente

Você pode exportar qualquer agente como arquivo JSON para backup ou para replicar em outra conta.

<Steps>
  <Step title="Acesse o Dashboard do Flow Builder">
    Na lista de agentes, localize o agente que deseja exportar.
  </Step>

  <Step title="Abra o menu de opções">
    Clique no menu de opções (tres pontos) do agente.
  </Step>

  <Step title="Clique em Exportar">
    Selecione **Exportar**. Um arquivo `.json` será baixado automaticamente para o seu computador.
  </Step>
</Steps>

#### O que é exportado e o que não é

| Incluído na exportação        | Removido por segurança              |
| ----------------------------- | ----------------------------------- |
| Blocos e conexões do fluxo    | Credenciais de API (tokens, chaves) |
| Configurações do prompt       | Bases de conhecimento vinculadas    |
| Regras, restrições e exemplos | IDs de equipes e agentes humanos    |
| Configurações do roteador     | Dados específicos da conta          |

<Warning>
  Credenciais e bases de conhecimento são removidas propositalmente do arquivo exportado. Isso protege informações sensíveis caso o arquivo seja compartilhado.
</Warning>

### Importando um agente existente

Além de criar do zero, você pode **importar um agente** de um arquivo JSON:

<Steps>
  <Step title="Clique em Importar">
    Na tela inicial do Flow Builder, clique no botão **Importar**.
  </Step>

  <Step title="Selecione o arquivo">
    Escolha o arquivo `.json` exportado anteriormente. O limite de tamanho é **5MB** por arquivo.
  </Step>

  <Step title="Revise os avisos pós-importação">
    Após o upload, um modal exibe a lista de itens que precisam de reconfiguração — como bases de conhecimento, equipes de atendimento e credenciais de API. Anote esses itens para ajustar depois.
  </Step>

  <Step title="Finalize a importação">
    O agente será criado como **rascunho**. Abra o editor, reconfigure os itens listados nos avisos e só publique quando tudo estiver pronto.
  </Step>
</Steps>

<Tip>
  **Caso de uso: redes multi-unidade.** Se você gerencia uma rede de hotéis, franquias ou lojas, pode criar um agente base bem configurado, exportá-lo e importar em cada conta. Depois, basta ajustar os detalhes específicos de cada unidade (nome, equipe, base de conhecimento). Isso economiza horas de configuração repetitiva.
</Tip>

***

## Os 3 blocos essenciais

Todo agente possui 3 blocos que formam sua base. Clique em cada bloco no editor para configurá-lo no painel lateral direito.

### 1. Bloco Início

<Frame caption="Bloco Início com variáveis de contexto">
  <img src="https://mintcdn.com/maketalk-7da59a87/N5-Q22gbtnd5e37o/images/administradores/flow-builder/bloco-inicio.png?fit=max&auto=format&n=N5-Q22gbtnd5e37o&q=85&s=32502a77660b6930315145ea547d0884" alt="Bloco Início" width="2822" height="1454" data-path="images/administradores/flow-builder/bloco-inicio.png" />
</Frame>

O bloco **Início** é o ponto de entrada do fluxo e define o contexto da conversa:

| Configuração               | Descrição                                             | Valor padrão        |
| -------------------------- | ----------------------------------------------------- | ------------------- |
| **Variáveis**              | Dados disponíveis na conversa (nome, telefone, canal) | Nome e canal ativos |
| **Variáveis customizadas** | Variáveis adicionais que você pode criar              | —                   |
| **Idioma**                 | Idioma principal do agente                            | Português (BR)      |
| **Fuso horário**           | Fuso para referências de data/hora                    | America/Sao\_Paulo  |
| **Tempo de sessão**        | Minutos de inatividade antes de reiniciar a sessão    | 30 min              |

<Tip>
  O tempo de sessão pode ser configurado para até **24 horas** (1440 minutos). Isso é útil para interações longas — como processos de cotação ou negociação — onde o cliente pode demorar para responder, mas você quer que o agente mantenha todo o contexto da conversa.
</Tip>

### 2. Bloco Prompt Base

<Frame caption="Bloco Prompt Base com contexto e regras">
  <img src="https://mintcdn.com/maketalk-7da59a87/N5-Q22gbtnd5e37o/images/administradores/flow-builder/bloco-prompt-base.png?fit=max&auto=format&n=N5-Q22gbtnd5e37o&q=85&s=ab5ef4e34f23f8538c2d985ed2510f30" alt="Bloco Prompt Base" width="2822" height="1510" data-path="images/administradores/flow-builder/bloco-prompt-base.png" />
</Frame>

O **Prompt Base** é onde você define a inteligência do agente. Este é o bloco mais importante para a qualidade das respostas.

| Campo          | Descrição                                          | Dica                                    |
| -------------- | -------------------------------------------------- | --------------------------------------- |
| **Contexto**   | Informações sobre sua empresa, produtos e serviços | Seja detalhado e específico             |
| **Regras**     | Comportamentos que o agente deve seguir            | Ex: "Sempre pergunte o nome do cliente" |
| **Restrições** | O que o agente NÃO deve fazer                      | Ex: "Nunca invente informações"         |
| **Exemplos**   | Pares de pergunta/resposta para guiar o tom        | Opcional, mas melhora a consistência    |
| **Guardrails** | Limites de segurança adicionais                    | Ex: "Não discuta temas políticos"       |
| **Avançado**   | Instruções complexas em texto livre                | Para cenários específicos               |

#### Exemplo de Contexto

```markdown theme={null}
Você é a assistente virtual da Construtora Horizonte.
A empresa atua no mercado imobiliário há 15 anos.

Empreendimentos disponíveis:
- Residencial Aurora: apartamentos de 2 e 3 quartos no centro
- Condomínio Vista Verde: casas com 3 suítes no bairro jardim

Horário de atendimento: Segunda a sexta, 8h às 18h.
```

#### Exemplo de Regras

```
1. Sempre pergunte qual empreendimento interessa ao cliente
2. Colete nome e telefone antes de agendar visita
3. Se o cliente perguntar sobre financiamento, encaminhe para humano
```

#### Exemplo de Restrições

```
1. NÃO invente informações sobre valores ou condições
2. NÃO compare com construtoras concorrentes
3. NÃO faça promessas de prazo de entrega
```

### 3. Bloco Configuração do Agente

<Frame caption="Bloco Configuração do Agente">
  <img src="https://mintcdn.com/maketalk-7da59a87/N5-Q22gbtnd5e37o/images/administradores/flow-builder/bloco-configuracao-agente.png?fit=max&auto=format&n=N5-Q22gbtnd5e37o&q=85&s=2002e7b0e5691ed24e63bd047d8042fd" alt="Configuração do Agente" width="2836" height="1502" data-path="images/administradores/flow-builder/bloco-configuracao-agente.png" />
</Frame>

A **Configuração do Agente** define a personalidade e o comportamento operacional:

| Campo                | Descrição                                    | Exemplo                                 |
| -------------------- | -------------------------------------------- | --------------------------------------- |
| **Nome**             | Identificador do agente                      | "Bella"                                 |
| **Função**           | Papel que o agente desempenha                | "Consultora comercial"                  |
| **Tom**              | Personalidade e estilo de comunicação        | "Amigável e profissional"               |
| **Idioma**           | Idioma das respostas                         | Português (BR)                          |
| **Saudação**         | Mensagem inicial enviada ao cliente          | "Olá! Sou a Bella, como posso ajudar?"  |
| **Fallback**         | Resposta quando o agente não consegue ajudar | "Não tenho essa informação no momento." |
| **Máximo de falhas** | Tentativas antes de transferir para humano   | 3                                       |
| **Ação ao exceder**  | O que fazer após as falhas                   | Transferir para humano                  |

***

## Templates disponíveis

Os templates são modelos pré-configurados com blocos adicionais já conectados:

| Template       | Segmento            | Blocos adicionais                                                           |
| -------------- | ------------------- | --------------------------------------------------------------------------- |
| **Hotel**      | Hotéis e pousadas   | Roteador, Cotação de Hotel, Transferência, Base de Conhecimento, Página Web |
| **E-commerce** | Lojas online        | Transferência, Integração API                                               |
| **Suporte**    | Atendimento técnico | Transferência, Base de Conhecimento                                         |

<Tip>
  Mesmo usando um template, todos os blocos podem ser editados, removidos ou reorganizados. O template é apenas um ponto de partida que acelera a configuração.
</Tip>

***

## Boas práticas para o Prompt Base

### Seja específico

<Tabs>
  <Tab title="Ruim">
    ```
    Você é um assistente de vendas.
    Seja educado e ajude o cliente.
    ```
  </Tab>

  <Tab title="Bom">
    ```
    Você é o Carlos, consultor comercial da TechSoft.

    Seu objetivo é:
    1. Entender a necessidade do cliente
    2. Apresentar a solução adequada
    3. Qualificar se tem orçamento e prazo
    4. Agendar demonstração se qualificado

    Tom: Profissional e consultivo, como um especialista
    que genuinamente quer ajudar.

    IMPORTANTE: Não fale de preços - encaminhe para humano.
    ```
  </Tab>
</Tabs>

### Defina limites claros

Use o campo **Restrições** para listar o que o agente NÃO deve fazer:

```
- NÃO discuta preços ou descontos
- NÃO faça promessas de prazo de entrega
- NÃO compare com concorrentes
- SEMPRE transfira para humano se o cliente insistir
```

### Use exemplos quando necessário

O campo **Exemplos** aceita pares de pergunta/resposta que guiam o tom do agente:

| Pergunta do cliente | Resposta esperada                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| "Quanto custa?"     | "O investimento varia conforme suas necessidades. Posso agendar uma conversa com nosso consultor para uma proposta personalizada?" |
| Cliente irritado    | "Entendo sua frustração e peço desculpas. Vou transferir você para um especialista que poderá resolver essa questão."              |

***

## Vinculando a uma caixa de entrada

Após criar e publicar o agente, você precisa vinculá-lo a uma caixa de entrada para que ele comece a atender. A vinculação é feita **no Make Talk**, não no Flow Builder.

<Steps>
  <Step title="Publique o agente">
    No Flow Builder, certifique-se de que o agente está com status **Publicado**. Agentes em rascunho não aparecem para vinculação.
  </Step>

  <Step title="Acesse o Make Talk">
    Vá em **Configurações → Caixas de Entrada** e selecione a caixa onde deseja ativar o agente.
  </Step>

  <Step title="Vá em Configurações do bot">
    Clique na aba **Configurações do bot** dentro das configurações da caixa de entrada.
  </Step>

  <Step title="Selecione AI Flow Builder">
    Escolha a opção **AI Flow Builder** e selecione o agente desejado no dropdown.
  </Step>

  <Step title="Salve a configuração">
    Clique em **Atualizar**. O agente começará a atender automaticamente.
  </Step>
</Steps>

<Note>
  Uma caixa de entrada pode ter apenas um agente ativo por vez. Se você vincular um novo agente, o anterior será substituído automaticamente.
</Note>

<Card title="Guia completo de integração" icon="link" href="/administradores/flow-builder/integrar-inbox">
  Veja o passo a passo detalhado com imagens.
</Card>

***

## Testando o agente

Antes de colocar em produção, teste extensivamente:

### Checklist de testes

<Check>
  Perguntas básicas sobre seu produto/serviço
</Check>

<Check>
  Perguntas fora do escopo (deve responder adequadamente)
</Check>

<Check>
  Situações que devem transferir para humano
</Check>

<Check>
  Cliente irritado ou com reclamação
</Check>

<Check>
  Múltiplas perguntas na mesma mensagem
</Check>

<Check>
  Mensagens em outros idiomas (se aplicável)
</Check>

### Simulando conversas

<Frame caption="Playground de teste do agente">
  <img src="https://mintcdn.com/maketalk-7da59a87/qpFJkk1VzAQuV40_/images/administradores/flow-builder/flow-builder-playground.png?fit=max&auto=format&n=qpFJkk1VzAQuV40_&q=85&s=ab1ec1f37e28a4b40f21b68bbff14ad1" alt="Playground de teste" width="2998" height="1564" data-path="images/administradores/flow-builder/flow-builder-playground.png" />
</Frame>

Use a função de **Playground** do Flow Builder para simular conversas completas:

1. Clique em **"Testar Agente"** (ícone de play)
2. Digite mensagens como se fosse um cliente
3. Observe as respostas e o fluxo
4. Ajuste o prompt ou fluxo conforme necessário

***

## Solução de problemas

<AccordionGroup>
  <Accordion title="O agente responde de forma genérica demais">
    **Solução:** Adicione mais contexto e exemplos específicos no bloco **Prompt Base**. Inclua informações sobre seus produtos/serviços no campo Contexto ou vincule uma base de conhecimento.
  </Accordion>

  <Accordion title="O agente inventa informações">
    **Solução:** Adicione nas **Restrições**: "Se você não souber a resposta, diga 'Vou verificar essa informação com nossa equipe' e transfira para um humano."
  </Accordion>

  <Accordion title="O agente é formal demais / informal demais">
    **Solução:** Ajuste o campo **Tom** no bloco Configuração do Agente e adicione exemplos de resposta no Prompt Base para guiar o estilo de comunicação.
  </Accordion>

  <Accordion title="O agente não transfere quando deveria">
    **Solução:** Liste explicitamente nas **Regras** do Prompt Base as situações que exigem transferência. Configure também o bloco de Transferência (Handoff) no fluxo.
  </Accordion>

  <Accordion title="O agente importado está com configurações faltando">
    **Solução:** Ao importar, recursos como bases de conhecimento, equipes e credenciais de API são específicos da conta. Reconfigure esses itens no editor após a importação.
  </Accordion>
</AccordionGroup>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Construir um Fluxo" icon="diagram-project" href="/administradores/flow-builder/construir-fluxo">
    Crie fluxos visuais para seu agente.
  </Card>

  <Card title="Base de Conhecimento" icon="database" href="/administradores/flow-builder/base-conhecimento-agente">
    Conecte uma base de conhecimento ao agente.
  </Card>
</CardGroup>