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

# Migrando para `agenteye-collector`

> Documentação de migração do AgentEye para `agenteye-collector`.

A migração é não-destrutiva: não gera downtime nem perda de dados, e libera o nome curto `agenteye` para o [AgentEye CLI](/pt-br/agenteye/cli), permitindo que o daemon coletor e o CLI coexistam na mesma máquina.

O binário do coletor foi **renomeado de `agenteye` para `agenteye-collector`**. O nome curto `agenteye` agora pertence ao AgentEye CLI, uma ferramenta separada para consultar sessões, eventos e avaliações pelo terminal.

Este guia mostra como migrar uma instalação existente do coletor.

***

## O que mudou

|                                      | Antes                                                                            | Depois                                                                                                           |
| ------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Comando / binário                    | `agenteye`                                                                       | `agenteye-collector`                                                                                             |
| Caminho de instalação padrão         | `/usr/local/bin/agenteye`                                                        | `/usr/local/bin/agenteye-collector`                                                                              |
| Subcomandos                          | `start`, `flush`, `health`, `update`                                             | `start`, `flush`, `health`                                                                                       |
| Auto-atualização (`agenteye update`) | integrada                                                                        | **removida**: baixe o novo binário ou faça pull da nova imagem                                                   |
| Script de instalação (`install.sh`)  | fornecido                                                                        | **removido**: baixe o binário diretamente (veja [Instalação do Coletor](/pt-br/agenteye/collector-installation)) |
| `AGENTEYE_TOKEN`                     | necessário para download **e** para verificações de atualização em segundo plano | necessário apenas para **baixar** binários/imagens                                                               |

A configuração permanece inalterada: o mesmo `~/.agenteye/config.json`, as mesmas variáveis de ambiente `AGENTEYE_URL` / `AGENTEYE_KEY` / `AGENTEYE_HOME` / TLS, e o mesmo spool `~/.agenteye/events/`. **Nenhuma edição de configuração é necessária.**

> Se você executar o binário renomeado com o nome antigo `agenteye`, ele ainda funcionará, mas exibirá um aviso de deprecação de uma linha no stderr lembrando que você deve migrar para `agenteye-collector`.

***

## Antes de começar

* Sua **instalação existente do `agenteye` continua funcionando**; nada quebra no momento em que você fizer o upgrade. Migre com calma e remova o binário antigo por último.
* Siga esta ordem para evitar downtime:
  1. Instale o novo binário `agenteye-collector` (ou faça pull da nova imagem).
  2. Atualize sua definição de serviço / probe de saúde / scripts para chamar `agenteye-collector`.
  3. Recarregue e reinicie o serviço; confirme que está saudável.
  4. **Somente então** remova o binário antigo `/usr/local/bin/agenteye`.

***

## 1. Instale o novo binário

Baixe o artefato para sua plataforma (`agenteye-collector-linux-x86_64`, `agenteye-collector-darwin-arm64`, entre outros; veja [Instalação do Coletor → Opção A](/pt-br/agenteye/collector-installation#option-a-binary-recommended) para a lista completa) da release mais recente `collector/v<version>` e coloque-o em `/usr/local/bin/agenteye-collector`. Usuários Docker: `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (ou uma tag fixada `:v<version>`, o que é preferível; `:latest` existe apenas para releases estáveis).

Verifique:

```bash theme={null}
agenteye-collector --version
```

***

## 2. Atualize seu deployment

### systemd (Linux)

Edite `/etc/systemd/system/agenteye-collector.service` para que o `ExecStart` aponte para o novo binário:

```ini theme={null}
[Service]
ExecStart=/usr/local/bin/agenteye-collector start
```

Em seguida, recarregue e reinicie:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart agenteye-collector
sudo systemctl status agenteye-collector
```

### launchd (macOS)

> **Renomeação de marca:** Se o seu plist existente estiver no caminho antigo
> `~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist`, renomeie
> o arquivo para `ai.befailproof.agenteye-collector.plist` e também altere o
> valor de `<key>Label</key>` dentro do arquivo para o novo identificador antes
> de recarregar.

Em `~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist`, altere a primeira entrada de `ProgramArguments` de `/usr/local/bin/agenteye` para `/usr/local/bin/agenteye-collector` e, em seguida, recarregue:

```bash theme={null}
launchctl unload ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
launchctl load   ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
```

### supervisord

No bloco de programa do seu `supervisord`, defina `command` para o novo binário:

```ini theme={null}
[program:agenteye-collector]
command=/usr/local/bin/agenteye-collector start
```

Em seguida, execute `supervisorctl reread && supervisorctl update`.

### Docker / Kubernetes

Faça pull da nova imagem (`ghcr.io/agenteye-enterprise/collector:beta-latest` ou uma tag fixada `:v<version>`, o que é preferível; `:latest` existe apenas para releases estáveis). O entrypoint da imagem já é `agenteye-collector`, portanto o mesmo comando `docker run` com o subcomando `start` continua funcionando sem alterações.

**Importante: atualize os probes de saúde.** Se você usar um probe de liveness/readiness do Kubernetes (ou qualquer `docker exec`) que execute o binário pelo nome, altere o comando para `agenteye-collector`:

```yaml theme={null}
livenessProbe:
  exec:
    command: ["agenteye-collector", "health"]
```

A nova imagem **não** inclui um alias `agenteye`, portanto um probe que ainda chame `agenteye` irá falhar. Atualize o probe no mesmo rollout da nova imagem.

### Cron / scripts manuais

Substitua todas as invocações `agenteye start|flush|health` pelo comando equivalente `agenteye-collector start|flush|health`. **Remova quaisquer cron jobs com `agenteye update`**; esse subcomando não existe mais (veja [Upgrades a partir de agora](#upgrades-from-now-on)).

***

## 3. Remova o binário antigo (por último)

Depois que o serviço estiver rodando com `agenteye-collector` e reportar saúde:

```bash theme={null}
sudo rm /usr/local/bin/agenteye
```

Isso é especialmente importante se você também usa o AgentEye CLI, que instala seu próprio comando `agenteye`; deixar o binário antigo do coletor em `/usr/local/bin/agenteye` tornaria o nome `agenteye` ambíguo no seu `PATH`.

***

## Upgrades a partir de agora

O coletor não se atualiza mais automaticamente. Para fazer upgrade:

* **Binário:** baixe o novo artefato para sua plataforma (por exemplo, `agenteye-collector-linux-x86_64`; veja [Instalação do Coletor → Opção A](/pt-br/agenteye/collector-installation#option-a-binary-recommended) para a lista completa), substitua `/usr/local/bin/agenteye-collector` e reinicie o serviço.
* **Docker:** `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (ou uma tag fixada `:v<version>`, o que é preferível; `:latest` existe apenas para releases estáveis) e recrie o container.

`AGENTEYE_TOKEN` ainda é necessário para baixar do repositório de releases privado, mas o daemon em execução não precisa mais dele.

***

## Verificar

```bash theme={null}
agenteye-collector --version    # novo binário está no PATH
agenteye-collector health       # exit 0 = saudável
agenteye-collector flush        # encaminha quaisquer eventos na fila e encerra normalmente
```

Em seguida, confirme que novos eventos aparecem no seu dashboard.

***

## Rollback

A migração é não-destrutiva. Se precisar reverter, aponte sua definição de serviço de volta para o binário antigo `/usr/local/bin/agenteye` (contanto que você ainda não o tenha removido) e reinicie. O spool de eventos e a configuração são compartilhados e não são afetados.

***

## Solução de problemas

| Sintoma                                                                     | Causa                                                          | Solução                                                                                                          |
| --------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `warning: the collector binary is now agenteye-collector …` a cada execução | Você está invocando o binário com o nome antigo `agenteye`     | Chame `agenteye-collector` no lugar; atualize arquivos de serviço e scripts.                                     |
| systemd falha: `.../agenteye: No such file or directory`                    | Você removeu o binário antigo antes de atualizar o `ExecStart` | Defina `ExecStart=/usr/local/bin/agenteye-collector start` e então execute `sudo systemctl daemon-reload`.       |
| Pod do Kubernetes entra em crash-loop após o upgrade da imagem              | O probe de liveness ainda executa `agenteye`                   | Altere o comando do probe para `["agenteye-collector", "health"]`.                                               |
| `agenteye: command not found`, mas `agenteye-collector` funciona            | Scripts/aliases ainda fazem referência ao nome antigo          | Atualize-os para `agenteye-collector`.                                                                           |
| Executar `agenteye` inicia o CLI, não o coletor                             | Você tem o AgentEye CLI instalado; ele é o dono do `agenteye`  | Use `agenteye-collector` para o daemon e remova qualquer binário antigo do coletor em `/usr/local/bin/agenteye`. |