Overview
En este tutorial, crearás e implementarás un agente "Hola Mundo" en el motor de agentes Atlas de MongoDB. Instalarás la interfaz de línea de comandos agentengine y generarás un proyecto a partir de una plantilla inicial. Luego, ejecutarás el agente localmente, lo registrarás y lo compilarás e implementarás en el motor de agentes Atlas.
El tutorial utiliza Anthropic como proveedor de modelos de lenguaje a gran escala (LLM, por sus siglas en inglés) y macOS como sistema operativo.
Requisitos previos
Asegúrese de cumplir con los siguientes requisitos previos antes de comenzar:
Un equipo macOS. Para ver las instrucciones de configuración para Windows y Linux, consulte la guía de instalación y autenticación.
Git
Docker Desktop ejecutándose en tu máquina
Una cuenta de Atlas con acceso a al menos una organización de Atlas.
Una clave API para el proveedor de LLM que haya elegido. Este tutorial utiliza Anthropic, pero puede usar cualquier proveedor.
Procedimiento
Siga los pasos que se indican a continuación para instalar la interfaz de línea de comandos agentengine, crear un agente "Hola Mundo", ejecutarlo localmente e implementarlo en el motor de agentes de Atlas.
Instale la interfaz de línea de comandos agentengine.
Inicie sesión en Atlas Agent Engine y, a continuación, descargue la CLI desde la página de descargas de la CLI. El menú desplegable Version ya muestra la última versión de la CLI, y el menú desplegable Platform muestra el sistema operativo detectado.
Haz clic en el botón Download for <your platform>. Guarda el valor de suma de comprobación SHA-256 que aparece en la página para usarlo en el siguiente paso.
Complete la instalación de la CLI.
En tu terminal, navega hasta tu directorio de descargas y ejecuta el siguiente comando:
shasum -a 256 agentengine
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.
Ejecute los siguientes comandos para marcar el binario como ejecutable y moverlo al directorio ~/.local/bin:
chmod +x ./agentengine 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.
Para obtener más información, consulte Instalar la CLI de agentengine.
Crear un proyecto de agente.
Ejecute el siguiente comando para generar un proyecto de agente "Hola Mundo":
agentengine create
Cuando la interfaz de línea de comandos (CLI) se lo solicite, seleccione los siguientes valores:
Plantilla: Agente Hola Mundo
Proveedor del programa LLM: Anthropic Claude
Clave API: su clave API de Anthropic
Habilitar memoria: no
El comando crea un directorio raíz del proyecto que contiene un archivo de configuración project-config.yaml y un directorio agents/. Los archivos de su agente, que incluyen el archivo de configuración agent.yaml, un archivo .env con su clave API y un archivo pyproject.toml, se encuentran en un subdirectorio de agents/. El siguiente ejemplo muestra la estructura que crea el comando:
my-project/ ├── project-config.yaml └── agents/ └── my-agent/ ├── agent.yaml ├── pyproject.toml ├── .env └── src/
Ejecute todos los comandos agentengine subsiguientes desde su directorio de agente, que es my-agent/ en este ejemplo.
Ejecuta el agente localmente.
El desarrollo local requiere acceso a la imagen base del ejecutor alojada en el registro de imágenes de contenedores de MongoDB. La interfaz de línea de comandos descarga la imagen utilizando su sesión agentengine auth login, por lo que no necesita iniciar sesión en un registro independiente.
Navegue hasta el directorio de su agente y ejecute el siguiente comando para iniciar el entorno de desarrollo local:
agentengine dev up La interfaz de línea de comandos (CLI) crea una imagen de Docker e inicia la pila completa de agentes. Cuando la pila se inicia correctamente, la salida del comando se asemeja a la siguiente:
◆ 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 Cuando todos los servicios estén listos, abre la URL
http://localhost:3000en tu navegador para chatear con tu agente.Nota
Es posible que la interfaz de usuario se ejecute en un puerto diferente al predeterminado
3000. Para ver la URL, compruebe el campouien la salida del comandoagentengine dev up.El siguiente ejemplo muestra un intercambio exitoso con su agente:
haga clic para ampliarPara detener el entorno local, ejecute el siguiente comando:
agentengine dev stop
Configurar los recursos de Atlas.
El motor de agentes de Atlas requiere un clúster de Atlas para almacenar el estado de ejecución, los puntos de control y el historial. La interfaz de línea de comandos (CLI) solo admite credenciales de cuentas de servicio de Atlas. No se admiten inicios de sesión de cuentas de usuario de Atlas ni claves públicas y privadas de la API de Atlas heredada.
Importante
Facturación Atlas
En este paso, puede seleccionar un clúster de Atlas existente o crear uno nuevo. Si crea un clúster nuevo, la CLI aprovisionará un clúster Atlas Flex de pago por defecto. Atlas le cobrará por las operaciones del clúster hasta que lo finalice. Para eliminar los recursos creados en este tutorial, consulte la sección «Limpiar recursos».
En la interfaz de usuario de Atlas, cree o seleccione una cuenta de servicio:
Abra el proyecto Atlas que desea utilizar.
Diríjase a Aplicaciones en el menú Identidad y acceso del proyecto y cree o seleccione una cuenta de servicio.
Otorgue a la cuenta de servicio el permiso de Propietario del proyecto. Para saber por qué se requiere este rol,consulte Roles de Atlas para la gestión de proyectos.
Ejecute el siguiente comando para configurar y aprovisionar un clúster:
agentengine atlas setup Cuando se le solicite, introduzca el ID de cliente y la clave secreta de su cuenta de servicio de Atlas. La CLI aprovisiona un clúster, configura el acceso a la red y almacena
MONGODB_URIcomo clave secreta de la plataforma. Para obtener más información sobre los recursos de Atlas, consulte Configuración de recursos de Atlas.
Configurar secretos en la nube.
El agente desplegado requiere credenciales para invocar el LLM y conectarse a Atlas.
Ejecute el siguiente comando para configurar la clave API de Anthropic. La interfaz de línea de comandos le pedirá que introduzca el valor.
agentengine secret set ANTHROPIC_API_KEY
Para obtener más información sobre la gestión de secretos,consulte Aprovisionamiento de secretos en la nube.
Construye e implementa el agente.
Ejecute el siguiente comando para crear la imagen del agente e implementarla en un solo paso:
agentengine deploy --auto
El comando empaqueta el código de tu agente, inicia una tarea de compilación remota y supervisa el despliegue que desencadena la compilación. La compilación tarda entre 5 y 10 minutos, y el despliegue otros 5 a 10 minutos. Durante el despliegue, la salida podría mostrar Agent Sandbox: waiting y Tool Sandbox: waiting durante varios minutos. Cuando el despliegue se realiza correctamente, la salida del comando se asemeja a la siguiente:
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>
Su agente ahora se está ejecutando en el motor de agentes Atlas de MongoDB.
La bandera --auto se aplica únicamente a proyectos de agente único. Para compilar e implementar en pasos separados, o para implementar una compilación específica, ejecute agentengine build y luego agentengine deploy. Para obtener más información, consulte Iniciar una implementación.
Solución de problemas en una implementación fallida
Las causas más comunes de fallos en la implementación son:
Secretos mal configurados
Un clúster de Atlas cuya lista de acceso IP no está configurada para permitir el tráfico desde el motor de agentes de Atlas.
Para depurar una implementación fallida, ejecute los siguientes comandos para ver los registros de Atlas Agent Engine:
# View deployment logs agentengine deploy logs # View deployed agent workspace logs agentengine logs
Para obtener más información sobre cada comando,consulte las guías "Ver el registro de eventos de implementación" y "Usar la interfaz de línea de comandos".
Recursos de limpieza
Este tutorial proporciona recursos que permanecen hasta que los elimine. Cuando ya no necesite estos recursos, elimínelos de las siguientes maneras:
Clúster de Atlas: Para finalizar un clúster, abre la página Clusters de tu proyecto de Atlas, haz clic en los puntos suspensivos (
...) junto al clúster y, a continuación, haz clic en Terminate. Si seleccionaste un clúster existente, el tutorial no crea uno nuevo, así que puedes dejarlo sin cambios.Espacio de trabajo: El comando
agentengine initcrea un espacio de trabajo en Atlas Agent Engine que contiene el agente implementado. Para encontrar el ID del espacio de trabajo, ejecute el siguiente comando:agentengine workspace list A continuación, ejecute el siguiente comando para eliminar el espacio de trabajo:
agentengine workspace delete <workspace-id> --yes Usuario de la base de datos: El proceso de configuración crea un usuario de base de datos que su agente utiliza para conectarse a Atlas. En la interfaz de usuario de Atlas, abra Database & Network Access y haga clic en el icono de eliminar junto al usuario de la base de datos.
Clave API de Voyage AI: El proceso de configuración crea una clave API de Voyage AI para habilitar las funciones de memoria de su agente. En la interfaz de usuario de Atlas, abra AI Model APIs y haga clic en el icono de eliminar junto a la clave API.
Secretos de la plataforma: El proceso de configuración pregunta si desea almacenar los valores
MONGODB_URIyVOYAGE_API_KEYcomo secretos de la plataforma. Si elige almacenar estos secretos, puede eliminarlos siguiendo las instrucciones en Eliminar un secreto.
Próximos pasos
Tras desplegar el agente, consulte las siguientes páginas para obtener recursos adicionales:
Para autenticar y llamar al agente desplegado, consulte la sección "Invocar un agente".
Para probar el agente y perfeccionar su código,consulte la sección "Probar el agente".
Para supervisar la ejecución de los agentes en la interfaz de usuario de la plataforma, consulte la sección Monitor.