Overview
Este tutorial te muestra cómo instalar y autenticar tu cuenta con el Motor de Agentes Atlas de MongoDB. Verificarás las dependencias de tu sistema, instalarás la CLI agentengine, verificarás la imagen base del ejecutor y autenticarás tu cuenta en la puerta de enlace API del Motor de Agentes Atlas.
Requisitos previos
Asegúrese de tener instalados y configurados los siguientes componentes antes de comenzar este tutorial:
Requisito previo | notas |
|---|---|
Sistema operativo compatible | Se admiten los siguientes sistemas operativos:
|
Motor de contenedores | Utilice Docker Desktop o Docker Engine con Docker Compose v2 ejecutándose activamente en su máquina. El motor de agentes de Atlas admite Podman en la medida de lo posible, y la CLI muestra un aviso de compatibilidad cuando detecta la herramienta |
Usa la versión 3.11 o posterior. | |
clúster de MongoDB | El agente desplegado utiliza este clúster, por lo que debe obtener su cadena de conexión. Las pruebas locales inician su propio contenedor de MongoDB. |
Acceso a la red | Su red debe permitir el acceso saliente a los siguientes hosts:
La interfaz de línea de comandos (CLI) muestra el host del registro de contenedores al ejecutar el comando Para redes aisladas o con acceso restringido, puede obtener el binario de la CLI y las imágenes de tiempo de ejecución del agente desde hosts que usted controle. Para obtener información sobre cómo configurar un origen de artefactos personalizado, consulte la sección "Usar un origen de artefactos personalizado". |
Utilice una fuente de artefactos personalizada
Puedes configurar la CLI agentengine para descargar el binario y obtener las imágenes de tiempo de ejecución del agente desde tus propios hosts en lugar del registro alojado por MongoDB. Ejecuta agentengine agent source setup para generar un archivo source.yaml o agentengine agent source template para escribir una plantilla comentada que puedes editar. Ejecuta estos comandos después de instalar la CLI agentengine.
Por defecto, la CLI lee source.yaml desde ~/.agentengine/source.yaml. Para usar una ubicación diferente, configure la variable de entorno AGENTENGINE_IMAGE_SOURCE_FILE con la ruta del archivo.
Exporta AGENTENGINE_IMAGE_SOURCE=custom para enrutar agentengine dev up y agentengine self-update a tu host personalizado. El siguiente ejemplo source.yaml refleja tanto el binario de la CLI como las imágenes de tiempo de ejecución del agente:
base: internal release: type: static url: https://artifactory.example.com/agentic-cli/manifest.json registry: prefix: artifactory.example.com/acme-docker
El bloque release dirige las descargas de binarios de la CLI a su host, y el bloque registry.prefix dirige las descargas de imágenes de tiempo de ejecución del agente a su registro. Si solo replica uno de estos, la CLI utiliza la fuente base (por defecto, internal) para el otro.
Con type: static, el manifiesto en release.url debe coincidir con la siguiente estructura, con una entrada en assets para cada sistema operativo y arquitectura. De lo contrario, agentengine self-update falla y la interfaz de línea de comandos no muestra notificaciones de actualización.
{ "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 leer versiones desde una API de versiones de GitHub Enterprise en lugar de un manifiesto, configure release.type en github y release.url en el punto final de la API, como https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releases.
Si su registro de imágenes requiere autenticación, inicie sesión antes de ejecutar agentengine dev up. Por ejemplo, ejecute docker login <registry> o, para Amazon ECR, ejecute el siguiente comando:
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com
Instale la CLI agentengine
La interfaz de línea de comandos agentengine es la herramienta principal para el desarrollo local con MongoDB Atlas Agent Engine. Genera la configuración de Docker Compose necesaria para ejecutar localmente los tres servicios del agente.
Los siguientes pasos describen cómo descargar la interfaz de línea de comandos (CLI) desde la interfaz de usuario de Atlas Agent Engine.
Abra la página de instalación de la CLI.
Inicie sesión en Atlas Agent Engine y, a continuación, descargue la interfaz de línea de comandos (CLI) desde la página de descarga de la CLI.
La página muestra un menú desplegable Version, que viene precargado con la última versión de la CLI. También muestra un menú desplegable Platform precargado con el sistema operativo detectado. Para cambiar estos valores predeterminados, seleccione una versión o plataforma diferente en los menús desplegables.
Verifica la descarga.
En tu terminal, navega hasta tu directorio de descargas. Selecciona la pestaña correspondiente a tu sistema operativo y ejecuta el siguiente comando:
shasum -a 256 agentengine
certutil -hashfile agentengine.exe SHA256
El resultado debe coincidir con el valor SHA-256 que guardaste. Si los valores no coinciden, elimina el archivo binario y descárgalo de nuevo.
Agregue el binario a su PATH.
Seleccione la pestaña correspondiente a su sistema operativo para ver las instrucciones para agregar el binario a su PATH.
Desde tu directorio de descargas, ejecuta el siguiente comando:
mkdir -p ~/.local/bin mv agentengine ~/.local/bin/agentengine
Confirma que ~/.local/bin está en tu PATH. Instalar el binario en un directorio con permisos de escritura para el usuario te permite ejecutar el comando agentengine self-update sin usar el comando sudo.
Mueva el archivo .exe a un directorio que ya esté en su PATH, o agregue su directorio a System Properties -> Environment
Variables -> Path en la GUI de Windows.
Para usar los comandos agentengine, cambie el nombre del binario a agentengine.exe.
Verifique la instalación.
Confirme que la interfaz de línea de comandos (CLI) está instalada comprobando su versión:
agentengine version
La salida es similar a la siguiente:
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 obtener información sobre cómo actualizar una interfaz de línea de comandos (CLI) instalada a una versión más reciente, consulte la sección "Actualizar la CLI".
Verificar la imagen base del corredor
La imagen base del agente es la imagen de contenedor que el motor de agentes de Atlas utiliza para ejecutar localmente cada uno de los tres servicios del agente. Si Docker no puede descargar esta imagen al ejecutar un agente por primera vez, este no se iniciará. Verificar la imagen base de Docker permite detectar y solucionar cualquier problema de red antes de ejecutar el proyecto del agente. La verificación de la imagen base del agente es opcional, pero recomendable.
El desarrollo local descarga la imagen base del ejecutor desde el registro de imágenes de contenedores alojado en MongoDB. No necesitas acceso a GitHub ni un inicio de sesión de registro independiente. La interfaz de línea de comandos (CLI) utiliza tu sesión agentengine auth login para recuperar la imagen e imprime el host del registro cuando ejecutas el comando agentengine dev up.
Autentíquese en el registro de imágenes de la plataforma.
Ejecute el siguiente comando para registrar su instalación local de Docker en el registro de imágenes de la plataforma:
agentengine dev login
El comando agentengine dev up ejecuta este flujo automáticamente, por lo que este paso solo es necesario cuando se descarga una imagen directamente.
Extrae la imagen base del corredor.
Ejecuta el siguiente comando para descargar la imagen base del corredor y reemplaza <runner-base-image> con el valor que copiaste de la salida agentengine version:
docker pull <runner-base-image>
Una extracción exitosa termina con una línea Status: que lee Downloaded newer image o Image is up to date.
Autentica tu cuenta
El comando agentengine auth login inicia un flujo de inicio de sesión OIDC basado en navegador contra la puerta de enlace API de Atlas Agent Engine y guarda el estado de autenticación local para futuros comandos de la CLI.
Nota
Delegación OAuth de Atlas
Al iniciar sesión en Atlas Agent Engine, la plataforma recupera automáticamente sus asignaciones de roles de Atlas y determina a qué organizaciones y proyectos puede acceder. La plataforma utiliza el servidor de conexiones de aplicaciones OAuth de Atlas 2.1 para autorizar el acceso a Atlas.
Inicie sesión en el motor de agentes de Atlas.
Desde tu terminal, ejecuta el siguiente comando:
agentengine auth login
Por defecto, esto abre un navegador en la puerta de enlace API de producción en https://agentengine.mongodb.com. Puede pasar --base-url al comando para dirigirse a una puerta de enlace diferente, o pasar --no-browser para imprimir la URL de inicio de sesión sin abrir un navegador. El siguiente código muestra el formato del comando:
agentengine auth login [--base-url <url>] [--no-browser] [--timeout <duration>]
Una vez que complete el inicio de sesión, la CLI lee sus membresías de proyecto desde la API y guarda el ID de proyecto seleccionado project_id, así como su token de autenticación.
Seleccione un proyecto.
Si tu cuenta pertenece a un solo proyecto, se selecciona automáticamente. Si pertenece a varios proyectos, la interfaz de línea de comandos (CLI) te pide que elijas uno de forma interactiva. Si no tienes preferencia, selecciona tu proyecto predeterminado. La CLI guarda tu selección como predeterminada, la cual puedes modificar con el indicador --project-id.
Verifique su estado de autenticación.
Para comprobar si la autenticación se realizó correctamente, ejecute el siguiente comando:
agentengine auth status
Este comando imprime tu contexto de autenticación local actual sin contactar con la plataforma, y su salida refleja el estado de inicio de sesión guardado en el disco. Puedes pasar el indicador --json al comando para generar un objeto JSON con los campos auth, command_defaults y directory_context por separado.
Hasta que registre un directorio de agentes ejecutando el comando agentengine init, el campo Directory context mostrará none found. Un inicio de sesión exitoso seguirá mostrando su cuenta, URL base y organización y proyecto predeterminados.
Tip
Si tu token de autenticación caduca, cierra sesión y vuelve a iniciarla para actualizarlo:
agentengine auth logout agentengine auth login
Próximos pasos
Tras instalar y autenticar tu cuenta con el Motor de Agentes de MongoDB Atlas, puedes crear un proyecto. Para saber cómo realizar los siguientes pasos, consulta la guía «Crear un proyecto».