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

# Guia de configuração do agente de IA

> Vá de uma chave de licença a um agente de IA que responde aos seus tickets do Discord.

A configuração leva cerca de 15 minutos. Você precisa de quatro coisas:

* Uma **chave de licença** do EchoAuth AI Agent. [Compre uma na loja](https://shop.echoauth.dev/product/echos-ai-agent-hosted) se você ainda não tiver.
* Um **servidor do Discord** onde você possa adicionar bots e gerenciar cargos.
* Uma **chave de API do [OpenRouter](https://openrouter.ai)**. Uma única chave do OpenRouter cobre tudo o que o agente precisa: respostas, capturas de tela e busca.
* Opcionalmente, um **site de documentação** ou documentação escrita para o agente usar nas respostas.

Nós hospedamos seu agente e o mantemos em execução. Você o configura pelo painel em [agent.echoauth.dev](https://agent.echoauth.dev).

> [!NOTE]
>
> **Configuração recomendada.** Os testes de longo prazo foram feitos apenas com o OpenRouter, usando estes três modelos:
>
> | Função | Modelo |
> | - | - |
> | Chat / Agent | `deepseek/deepseek-v4-flash-0731` |
> | Embedding | `qwen/qwen3-embedding-8b` |
> | Vision (detecção de imagens) | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` |
>
> Outros provedores (NVIDIA, OpenAI, Anthropic) estão disponíveis no painel, mas esta é a combinação que testamos ao longo do tempo.

## 1. Crie sua conta

**1. Abra a página de registro**

Acesse [agent.echoauth.dev/register](https://agent.echoauth.dev/register).

**2. Informe sua chave de licença**

Cole a chave do e-mail da sua compra. Ela se parece com `ECHO-XXXX-XXXX-XXXX-XXXX`.

**3. Escolha um nome de usuário e uma senha**

Sua senha precisa ter pelo menos 8 caracteres. Clique em **Create account**.

![Formulário de registro com campos de chave de licença, nome de usuário e senha](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/01-register.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=572419f600e4182cf06122e903cf3aa6)

A página de registro

Quando sua licença estiver ativa, seu agente é criado para você. Você chega ao painel, onde vê o agente, sua licença e as estatísticas de uso.

![Painel mostrando um agente, o status da licença e o uso](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/02-dashboard.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=2397a77fc1428106e09dcbc3b2869dab)

O painel depois de entrar

> [!NOTE]
>
> Se aparecer **No agents yet**, abra **License** na barra lateral e verifique se sua licença está ativa.

Clique no seu agente para abrir a página dele. Todo o resto deste guia começa aqui: **Configure** abre as configurações, **Live logs** mostra o que o agente está fazendo e **Update Agent** aplica as configurações que exigem uma nova publicação.

![Página do agente com Configure, Live logs, Restart e Update Agent](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/03-agent.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=6c4ca792bd16efd8e9e175519f337123)

A página do agente

## 2. Crie seu bot do Discord

Seu agente responde por meio de um bot do Discord que pertence a você. Crie um no Discord Developer Portal.

**1. Crie um aplicativo**

Abra o [Discord Developer Portal](https://discord.com/developers/applications) e clique em **New Application**. Dê a ele o nome do seu agente de suporte, por exemplo "Acme Support".

**2. Ative a intent Message Content**

Vá em **Bot**. Em **Privileged Gateway Intents**, ative **Message Content Intent** e salve.

> [!WARNING]
>
> Sem essa intent, o bot recebe mensagens vazias e nunca responde.

**3. Copie o token do bot**

Ainda em **Bot**, clique em **Reset Token** e copie o token. Você vai colá-lo no painel na próxima seção. Mantenha-o privado: qualquer pessoa com o token pode controlar seu bot.

**4. Convide o bot para o seu servidor**

Vá em **OAuth2** → **URL Generator**. Marque os escopos `bot` e `applications.commands` e depois estas permissões do bot:

* View Channels
* Send Messages
* Read Message History
* Embed Links
* Attach Files

Abra a URL gerada e adicione o bot ao seu servidor.

**5. Dê ao bot acesso à sua categoria de tickets**

Verifique se o cargo do bot consegue ver a categoria em que seus canais de ticket são criados. Se ele não enxergar o canal, não consegue responder.

## 3. Adicione suas chaves

Crie uma chave de API em [openrouter.ai/keys](https://openrouter.ai/keys) e adicione crédito à sua conta do OpenRouter. O modelo de visão é gratuito, mas os modelos de chat e de embedding são pagos por uso.

Depois, na página do seu agente, clique em **Configure** e abra a aba **API Keys**.

![Aba API Keys mostrando a chave de API do OpenRouter e o token do bot do Discord marcados como configured](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/04-keys.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=635dd8eb112950e6f74cfdc24c4f5664)

A aba API Keys, com a chave do OpenRouter e o token do bot do Discord configurados

1. Cole sua chave em **OpenRouter API Key**.
2. Cole o **Discord Bot Token**.
3. Clique em **Save**.

Você pode deixar os campos da OpenAI, da Anthropic e da NVIDIA vazios. As chaves são armazenadas criptografadas e nunca mais são exibidas depois de salvas. Um selo **configured** confirma que a chave está definida.

## 4. Escolha seus modelos de IA

Abra a aba **AI Settings**. O agente usa três modelos. Defina os três como **OpenRouter** e escolha os modelos recomendados:

| Configuração | O que faz | Provedor | Modelo |
| - | - | - | - |
| **Chat / Agent Model** | Escreve as respostas e decide o que consultar na sua documentação. | OpenRouter | `deepseek/deepseek-v4-flash-0731` |
| **Vision Model** | Lê as capturas de tela que os clientes anexam aos tickets. | OpenRouter | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` |
| **Embedding Model** | Indexa sua documentação e faz buscas nela. | OpenRouter | `qwen/qwen3-embedding-8b` |

![Aba AI Settings com o OpenRouter selecionado para os modelos de chat, visão e embedding](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/05-ai.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=9c43f2bab0d0ade4e7a897f04f0a21f0)

A aba AI Settings com os modelos recomendados do OpenRouter

> [!NOTE]
>
> Abaixo do modelo de embedding, o painel avisa que ele tem mais de 2000 dimensões. Isso é esperado para `qwen/qwen3-embedding-8b`. A busca continua funcionando: ela verifica cada trecho em vez de usar um índice, o que continua rápido para uma base de conhecimento de alguns milhares de trechos.

Depois, escreva seu **Base Prompt**. São as instruções permanentes do agente: para quem ele trabalha, o tom a usar e o que ele nunca deve fazer. Por exemplo:

```text theme={null}
You are the support agent for Acme Store. Be friendly and concise.
Answer only from the documentation. If you are not sure, ask a staff member to step in.
```

> [!WARNING]
>
> Escolha seu modelo de embedding antes de indexar qualquer coisa. Alterá-lo depois torna o índice existente inutilizável até que você o reconstrua.

## 5. Conecte-o aos seus tickets

Abra a aba **Discord**. Estas configurações dizem ao agente onde responder e quem conta como equipe.

![Aba Discord com cargos de owner, cargos de staff, IDs de categorias de tickets, IDs de bots de tickets e modelos de imagem](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/06-discord.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=43f9146b21aa094f8d7629f409930f57)

A aba Discord

Para copiar IDs, ative o **Developer Mode** no Discord em **User Settings** → **Advanced**. Depois clique com o botão direito em um cargo, categoria ou usuário e escolha **Copy ID**.

> [accordion] Owner Role IDs
>
> Cargos que podem usar todos os comandos de barra, incluindo `/pause_bot` e `/edit_base`. Separe vários IDs com vírgulas.

> [accordion] Staff Role IDs
>
> Os cargos da sua equipe de suporte. Quando um membro da equipe escreve em um ticket, o agente se afasta e fica em silêncio nesse ticket. Para trazê-lo de volta, mencione o bot no ticket ou use `/restart` lá.

> [accordion] Ticket Category IDs
>
> As categorias em que seus canais de ticket são criados. O agente só responde dentro dessas categorias.

> [accordion] Ticket Bot IDs
>
> O ID de usuário do seu bot de tickets, como Ticket Tool ou SellAuth Tickets. O agente ignora outros bots, então adicione o seu aqui para que o agente possa ler a mensagem de abertura do ticket.

> [accordion] Image Models
>
> Modelos de visão de reserva, um por linha, testados em ordem se o modelo de visão de AI Settings falhar. Coloque estes substitutos:\
> `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`\
> `google/gemma-4-31b-it:free`\
> `google/gemma-4-26b-a4b-it:free`\
> `thinkingmachines/inkling-small:free`\
> `dots-studio/dots-3-note-preview:free`

Clique em **Save**.

## 6. Dê ao agente a sua documentação

Abra a aba **Knowledge Base**. O agente responde a partir de duas fontes, e você pode usar uma delas ou ambas.

![Aba Knowledge Base com o botão Index documentation, a Docs URL e a base de conhecimento interna](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/07-knowledge.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=18150d070975d8635a2a87c251b04dfa)

A aba Knowledge Base

> [tab] Docs site
>
> Use esta opção se sua documentação estiver publicada no Mintlify.
>
> 1. Informe sua **Docs URL**, por exemplo `https://docs.acme-store.com`, sem barra no final. O site precisa servir `/llms.txt`, o que o Mintlify faz automaticamente.
> 2. Clique em **Save**, vá à página do seu agente e clique em **Update Agent**.
> 3. De volta a esta aba, clique em **Index documentation**. Algumas centenas de páginas levam alguns minutos, e você pode sair da página enquanto roda.
>
> Com **Sync Mode** em **Poll llms.txt hourly**, o agente verifica sua documentação a cada hora e reindexa apenas as páginas que mudaram.

> [tab] Internal knowledge base
>
> Use esta opção para tudo o que não está em um site de documentação: perguntas frequentes, políticas, códigos de erro.
>
> 1. Role até **Internal Knowledge Base**.
> 2. Cole seu texto ou clique em **Load file** e escolha um arquivo `.txt` ou `.md`.
> 3. Clique em **Save**.
>
> O agente o indexa em cerca de um minuto. Texto simples funciona bem: títulos em MAIÚSCULAS ou entre linhas de `=====` viram seções pesquisáveis.

Mantenha **Documentation Retrieval** e **Agentic Retrieval** ativados. Com a recuperação ativada, o agente consulta apenas os trechos relevantes para cada pergunta em vez de ler tudo toda vez.

## 7. Defina o tempo de resposta e a escalada

Abra a aba **Behavior**.

![Aba Behavior com o tempo de resposta e as palavras-chave de ajuda humana](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/08-behavior.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=14df915b4ac0f9860f6e3a6b3a61d318)

A aba Behavior

O agente espera até o cliente parar de digitar e depois responde a tudo em uma única resposta. Cada nova mensagem reinicia o temporizador.

| Configuração | Padrão | Significado |
| - | - | - |
| After ticket opens | 45 s | Espera após a primeira mensagem, pois os clientes costumam adicionar detalhes ou capturas de tela. |
| After each message | 30 s | Tempo de silêncio necessário após as mensagens seguintes antes de responder. |
| Maximum wait | 180 s | Responde após esse tempo, mesmo que o cliente continue digitando. |

Em **Human Help Keywords**, liste as palavras que devem passar o ticket para sua equipe, uma por linha. Por exemplo `refund`, `chargeback` ou `real person`.

## 8. Receba alertas (opcional)

Abra a aba **Notifications** e cole o ID de um canal privado da equipe. O agente publica ali quando sua licença está prestes a expirar e quando um provedor de IA rejeita sua chave ou fica sem cota.

![Aba Notifications com o ID do canal de notificações](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/09-notifications.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=5906f4bf0dbdf4fa308c4958553bded2)

A aba Notifications

## 9. Inicie o agente

Volte à página do seu agente e clique em **Update Agent**. Isso publica o agente novamente com o token do seu bot, a URL da documentação e o modelo de embedding. A saída aparece abaixo do botão enquanto ele roda.

> [!NOTE]
>
> A maioria das configurações chega ao agente em execução em cerca de um minuto, sem nova publicação. Você só precisa de **Update Agent** depois de alterar o **Discord Bot Token**, a **Docs URL**, o **Embedding Model** ou o **Sync Mode**.

Para verificar se tudo funciona:

1. Abra um ticket de teste no seu servidor e faça uma pergunta que sua documentação responda.
2. Abra **Live logs** na página do seu agente e acompanhe o agente receber a mensagem, pesquisar sua documentação e responder.

![Live logs mostrando o agente iniciar, sincronizar, pesquisar a documentação e responder em um ticket](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/11-logs.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=18d1bd77e85407858cd81751cd36388e)

Live logs

O selo de status do seu agente mostra **Online** quando ele está em execução.

## Comandos de barra

Depois que o agente estiver no seu servidor, owners e equipe podem controlá-lo pelo Discord.

| Comando | Quem | O que faz |
| - | - | - |
| `/stop` | Owner, equipe | Impede o agente de responder neste canal. |
| `/restart` | Owner, equipe | Permite que o agente volte a responder neste canal. |
| `/mute_existing` | Owner, equipe | Silencia o agente em todos os tickets que já estão abertos. |
| `/pause_bot` | Owner | Pausa o agente em todos os lugares. |
| `/resume_bot` | Owner | Retoma o agente em todos os lugares. |
| `/edit_base` | Owner | Edita o base prompt. |
| `/chat_model` | Owner | Altera o modelo de chat. |

Você também pode pausar o agente pelo painel com **Global Bot Pause** na aba **Discord**.

## Mantenha sua licença ativa

Seu agente continua online enquanto sua licença estiver ativa. A página **License** mostra os dias restantes e a data de validade.

![Página de licença com status, dias restantes e planos disponíveis](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/10-license.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=62db270604520c9a0c2815db6201b908)

A página License

Para renovar, compre uma nova chave na [loja](https://shop.echoauth.dev/product/echos-ai-agent-hosted), clique em **Renew license** e cole a chave. O tempo é somado à sua licença atual.

## Solução de problemas

> [accordion] O bot está online, mas nunca responde
>
> * Verifique se **Message Content Intent** está ativada no Discord Developer Portal.
> * Verifique se o ID da categoria do ticket está em **Ticket Category IDs**.
> * Verifique se o bot consegue ver e enviar mensagens nessa categoria.
> * Verifique se um membro da equipe já não escreveu no ticket. Mencione o bot ou use `/restart` para trazê-lo de volta.
> * Verifique se **Global Bot Pause** está desativado.

> [accordion] O bot ignora a mensagem de abertura do ticket
>
> Adicione o ID de usuário do seu bot de tickets em **Ticket Bot IDs** na aba **Discord**.

> [accordion] O agente não está usando minha documentação
>
> Abra a aba **Knowledge Base**. Se aparecer **Documentation is not indexed yet**, clique em **Index documentation**. Se aparecer **The index does not match the embedding model**, clique em **Clear and rebuild the index** ou volte o modelo de embedding ao que está indicado e salve.

> [accordion] As respostas ou a indexação falham com um erro do OpenRouter
>
> Verifique se sua conta do OpenRouter tem crédito e se a chave na aba **API Keys** ainda é válida. Modelos gratuitos, como o de visão, podem ter limite de requisições em horários de pico; o agente então recorre ao próximo modelo em **Image Models**.

> [accordion] O agente parou de responder
>
> Abra **Live logs** e procure erros, por exemplo uma chave inválida ou crédito esgotado. Depois clique em **Restart** na página do agente. Se isso não resolver, clique em **Update Agent**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.