Introdução ao Atlas Agent Engine

Instale o agentengine CLI.

Inicie sessão no Atlas Agent Engine e baixe a CLI na página de download da CLI. O menu suspenso Version é pré-preenchido com a versão CLI mais recente, e o menu suspenso Platform é pré-preenchido com seu sistema operacional detectado.

Clique no botão Download for <your platform>. Salve o valor da checksum SHA-256 exibido na página para uso na etapa seguinte.

Conclua a instalação da CLI.

No seu terminal, navegue até o diretório de downloads e execute o seguinte comando:

shasum -a 256 agentengine

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.

Execute os seguintes comandos para marcar o binário como executável e movê-lo para o diretório ~/.local/bin:

chmod +x ./agentengine
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.

Para saber mais, consulte Instalar a CLI agentengine.

Inicie sessão no Atlas Agent Engine.

Execute o seguinte comando para autenticar a CLI:

agentengine auth login

Siga o fluxo de login baseado no navegador para concluir a autenticação.

Crie um projeto de agente .

Execute o seguinte comando para estruturar um projeto de agente Olá, mundo:

agentengine create

Quando solicitado pela CLI, escolha os seguintes valores:

• Modelo: Olá, agente mundial

• Provedor de LLM: Athropic Class

• Chave de API: sua chave de API antrófica

• Habilitar memória: não

O comando cria um diretório raiz do projeto que contém um arquivo de configuração project-config.yaml e um diretório agents/. Os arquivos do seu agente, que incluem o arquivo de configuração agent.yaml, um arquivo .env com sua chave de API e um arquivo pyproject.toml, estão em um subdiretório de agents/. O exemplo a seguir mostra a estrutura que o comando cria:

my-project/
├── project-config.yaml
└── agents/
    └── my-agent/
        ├── agent.yaml
        ├── pyproject.toml
        ├── .env
        └── src/

Execute todos os comandos agentengine subsequentes do seu diretório de agente , que é my-agent/ neste exemplo.

Execute o agente localmente.

O desenvolvimento local requer acesso à imagem da base do executor hospedada no registro de imagens de contêiner do MongoDB. A CLI extrai a imagem usando sua sessão agentengine auth login , então você não precisa de um login de registro separado.

1. Navegue até o diretório do agente e execute o seguinte comando para iniciar o ambiente de desenvolvimento local:

   agentengine dev up

   A CLI cria uma imagem Docker e inicia a pilha de agente completa. Quando a pilha é iniciada com sucesso, a saída do comando é semelhante ao seguinte:

   ◆ Workspace  <your organization>  /  Default Project  /  <your project>
   ✓ Created .agentengine/docker-compose.dev.yml
   ✓ Created .agentengine/Dockerfile.dev
   ✓ Created .agentengine/Dockerfile.dev.dockerignore
   ✓ Created .agentengine/dev-entrypoint.py
   ✓ Created .agentengine/entrypoint.py
   ✓ Created .devcontainer/devcontainer.json
   ✓ Reused existing .agentengineignore
   [+] Building 1.6s (17/17) FINISHED
   [+] up 5/5
    ✔ Container <your-project>-mongodb-1  Healthy
    ✔ Container <your-project>-oe-1       Healthy
    ✔ Container <your-project>-app-1      Started
   ✓ Stack running (hot-reload)
     oe       http://localhost:51331
     mongo    mongodb://localhost:51333
     ui       http://localhost:3000
     Invoke:  curl -X POST 'http://localhost:3000/invoke' \
                -H 'Content-Type: application/json' \
                -d '{"message": "Hello"}'
     Next:    Open VS Code and run "Dev Containers: Reopen in Container"
              for editing and debugging inside the running app container
     Restart: from this workspace dir, run
              agentengine dev restart
     Logs:    agentengine dev logs
     Stop:    agentengine dev stop
     Clean:   agentengine dev clean

   Quando todos os serviços estiverem prontos, abra o URL http://localhost:3000 em seu navegador para conversar por chat com seu agente.

   Observação

   A interface do usuário pode ser executada em uma porta diferente da porta padrão 3000. Para visualizar sua URL, marque o campo ui na saída do comando agentengine dev up.

   O exemplo a seguir mostra uma troca bem-sucedida com seu agente:

   

   clique para ampliar

2. Para interromper o ambiente local, execute o seguinte comando:

   agentengine dev stop

Registre-se na plataforma.

Execute o seguinte comando para registrar seu projeto com o Atlas Agent Engine antes de implementá-lo:

agentengine init

Este comando vincula seu projeto local ao Mecanismo do Agente Atlas e cria um espaço de trabalho para o seu agente.

Configure os recursos do Atlas .

O Atlas Agent Engine requer um cluster Atlas para armazenar o estado de execução, os pontos de verificação e o histórico. A CLI é compatível apenas com credenciais da conta de serviço do Atlas . Logins de conta de usuário do Atlas e chaves públicas e privadas da API legado do Atlas não são suportados.

1. Na UI do Atlas , crie ou selecione uma conta de serviço:

   1. Abra o projeto Atlas que deseja utilizar.

   2. Vá para Aplicativos na seção Identidade & Acesse o menu e crie ou selecione uma conta de serviço.

   3. Conceda à conta de serviço a permissão de Proprietário do Projeto. Para saber por que essa função é necessária, consulte Funções do Atlas para gerenciamento de projetos.

2. Execute o seguinte comando para configurar e provisionar um cluster:

   agentengine atlas setup

   Quando solicitado, cliente o ID e o segredo da sua conta de serviço do Atlas . O CLI provisiona um cluster, configura o acesso à rede e armazena o MONGODB_URI como um segredo de plataforma. Para saber mais sobre os recursos do Atlas , consulte Configurar recursos do Atlas .

Definir segredos de nuvem.

Seu agente implementado requer segredos para invocar o LLM e se conectar ao Atlas.

Execute o seguinte comando para definir a chave de API antrópico. A CLI solicita o valor.

agentengine secret set ANTHROPIC_API_KEY

Para saber mais sobre o gerenciamento de segredos,consulte Provision Cloud Secrets.

Construa e implemente o agente.

Execute o seguinte comando para construir a imagem do agente e implementá-la em uma etapa:

agentengine deploy --auto

O comando agrupa seu código de agente , inicia um tarefa de compilação remota e monitora a implantação que a compilação aciona. A construção leva de 5 a 10 minutos e a implantação leva mais 5 a 10 minutos. Durante a implantação, o resultado pode mostrar Agent Sandbox: waiting e Tool Sandbox: waiting por vários minutos. Quando a implantação é bem-sucedida, a saída do comando é semelhante à seguinte:

Waiting for auto-deploy to start...
✓ Auto-deploy started (deployment_id: <deployment-id>)
✓ Deployment succeeded
  version: v0.1.0
  components:
    Orchestration Engine      ready (2 replicas)
    Agent Sandbox             ready (3 replicas)
    Tool Sandbox              ready (4 replicas)
  url: https://agentengine.mongodb.com/project/<project-id>/deployments/<deployment-id>

Seu agente agora está em execução no MongoDB Atlas Agent Engine.

O sinalizador --auto se aplica somente a projetos de agente único. Para construir e implantar em etapas separadas ou para implantar uma compilação específica, execute agentengine build e, em seguida, agentengine deploy. Para saber mais, consulte Iniciar uma implementação.