Pré-requisitos
- Um GitHub PAT para baixar imagens de contêiner e artefatos (veja enterprise-docs/github-token.md)
- Um cluster Kubernetes dedicado (veja os requisitos abaixo)
- Um bucket de armazenamento para backups de banco de dados
- Conectividade de rede: porta 443 de entrada para o load balancer do cluster
Etapa 1: Provisionar um Cluster Kubernetes Dedicado
Crie um cluster Kubernetes dedicado ao AgentEye. Ele não deve ser compartilhado com outras cargas de trabalho, para que a plataforma completa (serviços de aplicação, bancos de dados, análises e cache) seja executada de forma isolada sem impactar sua infraestrutura existente.| Requisito | Detalhes |
|---|---|
| Distribuição | Qualquer Kubernetes conformante: EKS, GKE, AKS ou autogerenciado |
| Versão | 1.27 ou posterior |
| Pool de nós | Mínimo: 3 nós, 4 vCPU / 8 GB de RAM cada (instâncias de uso geral padrão) |
| Armazenamento | Um StorageClass padrão que provisiona volumes em bloco (ex.: gp3 na AWS, pd-ssd no GCP) |
| Load Balancer | O cluster deve ser capaz de provisionar serviços de LoadBalancer na nuvem (padrão no EKS, GKE, AKS) |
A Exosphere instala e gerencia tudo o mais dentro do cluster: controladores de ingress, certificados TLS, bancos de dados, cache, monitoramento e todas as implantações de aplicações.
Etapa 2: Conceder Acesso à Equipe do AgentEye
A Exosphere precisa de acesso de cluster-admin (ou RBAC amplo equivalente) para gerenciar namespaces, definições de recursos personalizados, controladores de ingress e provisionadores de armazenamento.| Requisito | Detalhes |
|---|---|
| Método de acesso | IAM role (preferido para EKS/GKE), kubeconfig ou acesso baseado em SSO |
| VPN / bastion | Se o servidor de API do Kubernetes for privado, forneça credenciais de VPN ou acesso via bastion para a equipe de operações da Exosphere |
Etapa 3: Configurar Conectividade de Rede
Sua equipe de rede precisa permitir tráfego de entrada na porta 443 para os load balancers do cluster. A implantação utiliza dois load balancers separados: um para ingestão de eventos (protegido por mTLS) e outro para o painel:| Tráfego | Origem | Destino | Segurança |
|---|---|---|---|
| Ingestão de eventos | Pods coletores nos seus clusters | Ingest LoadBalancer, porta 443 | mTLS (certificado de cliente) + chave de API |
| Painel | Navegadores dos desenvolvedores | Dashboard LoadBalancer, porta 443 | HTTPS no seu domínio, login OTP por e-mail sem senha |
agenteye.sua-empresa.exemplo) — apontando para os hostnames do load balancer fornecidos pela Exosphere. A Exosphere então provisiona automaticamente certificados TLS publicamente confiáveis para ambos os hostnames, incluindo renovações.
Observação sobre a porta 80: a emissão e renovação automáticas de certificados são validadas via HTTP na porta 80 de cada load balancer. Se sua política de segurança exigir restringir o load balancer do painel a intervalos de IP corporativos, informe a Exosphere com antecedência — nós alteramos a validação de certificados para um método baseado em DNS (um registro DNS extra do seu lado) para que as renovações continuem funcionando por trás da restrição.
Saída: os nós do cluster precisam de acesso à internet para baixar imagens de contêiner doghcr.io. Se sua rede restringir o tráfego de saída, adicioneghcr.ioà lista de permissões ou espelhe as imagens para seu registro interno.
Etapa 4: Fornecer um Bucket de Armazenamento para Backup
Os backups do banco de dados são armazenados em um bucket de armazenamento na nuvem que você possui.| Requisito | Detalhes |
|---|---|
| Serviço | S3 (AWS), GCS (GCP) ou Azure Blob Storage |
| Acesso | Conceda acesso de escrita aos nós do cluster via IAM role para contas de serviço (IRSA no EKS, Workload Identity no GKE) ou forneça credenciais |
| Retenção | Você controla a política de ciclo de vida do bucket (período de retenção, regras de arquivamento). A Exosphere grava os backups; você decide por quanto tempo mantê-los |
Etapa 5: Designar um Ponto de Contato
Forneça uma pessoa ou canal do Slack/Teams do seu lado para questões no nível do cluster: integridade dos nós, limites da conta na nuvem, mudanças na rede. As operações do dia a dia não envolvem esse contato.O Que Implantamos
Assim que a Exosphere tiver acesso ao cluster, os seguintes componentes são implantados e gerenciados para você:| Componente | Função |
|---|---|
| AgentEye Server | API HTTP que recebe eventos dos coletores, executa análises e serve dados para o painel |
| Dashboard | Interface web para visualizar sessões de agentes, chamadas de ferramentas, requisições de modelos e erros; hospeda o assistente de IA opcional somente leitura |
| ClickHouse | Armazenamento canônico obrigatório para eventos ingeridos, análises e avaliações |
| PostgreSQL | Armazenamento relacional para organizações, chaves de API, usuários, painéis e consultas salvas |
| Redis | Cache compartilhado opcional e backend de limitação de taxa; a plataforma degrada graciosamente se estiver indisponível |
| Assistente de IA (opcional) | Contêiner assistente interno somente leitura; permanece desativado até que um endpoint de LLM seja configurado |
| Controladores de ingress | Dois load balancers (um para ingestão protegida por mTLS, outro para o painel) encerrando TLS com certificados publicamente confiáveis e renovados automaticamente, e aplicando mTLS no endpoint de ingestão |
| cert-manager | Automatiza o provisionamento de certificados TLS e a emissão de certificados de cliente mTLS |
| Monitoramento de certificados | Um job agendado verifica a expiração de certificados e envia alertas (ex.: para o Slack) à medida que os certificados se aproximam da renovação |
O Que Fornecemos a Você
Após a conclusão da implantação, você recebe:| Item | Detalhes |
|---|---|
| URL do painel | Um hostname no seu domínio (ex.: https://agenteye.sua-empresa.exemplo), servido com um certificado TLS publicamente confiável e renovado automaticamente. Você cria um CNAME para o hostname do load balancer que fornecemos; o login é OTP por e-mail sem senha |
| Endpoint do coletor | O caminho /events do hostname de ingestão (ex.: https://ingest.sua-empresa.exemplo/events), protegido por mTLS |
| Bundle de certificado de cliente | Por cluster: certificado de cliente, chave privada e certificado CA entregues como um manifesto de Secret do Kubernetes. Aplique uma vez por cluster |
| GitHub PAT | Para baixar binários do coletor e pacotes do SDK Python |
| Chaves de API do coletor | Chaves com escopo de permissão events:add, uma por implantação de coletor |
| Guias de instalação | Documentação passo a passo para o coletor e o SDK Python |
O Que Você Faz Após a Configuração
Seu único trabalho contínuo é nas suas próprias máquinas de agentes, não no cluster do AgentEye:- Instale o coletor em cada cluster Kubernetes que executa agentes de IA: monte o certificado de cliente e configure a URL do endpoint e a chave de API. Veja enterprise-docs/collector-installation.md.
- Integre o SDK Python no código do seu agente. Veja enterprise-docs/python-sdk.md.
- Abra o painel no seu navegador para visualizar a atividade dos agentes.
Segurança
- Os dados permanecem na sua conta na nuvem. O cluster, o armazenamento e os bancos de dados são todos executados no seu ambiente. Nenhum dado sai do seu perímetro.
- Você controla o acesso. O cluster está na sua conta. Você pode auditar, monitorar ou revogar o acesso da Exosphere a qualquer momento. Todas as operações passam pelo log de auditoria da sua nuvem (CloudTrail, GCP Audit Logs, etc.).
- mTLS na ingestão de eventos. Cada requisição do coletor exige tanto um certificado de cliente válido quanto uma chave de API. Uma chave vazada é inútil sem o certificado; um certificado roubado é inútil sem uma chave válida.
- Controle de acesso ao painel. O painel é executado em seu próprio load balancer, separado da ingestão de eventos, e o login é OTP por e-mail sem senha, restrito aos endereços de e-mail/domínios na sua lista de permissões. Uma lista de permissões de intervalo de IP de origem no load balancer está disponível mediante solicitação; como a renovação automática de certificados precisa alcançar o load balancer, a Exosphere combina a restrição com a validação de certificados baseada em DNS para que as renovações continuem funcionando.
- Certificados por cluster. Cada um dos seus clusters recebe seu próprio certificado de cliente. Se um cluster for comprometido, esse certificado é revogado de forma independente, sem afetar os demais.
Cronograma de Implantação
| Fase | Duração | Seu envolvimento |
|---|---|---|
| Provisionamento do cluster | 1-2 dias | Provisionar o cluster e conceder acesso à Exosphere |
| Configuração da plataforma | 1 dia | Nenhum; a Exosphere instala todos os componentes de infraestrutura |
| Implantação da aplicação | 1 dia | Nenhum; a Exosphere implanta o servidor, o painel e cria as chaves de API |
| Rollout do coletor | 1-3 dias | Instalar os coletores nos seus clusters (com orientação da Exosphere) |
| Estabilização em produção | 1 semana | Nenhum; a Exosphere monitora e ajusta |
Suporte
Para dúvidas ou problemas, entre em contato com a Exosphere emsupport@exosphere.host.
Próximos Passos
- Primeiros Passos: guia completo de ponta a ponta
- Instalação do Coletor: instalar e configurar o coletor
- SDK Python: instrumentar o código do seu agente
- Chaves de API: gerenciar acesso e permissões
- Solução de Problemas: problemas comuns e soluções