---
title: AI Agent
description: Permita aos clientes gerenciar VMs Linux em linguagem natural — como o Agent conecta via SSH, o que executa sozinho e os requisitos necessários.
url: https://nexcmp.com/pt/docs/ai/ai-agent/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI Agent {#ai-agent}

> **Onde no admin:** System › Settings › AI provider (`/settings/ai`) — interruptor do módulo e provedor; System › Admin › License & updates (`/license`) — interruptor do módulo. **Onde no portal:** AI Agent (`/ai/agent`) e a página `/chat/agent`, ou o modo **Agent** dentro do chat.

## O que faz {#what-it-does}

O AI Agent se conecta à VM Linux própria de um cliente via SSH e executa tarefas descritas em linguagem natural: "verificar integridade do sistema", "instalar o Docker", "encontrar erros recentes", "liberar espaço em disco". Ele exibe cada comando proposto e sua saída. Comandos somente leitura podem ser executados automaticamente; qualquer alteração no servidor aguarda o cliente pressionar **Run**.

## Requisitos {#requirements}

| Item | Requisito |
|---|---|
| Módulo de IA e provedor | O módulo **AI** ativado e um [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/) funcional. O Agente também precisa de um modelo que suporte chamada de ferramentas. |
| `openssh-client` no servidor do painel | O Agente executa comandos com o programa `ssh` próprio do painel (`/usr/bin/ssh`). O instalador instala o `openssh-client`; verifique com `ssh -V`. Sem ele, o Agente relata "ssh client is not installed on the panel server". |
| Sem gateway SSH separado | Na instalação padrão, o SSH integrado é usado e o terminal web `ssh-proxy` **não** é necessário. Somente quando o recurso opcional de *web SSH* (`feature_ssh_web`) é habilitado e o serviço `ssh-proxy` é instalado é que o Agente passa pelo `ssh-proxy`. |
| Rede | O servidor do painel deve alcançar o IP da VM em sua porta SSH (22 por padrão). Verifique firewalls e grupos de segurança entre o painel e a rede de convidados. |
| VM | De propriedade do cliente, **em execução**, não bloqueada, **Linux** (VMs Windows são recusadas), com um endereço IP público ou alcançável. |
| Credenciais SSH | O usuário e senha de login da VM armazenados pelo NexCMP (salvos quando a VM foi criada ou sua senha foi redefinida, criptografados), ou a chave de operações do painel se houver uma instalada. Se nenhum dos dois existir, o Agente informará que não pode fazer login. |

## Preparar a infraestrutura {#prepare-the-infrastructure}

1. Verifique o cliente SSH no servidor do painel:

   ```bash
   ssh -V
   sudo apt-get install -y openssh-client   # only if missing
   ```

2. Verifique se o servidor do painel consegue abrir o SSH para uma VM convidada:

   ```bash
   nc -vz 198.51.100.10 22
   ```

   Substitua o endereço pelo IP de uma VM de teste. Se isso falhar, corrija o roteamento ou o firewall primeiro.
3. Certifique-se de que o convidado permita login por senha para o usuário armazenado pelo NexCMP (algumas imagens em nuvem o desativam) ou que a chave de operações do painel esteja instalada no convidado.

## Conectar no NexCMP {#connect-in-nexcmp}

1. Complete o [AI provider](https://nexcmp.com/pt/docs/ai/ai-providers/): módulo ativado, provedor salvo, **Test connection** verde.
2. Nada mais é configurado no lado do admin. O interruptor do módulo faz com que as entradas do **AI Agent** apareçam no portal do cliente.
3. Como cliente: abra o **AI Agent**, escolha um servidor em execução e clique em **Choose server**. A página primeiro testa o SSH com um comando fixo inofensivo (nenhuma chamada de IA é usada) e exibe *SSH connected* ou o motivo da falha.
4. Digite uma tarefa ou escolha um início rápido (*Check system health*, *Install Docker*, *Install Nginx*, *Find recent errors*, *Security check*, *Free up disk space*).



## Como ele executa comandos {#how-it-runs-commands}

- **De onde:** o servidor do painel, com o `ssh` client do sistema, um comando não interativo por vez. O destino é sempre o IP da VM **proveniente do banco de dados**, nunca da requisição; apenas a VM própria, em execução e desbloqueada do proprietário pode ser acessada.
- **Autenticação:** a senha armazenada é passada por meio de um auxiliar `SSH_ASKPASS` de uso único no ambiente de processo — ela não é gravada em disco nem inserida na linha de comando. As chaves de host não são fixadas (as VMs são reinstaladas com novas chaves). A saída por comando é limitada a 200 KB e cada comando possui um limite de tempo (60 segundos).
- **Loop do agente:** a IA propõe comandos e lê as saídas; um turno termina após no máximo **10 etapas**.
- **Modos:**

  | Modo | Comportamento |
  |---|---|
  | **Confirm** | Cada comando aguarda por **Run**. |
  | **Auto** | Apenas comandos que passam por uma lista de permissões estrita somente leitura são executados sozinhos (por exemplo `df -h`, `ps`, `journalctl`). Qualquer outra coisa, e qualquer coisa que o analisador não possa analisar com certeza (variáveis, substituição de comando, redirecionamentos para arquivos), aguarda por **Run**. |

- **Rótulos de risco:** comandos que sobrescrevem ou excluem arquivos, gravam em discos, alteram contas ou chaves SSH, enviam dados para um servidor externo, abrem conexões de rede brutas, executam código ofuscado, baixam e executam um script, desligam ou reiniciam a máquina, ou alcançam outros servidores sempre mostram **Needs confirmation**, mesmo no modo Auto.
- **Saída não confiável:** a saída do comando é mostrada ao modelo como dados não confiáveis; as instruções contidas nela não são seguidas.

## Verificar {#verify}

1. Escolha uma VM de teste em execução. A página exibe *SSH connected*.
2. Peça "Check CPU, RAM and disk". No modo Auto, os comandos somente leitura são executados e a resposta os resume.
3. Peça "Install Nginx". O comando de instalação aparece com **Run** e **Skip**; nada é executado até que você pressione **Run**.
4. O contador na parte superior mostra o número de chamadas de IA usadas hoje (por exemplo `3/300`).

## Limites e notas {#limits-notes}

- **Limite diário:** 300 chamadas de IA por cliente por dia (UTC); ele é redefinido às 00:00 UTC. Quando esgotado, o Agente responde "Daily AI quota reached".
- **Concorrência:** no máximo 2 execuções do Agente por cliente ao mesmo tempo; uma sessão executa um turno de cada vez.
- **Sessões:** até 100 mensagens por sessão, 4,000 caracteres por mensagem. Uma sessão pertence a uma VM; se a VM for excluída ou transferida, a sessão antiga torna-se somente leitura.
- **VM bloqueada ou parada, ou Windows:** a VM é exibida como *Locked*, *Stopped*, *Windows* ou *No address* e não pode ser escolhida.
- **Personificação:** um administrador personificando um cliente não pode usar os recursos de credencial do Agente (consulte [Log in as a customer](https://nexcmp.com/pt/docs/customers/login-as/)).
- **Responsabilidade:** o Agente pode cometer erros. O portal instrui os clientes a revisarem os comandos antes de executá-los. Informe aos clientes em seus termos que eles são responsáveis pelos comandos que aprovam.
- Desativar o módulo de IA remove as entradas do Agente e as rotas respondem com 404 `module_disabled`.

## Resolução de problemas {#troubleshooting}

| Sintoma | Causa | Correção |
|---|---|---|
| "o cliente ssh não está instalado no servidor do painel (apt install openssh-client)" | Sem o binário `ssh` | `sudo apt-get install -y openssh-client`. |
| "O Agent não conseguiu fazer login" / `ssh: no saved credentials for this VM` | Sem senha armazenada e sem chave de operações | Redefina a senha da VM no portal para que ela seja salva novamente ou instale a chave de operações. |
| "O servidor não respondeu a tempo" | Firewall, SSH não escutando, VM ocupada | Teste `nc -vz <ip> 22` a partir do servidor do painel; inicie `sshd` na VM. |
| "Não foi possível acessar o SSH neste servidor" | Roteamento ou grupo de segurança | Permita que o servidor do painel alcance a VM na porta 22. |
| "VM não está em execução" / "Proibido" | VM parada, bloqueada, excluída ou que não pertence ao cliente | Inicie-a, desbloqueie-a ou escolha outra. |
| "Não disponível: N (parada, bloqueada ou Windows)" | Motivos listados acima | A VM deve ser Linux e estar em execução. |
| "O gateway SSH está temporariamente indisponível" | Recurso de SSH Web ativado, mas o `ssh-proxy` está fora do ar | Inicie o `ssh-proxy` ou desative o recurso de SSH Web para usar o SSH integrado. |
| "A IA está demorando muito para responder (mais de 90 segundos)" | Provedor lento | Use um modelo mais rápido ou um **Reasoning effort** menor. |
| "Cota diária de IA atingida" | 300 chamadas usadas | Aguarde até 00:00 UTC. |
| "Esta sessão ainda está em execução" | Outro turno em andamento | Aguarde ou pressione **Stop**. |