Visão geral
Este tutorial mostra como instalar e autenticar sua conta com o MongoDB Atlas Agent Engine. Você verificará as dependências do sistema, instalará a CLI agentengine, verificará a imagem da base do executor e autenticará sua conta no Atlas Agent Engine API Gateway.
Pré-requisitos
Certifique-se de ter os seguintes componentes instalados e configurados antes de iniciar este tutorial:
Pré-requisitos | Notas |
|---|---|
Sistema operacional suportado | Os seguintes sistemas operacionais são suportados:
|
Mecanismo de contêiner | Use o Docker Desktop ou o Docker Engine com o Docker Compose v2 em execução ativamente em sua máquina. O Atlas Agent Engine oferece suporte ao Podman da melhor maneira possível, e a CLI imprime um aviso de compatibilidade quando detecta a ferramenta |
Use a versão 3.11 ou posterior. | |
Cluster MongoDB | O agente implementado usa esse cluster, portanto, você deve recuperar sua string de conexão. O teste local inicia seu próprio container MongoDB . |
Acesso à rede | Sua rede deve permitir acesso de saída aos seguintes hosts:
A CLI imprime o host de registro de contêiner quando você executa o comando Para redes com restrição de ar ou de saída, você pode obter as imagens binárias e de tempo de execução do agente CLI dos hosts que você controla. Para saber como configurar uma fonte de artefato personalizada, consulte Usar uma fonte de artefato personalizada. |
Use uma fonte de artefato personalizada
Você pode configurar a CLI agentengine para baixar o binário e extrair imagens de tempo de execução do agente de seus próprios hosts em vez do registro hospedado no MongoDB. Execute agentengine agent source setup para gerar um arquivo source.yaml ou execute agentengine agent source template para escrever um modelo comentado que você pode editar. Execute estes comandos após instalar o agentengine CLI.
Por padrão, a CLI lê source.yaml de ~/.agentengine/source.yaml. Para usar um local diferente, defina a variável de ambiente AGENTENGINE_IMAGE_SOURCE_FILE para o caminho do arquivo.
Exporte AGENTENGINE_IMAGE_SOURCE=custom para rotear agentengine dev up e agentengine self-update para seu host personalizado. A seguinte amostra source.yaml espelha o binário CLI e as imagens de tempo de execução do agente :
base: internal release: type: static url: https://artifactory.example.com/agentic-cli/manifest.json registry: prefix: artifactory.example.com/acme-docker
O bloco release direciona as transferências binárias da CLI para o seu host, e o bloco registry.prefix direciona as extrações de imagens do agente para o seu registro. Se você espelhar apenas um deles, a CLI usará a origem base, internal por padrão, para o outro.
Com type: static, o manifesto em release.url deve corresponder à seguinte estrutura, com uma entrada em assets para cada sistema operacional e arquitetura. Caso contrário, agentengine self-update falha e a CLI não exibe notificações de atualização.
{ "releases": [ { "version": "1.4.2", "assets": [ { "os": "darwin", "arch": "arm64", "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_darwin_arm64", "sha256": "9f2b...e1" } ] } ] }
Para ler as versões de uma API do GitHub Enterprise em vez de um manifesto, defina release.type como github e release.url como o ponto de extremidade da API, como https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releases.
Se o registro de imagem exigir autenticação, faça login antes de executar agentengine dev up. Por exemplo, execute docker login <registry> ou, para Amazon ECR, execute o seguinte comando:
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com
Instalar a CLI agentengine
O agentengine CLI é a principal ferramenta para o desenvolvimento local com o MongoDB Atlas Agent Engine. Ele gera a configuração do Docker Compose necessária para executar os três serviços do seu agente localmente.
As seguintes etapas descrevem como baixar a CLI a partir da UI do Atlas Agent Engine.
Abra a página Instalar CLI.
Inicie sessão no Atlas Agent Engine e baixe a CLI na página de download da CLI.
A página exibe um menu suspenso Version, que é pré-preenchido com a versão mais recente da CLI. Ele também exibe um menu suspenso Platform pré-preenchido com seu sistema operacional detectado. Para alterar esses valores padrão, escolha uma versão ou plataforma diferente nos seletores suspensos.
Verifique o download.
No seu terminal, navegue até o diretório de downloads. Selecione a aba correspondente ao seu sistema operacional e execute o seguinte comando:
shasum -a 256 agentengine
certutil -hashfile agentengine.exe SHA256
A saída deve corresponder ao valor SHA-256 que você salvou. Se os valores não corresponderem, exclua o binário e baixe-o novamente.
Adicione o binário ao seu PATH.
Selecione a guia correspondente ao seu sistema operacional para visualizar as instruções de adição do binário ao seu PATH.
No seu diretório de downloads, execute o seguinte comando:
mkdir -p ~/.local/bin mv agentengine ~/.local/bin/agentengine
Confirme que ~/.local/bin está em seu PATH. Instalar o binário em um diretório gravável pelo usuário permite que você execute o comando agentengine self-update sem usar o comando sudo.
Mova o arquivo .exe para um diretório que já esteja em seu PATH ou adicione seu diretório para System Properties -> Environment
Variables -> Path na GUI do Windows.
Para usar comandos agentengine, renomeie o binário para agentengine.exe.
Verifique a instalação.
Confirme se a CLI está instalada verificando sua versão:
agentengine version
A saída se assemelha ao seguinte:
0.1.94-alpha (commit: <hash>) image registry: ECR runner-base: <registry-host>/runner-base:0.1.94-alpha runner-base-typescript-langgraph: <registry-host>/runner-base-typescript-langgraph:0.1.94-alpha playground-ui: <registry-host>/playground-ui:0.1.94-alpha orchestrator: <registry-host>/orchestration-engine:<version> memory-server: <registry-host>/memory-server:<version>
Para saber como atualizar uma CLI instalada para uma versão mais recente, consulte Atualizar a CLI.
Verificar a imagem da base do executor
A imagem run-base é a imagem do container que o Atlas Agent Engine usa para executar cada um dos três serviços do seu agente localmente. Se o Docker não puder extrair essa imagem quando você executar um agente pela primeira vez, seu agente não iniciará. A verificação da imagem base do Docker permite detectar e corrigir quaisquer problemas de rede antes de executar o projeto do agente . A verificação da imagem da base do executor é opcional, mas recomendada.
O desenvolvimento local extrai a imagem da base do executor do registro de imagens de contêiner hospedado do MongoDB. Você não precisa de acesso ao GitHub ou de um login de registro separado. A CLI usa sua sessão agentengine auth login para recuperar a imagem e imprime o host de registro quando você executa o comando agentengine dev up.
Autentique no registro de imagem da plataforma.
Execute o seguinte comando para registrar sua instalação local do Docker no registro de imagem da plataforma:
agentengine dev login
O comando agentengine dev up executa esse fluxo automaticamente, portanto, essa etapa só é necessária quando você extrai uma imagem diretamente.
Puxe a imagem da base do executor.
Execute o seguinte comando para extrair a imagem da base do executor e substitua <runner-base-image> pelo valor que você copiou da saída agentengine version:
docker pull <runner-base-image>
Um pull bem-sucedido termina com uma linha Status: que lê Downloaded newer image ou Image is up to date.
Autentique sua conta
O comando agentengine auth login inicia um fluxo de login do OIDC baseado em navegador no gateway de API do Atlas Agent Engine e salva o estado de autenticação local para futuros comandos de CLI.
Observação
Delegação do Atlas OAuth
Quando você faz login no Atlas Agent Engine, a plataforma recupera automaticamente suas atribuições de função do Atlas e determina quais organizações e projetos você pode acessar. A plataforma usa o servidor Atlas OAuth 2.1 App Connections para autorizar o acesso ao Atlas.
Faça login no Atlas Agent Engine.
No seu terminal, execute o seguinte comando:
agentengine auth login
Por padrão, isso abre um navegador no gateway de API de produção em https://agentengine.mongodb.com. Você pode passar --base-url para o comando para direcionar um gateway diferente ou passar --no-browser para imprimir a URL de login sem abrir um navegador. O seguinte código mostra o formato do comando:
agentengine auth login [--base-url <url>] [--no-browser] [--timeout <duration>]
Depois de concluir o login, a CLI lê suas associações de projeto a partir da API e persiste o ID do projeto selecionado project_id, bem como seu token de autenticação.
Selecione um projeto.
Se sua conta pertencer a um único projeto, ela será selecionada automaticamente. Se sua conta pertencer a vários projetos, a CLI solicitará que você escolha um interativamente. Se você não tiver uma preferência, selecione seu projeto padrão. A CLI salva sua seleção como um padrão que você pode substituir pelo sinalizador --project-id.
Verifique seu status de autenticação.
Para verificar se sua autenticação foi bem-sucedida, execute o seguinte comando:
agentengine auth status
Este comando imprime seu contexto de autenticação local atual sem entrar em contato com a plataforma, e sua saída reflete o estado de login salvo no disco. Você pode passar o sinalizador --json para o comando para gerar um objeto JSON com campos auth, command_defaults e directory_context separados.
Até que você registre um diretório de agente executando o comando agentengine init, o campo Directory context relata none found. Um login bem-sucedido ainda exibe sua conta, URL base e organização e projeto padrão.
Dica
Se o seu token de autenticação expirar, saia e faça login novamente para atualizá-lo:
agentengine auth logout agentengine auth login
Próximos passos
Após instalar e autenticar sua conta com o MongoDB Atlas Agent Engine, você pode criar um projeto. Para saber como executar as próximas etapas, consulte o guia Criar um projeto.