Visão geral
O Atlas cluster vinculado do seu espaço de trabalho faz parte da política de saída baseada na plataforma. Depois de vincular um cluster, seu agente poderá acessá-lo nos modos deny_all e allow_list, e você não precisará adicionar o cluster como um destino de saída.
Neste guia, você pode aprender como vincular um Atlas cluster ao seu espaço de trabalho usando a CLI agentengine, verificar o link e alterar o cluster vinculado posteriormente.
Vincular um cluster também adiciona os endereços IP da conexão do Atlas Agent Engine à lista de acesso IP do cluster. Você não precisa adicionar esses endereços IP manualmente.
Para saber como permitir os destinos que a política base não cobre, como APIs de fornecedor de LLM e outros serviços de terceiros, consulte o guia Gerenciar políticas de saída de rede.
Pré-requisitos
Antes de começar, certifique-se de atender aos seguintes pré-requisitos:
Você tem a versão
agentengineCLI 0.1.54-alfa ou posterior instalada e ela está disponível em sua variável de ambientePATH. Para saber mais, consulte o guia Instalar e autenticar.Você pode autenticar na plataforma usando o comando
agentengine auth login.Você tem um projeto do Atlas que contém o cluster que deseja vincular ou permissão para criar um cluster nesse projeto.
Criar uma Conta de Serviço do Atlas
O agentengine CLI autentica no Atlas usando uma conta de serviço. Crie uma conta de serviço no projeto Atlas que contenha seu cluster e, em seguida, conceda a ele uma das seguintes configurações de role:
Project OwnerpapelCluster Creator,Cluster Manager,Database Access AdmineNetwork Access Managerroles
Para saber como a CLI armazena e resolve as credenciais da conta de serviço, consulte o guia Configurar recursos do Atlas .
Vincular o cluster
Selecione ou crie um cluster.
Quando a CLI solicitar, selecione o cluster que deseja vincular. Para criar um cluster, escolha a opção para criar um. Novos clusters são padronizados para a camada Flex.
Observação
Não use o M0 ou camadas compartilhadas. Para saber mais sobre os requisitos de camada do cluster , consulte o guia Configurar Recursos do Atlas .
Verificar o Link
A CLI relata duas visualizações diferentes da configuração do Atlas : o estado da CLI local e o estado da plataforma. Como esses estados podem ser diferentes, verifique ambos ao solucionar um problema de conexão.
Estado CLI local
Para revisar a configuração do Atlas registrada em sua máquina, execute o seguinte comando:
agentengine atlas setup
Este comando lê o estado local que a CLI armazena no arquivo .agentengine/state.json. Em um novo checkout ou em uma máquina diferente, o comando pode solicitar que você execute a configuração completa novamente, mesmo quando o workspace já estiver vinculado. Esse comportamento é esperado e não desvincula o cluster.
Estado da plataforma
Para revisar o link que o Atlas Agent Engine registrou, execute o seguinte comando:
agentengine atlas status
Esse comando relata o ambiente Atlas vinculado e o ID do projeto, o status da sincronização de saída e a hora da última sincronização bem-sucedida. A tabela a seguir descreve os valores de status de sincronização:
Status | Descrição |
|---|---|
| O Atlas Agent Engine tem a política de cluster atual. |
| O Atlas Agent Engine está aplicando uma alteração de política. |
| O Atlas Agent Engine não pode recuperar a política de cluster. |
Alterar o cluster vinculado
Para vincular um cluster diferente, execute o comando agentengine atlas setup novamente e selecione o novo cluster. Esse comando aponta novamente o link de saída e configura a lista de acesso IP do Atlas do novo cluster.
Observação
Se o novo cluster pertencer a um projeto Atlas diferente, sua conta de serviço também deverá ter a função Project Owner nesse projeto .
Solução de problemas
Esta seção descreve problemas que você pode encontrar ao vincular um Atlas cluster.
A configuração falha com um erro de permissão
Confirme se sua conta de serviço do Atlas tem a função Project Owner no projeto do Atlas que contém seu cluster.
A configuração não é possível vincular seu projeto Atlas
O comando agentic atlas setup vincula seu projeto Atlas ao seu espaço de trabalho automaticamente. Se o link falhar, o comando imprimirá uma observação e será concluído. Para tentar criar o link novamente, execute agentic atlas link e, em seguida, execute agentic atlas status para confirmar que o link foi bem-sucedido.
Seu agente não pode alcançar um cluster que você não vinculou
A política base abrange apenas o cluster vinculado. Para acessar outro cluster MongoDB , adicione-o como um destino de saída na porta 27017. Para saber mais, consulte o guia Gerenciar políticas de saída de rede.
Seu agente não usa a memória, mas ainda não consegue acessar o Atlas
Desativar a memória não remove o requisito do Atlas . Se o seu espaço de trabalho se conectar ao Atlas , vincule o cluster conforme descrito neste guia.
Próximos passos
Depois de vincular o cluster, permita os outros destinos que o agente chama, como APIs do fornecedor LLM. Para saber como, consulte o tutorial Introdução à saída de rede.