Configurar recursos de Atlas

Esquema del archivo de perfil

El archivo ~/.agentengine/atlas.json tiene la siguiente estructura:

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

Puede agregar varios perfiles con nombre para usarlos con diferentes entornos de Atlas o cuentas de servicio. Para usar un perfil que no sea el predeterminado, pase el indicador --profile como se muestra en el siguiente ejemplo:

agentengine atlas setup --profile <profile-name>

Variables de entorno

Puede proporcionar o sobrescribir credenciales utilizando las siguientes variables de entorno sin editar directamente el archivo de perfil:

El comando resuelve las credenciales en el siguiente orden:

1. MONGODB_ATLAS_ACCESS_TOKEN, si está configurado

2. MONGODB_ATLAS_CLIENT_ID y MONGODB_ATLAS_CLIENT_SECRET, si ambos están configurados

3. Perfil almacenado en ~/.agentengine/atlas.json

4. Mensaje interactivo, si hay un terminal conectado.

Banderas de comando

Flujo interactivo

Cuando ejecutas agentengine atlas setup, la interfaz de línea de comandos te guía a través de los siguientes pasos:

1. Organización: Muestra tus organizaciones de Atlas en un menú numerado. Selecciona una organización existente o crea una nueva.

2. Proyecto: Muestra los proyectos de la organización seleccionada. Seleccione un proyecto existente o cree uno nuevo. Los proyectos nuevos reciben una cuenta de servicio con alcance de proyecto.

3. Clúster: Muestra los clústeres del proyecto seleccionado. Seleccione un clúster existente o, si su cuenta de servicio tiene permisos de creador de clústeres, cree uno nuevo.

4. Usuario de la base de datos: Crea un usuario de la base de datos con las credenciales que el agente utiliza para conectarse al clúster.

5. Clave API de Voyage AI: Proporciona una clave API de Voyage AI para las funciones de memoria del agente.

6. Secretos: Guarda MONGODB_URI y VOYAGE_API_KEY como secretos de Atlas Agent Engine para que los agentes implementados puedan conectarse a su clúster de Atlas y a Voyage AI.

7. Lista de acceso IP: Agrega las direcciones IP del plano de datos de Atlas Agent Engine a la lista de acceso IP del clúster.

Una vez finalizado el proceso, la interfaz de línea de comandos (CLI) muestra el estado de aprovisionamiento de cada recurso.

Configuración automática

Para crear automáticamente todos los recursos de Atlas sin indicaciones interactivas, pase el indicador --yes al comando agentengine atlas setup. Cuando el espacio de trabajo no se ha inicializado, el comando agentengine atlas setup --yes ejecuta primero agentengine init y luego crea los siguientes recursos utilizando nombres basados ​​en el ID del espacio de trabajo:

• Atlas cluster

• Usuario de la base de datos llamado agent-engine-<workspace-id>

• Clave API de Voyage llamada agent-engine-<workspace-id>

La configuración automática se detiene cuando encuentra metadatos guardados o recursos de Atlas existentes que coinciden con los nombres generados. Para crear un nuevo conjunto de recursos, elimine los recursos conflictivos y pase --force.

La configuración automática utiliza el proyecto de Atlas guardado, si está presente. De lo contrario, requiere exactamente una organización de Atlas visible y un proyecto de Atlas visible para continuar sin necesidad de indicaciones.

Puede anular la configuración predeterminada del clúster estableciendo las siguientes variables de entorno antes de ejecutar el comando:

Estado de configuración

El comando agentengine atlas setup muestra el estado de aprovisionamiento de todos los recursos al final de cada ejecución. Para volver a comprobar el estado actual o volver a ejecutar el flujo de configuración completo, ejecute el siguiente comando:

agentengine atlas setup --force

Lista de perfiles

Utilice el siguiente comando para devolver los perfiles guardados del archivo ~/.agentengine/atlas.json:

agentengine atlas profile list --json

El siguiente ejemplo muestra el formato de salida:

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

Verificar un perfil

Utilice el siguiente comando para validar las credenciales de la cuenta de servicio y obtener las organizaciones y proyectos accesibles:

agentengine atlas profile verify --json --input -

Para pasar un objeto de solicitud JSON a través de stdin, utilice - como parámetro para --input. El comando devuelve el nombre del perfil seleccionado, la URL base y listas de organizaciones y proyectos accesibles. La salida no incluye tokens de acceso ni secretos.

Guardar un perfil

Utilice el siguiente comando para guardar la organización y el proyecto de Atlas seleccionados en el contexto del espacio de trabajo:

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

Se pasa un objeto de solicitud JSON a través de stdin mediante el parámetro - en el indicador --input. El comando guarda el entorno, el perfil, la organización y el proyecto de Atlas en el archivo .agentengine/state.json del espacio de trabajo. Si la selección de organización y proyecto no cambia, el comando conserva las selecciones existentes de clúster, usuario de base de datos y clave API de Voyage.

Listar clústeres

Utilice el siguiente comando para devolver los clústeres del proyecto Atlas guardado:

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

El siguiente ejemplo muestra el formato de salida:

{
  "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": []
}

El objeto create_defaults proporciona la configuración sugerida para un nuevo clúster. El campo can_create indica si la cuenta de servicio tiene permiso para crear un clúster en el proyecto seleccionado.

Guardar un clúster

Utilice el siguiente comando para seleccionar un clúster existente o crear uno nuevo:

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

Pase un objeto de solicitud JSON a través de stdin pasando - al indicador --input. Para seleccionar un clúster existente:

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

Para crear un nuevo clúster:

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

Si omite el campo name en el modo de creación, la CLI genera un nombre a partir del ID del espacio de trabajo. La creación de un clúster solicita el aprovisionamiento en Atlas y finaliza inmediatamente. Atlas puede tardar varios minutos en completar el aprovisionamiento del clúster.

Lista de usuarios de la base de datos

Utilice el siguiente comando para obtener los usuarios de la base de datos en el proyecto Atlas guardado:

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

El siguiente ejemplo muestra el formato de salida:

{
  "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": []
}

Cuando el comando encuentra un usuario existente cuyo nombre coincide con el predeterminado generado para el espacio de trabajo, lo guarda automáticamente en el archivo .agentengine/state.json. Esto mantiene actualizado el estado local cuando se aprovisionan recursos fuera de la sesión actual.

Guardar un usuario de la base de datos

Utilice el siguiente comando para seleccionar un usuario existente o crear uno nuevo:

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

Pase un objeto de solicitud JSON a través de stdin pasando - al indicador --input. Para seleccionar un usuario existente, incluya la contraseña como se muestra en el siguiente ejemplo:

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

Para crear un nuevo usuario, pase el siguiente objeto:

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

Si omite el campo username en el modo de creación, la CLI genera un nombre a partir del ID del espacio de trabajo. Para los nuevos usuarios, la CLI genera una contraseña automáticamente. La contraseña generada no se incluye en la salida del comando.

Tras guardar, el comando escribe MONGODB_URI como un secreto de Atlas Agent Engine con ámbito de proyecto. No escribe en un archivo local.

Lista de claves API de Voyage

Utilice el siguiente comando para devolver las claves API de Voyage en el proyecto Atlas guardado:

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

El siguiente ejemplo muestra el formato de salida:

{
  "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": []
}

Cuando el comando encuentra una clave existente cuyo nombre coincide con el valor predeterminado generado para el espacio de trabajo, guarda automáticamente esa clave en el archivo .agentengine/state.json.

Clave API de Save a Voyage

Utilice el siguiente comando para seleccionar una clave existente o crear una nueva:

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

Pase un objeto JSON a través de stdin pasando - al indicador --input. Para seleccionar una clave existente, utilice el siguiente formato:

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

Para crear una nueva clave, utilice el siguiente formato:

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

Si omite el campo name en el modo de creación, la CLI genera un nombre a partir del ID del espacio de trabajo. Al crear una clave, la CLI utiliza directamente el valor secreto devuelto por Atlas.

Tras guardar, el comando escribe VOYAGE_API_KEY como un secreto de Atlas Agent Engine con ámbito de proyecto. No escribe en un archivo local. Para entornos Atlas más antiguos, el comando también escribe la variable VOYAGE_URL de la misma manera.