Configurar Recursos do Atlas

Esquema de arquivo de perfil

O arquivo ~/.agentengine/atlas.json tem a seguinte estrutura:

{
  "version": 1,
  "profiles": {
    "default": {
      "base_url": "https://cloud.mongodb.com",
      "client_id": "<service-account-client-id>",
      "client_secret": "<service-account-client-secret>"
    }
  }
}

Você pode adicionar vários perfis nomeados para usar com diferentes ambientes ou contas de serviço do Atlas . Para usar um perfil não padrão, passe o sinalizador --profile conforme mostrado no exemplo a seguir:

agentengine atlas setup --profile <profile-name>

Variáveis de ambiente

Você pode fornecer ou substituir credenciais usando as seguintes variáveis de ambiente sem editar o arquivo de perfil diretamente:

O comando resolve as credenciais na seguinte ordem:

1. MONGODB_ATLAS_ACCESS_TOKEN, se definido

2. MONGODB_ATLAS_CLIENT_ID e MONGODB_ATLAS_CLIENT_SECRET, se ambos estiverem definidos

3. Perfil armazenado em ~/.agentengine/atlas.json

4. Solicitação interativa, se um terminal estiver conectado

Sinalizadores de comando

Fluxo interativo

Quando você executa o agentengine atlas setup, a CLI orienta você nas seguintes etapas:

1. Organização: Lista suas organizações do Atlas com um menu numerado. Selecione uma organização existente ou crie uma nova.

2. Projeto: lista os projetos na organização selecionada. Selecione um projeto existente ou crie um novo. Novos projetos recebem uma conta de serviço com escopo de projeto.

3. Cluster: lista os clusters no projeto selecionado. Selecione um cluster existente ou, se sua conta de serviço tiver permissões de criador de cluster, crie um novo cluster.

4. Usuário do banco de dados: cria um usuário de banco de dados com as credenciais que o agente usa para se conectar ao cluster.

5. Chave de API Voyage AI: provisiona uma chave de API do Voyage AI para os recursos de memória do agente.

6. Segredos: Salva MONGODB_URI e VOYAGE_API_KEY como segredos do Atlas Agent Engine para que os agentes implementados possam se conectar ao seu Atlas cluster e à IA do Voyage.

7. lista de acesso IP: adiciona os endereços IP do plano de dados do Atlas Agent Engine à lista de acesso IP do cluster.

Após a conclusão do fluxo, a CLI exibe o status de provisionamento de cada recurso.

Configuração automática

Para criar todos os recursos do Atlas automaticamente sem prompts interativos, passe o sinalizador --yes para o comando agentengine atlas setup. Quando o espaço de trabalho não tiver sido inicializado, o comando agentengine atlas setup --yes executa agentengine init primeiro e, em seguida, cria os seguintes recursos usando nomes baseados na ID do espaço de trabalho:

• Cluster do Atlas

• Usuário do banco de dados nomeado agent-engine-<workspace-id>

• Chave API Voyage chamada agent-engine-<workspace-id>

A configuração automática é interrompida quando encontra metadados salvos ou recursos Atlas existentes que correspondam a esses nomes gerados. Para criar um novo conjunto de recursos, remova os recursos conflitantes e passe --force.

A configuração automática utiliza o projeto Atlas salvo quando presente. Caso contrário, é necessária exatamente uma organização Atlas visível e um projeto Atlas visível para prosseguir sem prompts.

Você pode substituir a configuração de cluster padrão definindo as seguintes variáveis de ambiente antes de executar o comando:

Status da configuração

O comando agentengine atlas setup exibe o status de provisionamento de todos os recursos no final de cada execução. Para verificar novamente o estado atual ou executar novamente o fluxo de configuração completo, execute o seguinte comando:

agentengine atlas setup --force

Listar perfis

Use o seguinte comando para retornar os perfis salvos do arquivo ~/.agentengine/atlas.json:

agentengine atlas profile list --json

O exemplo a seguir mostra o formato de saída:

{
  "schema_version": "1",
  "status": "ok",
  "profiles": [
    {"name": "default", "base_url": "https://cloud.mongodb.com"}
  ]
}

Verificar um perfil

Use o comando a seguir para validar as credenciais da conta de serviço e retornar organizações e projetos acessíveis:

agentengine atlas profile verify --json --input -

Passe um objeto de solicitação JSON por stdin passando - para o sinalizador --input. O comando retorna o nome do perfil selecionado, URL base e listas de organizações e projetos acessíveis. A saída não inclui tokens de acesso e segredos.

Salvar um perfil

Use o seguinte comando para persistir a organização e o projeto selecionados do Atlas no contexto do espaço de trabalho:

agentengine atlas profile save [--context <name>] [--workspace <name>] --json --input -

Passe um objeto de solicitação JSON por stdin passando - para o sinalizador --input. O comando salva o ambiente, perfil, organização e projeto do Atlas no arquivo .agentengine/state.json do espaço de trabalho. Se a organização e a seleção do projeto não forem alteradas, o comando preservará qualquer cluster existente, usuário de banco de dados e seleções de chave da API Voyage.

Listar clusters

Use o comando abaixo para retornar os clusters no projeto Atlas salvo:

agentengine atlas cluster list [--context <name>] [--workspace <name>] --json

O exemplo a seguir mostra o formato de saída:

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "clusters": [
    {
      "name": "my-cluster",
      "kind": "REPLICASET",
      "state_name": "IDLE",
      "is_flex": false
    }
  ],
  "create_defaults": {
    "name": "my-agent",
    "provider": "AWS",
    "region": "US_EAST_1",
    "tier": "FLEX",
    "label": "Flex"
  },
  "can_create": true,
  "warnings": []
}

O objeto create_defaults fornece a configuração sugerida para um novo cluster. O campo can_create indica se a conta de serviço tem permissão para criar um cluster no projeto selecionado.

Salvar um cluster

Use o comando a seguir para selecionar um cluster existente ou criar um novo:

agentengine atlas cluster save [--context <name>] [--workspace <name>] --json --input -

Passe um objeto de solicitação JSON por stdin passando - para o sinalizador --input. Para selecionar um cluster existente:

{"mode": "existing", "name": "my-cluster"}

Para criar um novo cluster:

{
  "mode": "create",
  "name": "my-agent",
  "provider": "AWS",
  "region": "US_EAST_1",
  "tier": "FLEX"
}

Se você omitir o campo name no modo de criação, a CLI gerará um nome a partir do ID do espaço de trabalho. A criação de um cluster solicita o provisionamento no Atlas e retorna imediatamente. O Atlas pode levar alguns minutos para concluir o provisionamento do cluster.

Listar usuários do banco de dados

Utilize o seguinte comando para retornar os usuários do banco de dados no projeto Atlas salvo:

agentengine atlas database-user list [--context <name>] [--workspace <name>] --json

O exemplo a seguir mostra o formato de saída:

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "users": [
    {"username": "my-user", "database_name": "admin"}
  ],
  "create_defaults": {"username": "agent-engine-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

Quando o comando encontra um usuário existente cujo nome corresponde ao padrão gerado para o espaço de trabalho, ele salva esse usuário automaticamente no arquivo .agentengine/state.json. Isso mantém o estado local atualizado quando os recursos foram provisionados fora da sessão atual.

Salvar um utilizador de banco de dados

Use o seguinte comando para selecionar um usuário existente ou criar um novo:

agentengine atlas database-user save [--context <name>] [--workspace <name>] --json --input -

Passe um objeto de solicitação JSON por stdin passando - para o sinalizador --input. Para selecionar um usuário existente, inclua a senha conforme mostrado no exemplo a seguir:

{"mode": "existing", "username": "my-user", "password": "my-password"}

Para criar um novo usuário, passe o seguinte objeto:

{"mode": "create", "username": "my-user"}

Se você omitir o campo username no modo de criação, a CLI gerará um nome a partir do ID do espaço de trabalho. Para novos usuários, a CLI gera uma senha automaticamente. A senha gerada não está incluída na saída do comando.

Após salvar, o comando grava MONGODB_URI como um segredo do Atlas Agent Engine no escopo do projeto. Ele não escreve em um arquivo local.

Listar chaves de API do Voyage

Use o comando a seguir para retornar as chaves da API do Voyage no projeto Atlas salvo:

agentengine atlas voyage-api-key list [--context <name>] [--workspace <name>] --json

O exemplo a seguir mostra o formato de saída:

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "keys": [
    {
      "id": "key-id",
      "name": "agent-engine-<workspace-id>",
      "masked_secret": "voy...xxxx"
    }
  ],
  "create_defaults": {"name": "agent-engine-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

Quando o comando encontra uma chave existente cujo nome corresponde ao padrão gerado para o espaço de trabalho, ele salva automaticamente essa chave no arquivo .agentengine/state.json.

Salvar uma chave API do Voyage

Use o seguinte comando para selecionar uma chave existente ou criar uma nova:

agentengine atlas voyage-api-key save [--context <name>] [--workspace <name>] --json --input -

Passe um objeto JSON por stdin passando - para o sinalizador --input. Para selecionar uma chave existente, use o seguinte formato:

{"mode": "existing", "name": "my-key", "value": "<api-key-value>"}

Para criar uma nova chave, use o seguinte formato:

{"mode": "create", "name": "my-key"}

Se você omitir o campo name no modo de criação, a CLI gerará um nome a partir do ID do espaço de trabalho. Quando você cria uma chave, a CLI usa diretamente o valor secreto retornado pelo Atlas.

Após salvar, o comando grava VOYAGE_API_KEY como um segredo do Atlas Agent Engine no escopo do projeto. Ele não escreve em um arquivo local. Para ambientes Atlas inferiores, o comando também escreve a variável VOYAGE_URL da mesma maneira.