Overview
En esta guía, aprenderá a iniciar un entorno de desarrollo local para su agente de Atlas Agent Engine. El comando agentengine dev crea una imagen de Docker que incluye el código de su aplicación e inicia la pila completa del agente, incluyendo el orquestador, el entorno aislado del agente, el entorno aislado de herramientas y una instancia local de MongoDB, en su máquina. Cuando el entorno esté en funcionamiento, la interfaz de línea de comandos (CLI) mostrará las URL de los servicios para que pueda desarrollar y probar su agente.
Requisitos previos
Antes de comenzar, asegúrese de instalar la interfaz de línea de comandos (CLI) agentengine. Para obtener más información sobre cómo instalar la CLI, autenticarse y registrar el proyecto, consulte la sección Instalación y autenticación.
Configuración opcional
Esta sección describe las opciones de configuración que puede utilizar para configurar su entorno de desarrollo local.
Habilitar memoria
Si configura features.memory: true en su archivo agent.yaml, agregue las siguientes variables a su archivo .env antes de iniciar el entorno local:
VOYAGE_API_KEY: Necesario para generar incrustaciones de memoria.MONGOMEM_DB_NAME: Opcional. El nombre de la base de datos MongoDB en la que escribe el servidor de memoria. Por defecto esmdb_memory_<project-id>.
Configurar los ajustes de desarrollo local
Puedes usar un archivo dev.yaml para anular las asignaciones de puertos de servicio locales y activar o desactivar la instancia local de MongoDB durante el desarrollo. Coloca tu archivo dev.yaml en el mismo directorio que tu archivo agent.yaml. Este archivo es opcional y la plataforma no lo agrega a tu archivo .gitignore, por lo que puedes confirmar y compartir la configuración.
La siguiente tabla describe los campos que puede incluir en el archivo dev.yaml:
Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| entero (1–65535) | no | Anulación de puerto para un servicio de plataforma. Los nombres de servicio válidos son: |
| bool | no | Indica si se debe iniciar una instancia local de MongoDB como parte del entorno de desarrollo. Por defecto, se utiliza |
| Int | no | Puerto en el que MongoDB escucha cuando se ejecuta localmente. Por defecto es |
El siguiente ejemplo muestra un archivo dev.yaml que configura todos los campos disponibles:
services: playground: port: 3000 oe: port: 8000 aer: port: 8001 tool: port: 8002 mongodb: local: true port: 27017
Iniciar el desarrollo local
El comando agentengine dev admite dos modos de inicio: modo de recarga en caliente para el desarrollo activo y modo aislado para probar una topología similar a la de producción.
Modo de recarga rápida (recomendado)
El modo de recarga en caliente ejecuta todos los servicios del agente dentro de un único contenedor de aplicación y monta el código fuente directamente en él. Cuando editas un archivo, watchfiles detecta el cambio y recarga automáticamente el servicio afectado sin necesidad de una reconstrucción completa.
(Opcional) Adjunte VS Code como contenedor de desarrollo.
Si utiliza Visual Studio (VS) Code, siga estos pasos para conectarse directamente al contenedor en ejecución. Esto le proporcionará una experiencia de desarrollo integrada con soporte completo para IntelliSense y depuración.
Instala la extensión Dev Containers en VS Code.
Mientras la pila esté en funcionamiento, abra Command Palette y seleccione Dev Containers:/ Reopen in Container.
VS Code se conecta al contenedor de la aplicación y recarga el espacio de trabajo que contiene.
Modo aislado
Puedes usar la bandera --isolated para iniciar el entorno local en modo aislado. El modo aislado inicia cada servicio de agente en un contenedor independiente, replicando la topología de producción. Usa este modo para validar el comportamiento entre servicios o para reproducir problemas específicos de producción. Dado que el código no se monta desde tu host, debes reconstruir las imágenes después de realizar cambios en el código.
Gestionar el entorno local
Utilice los siguientes comandos agentengine dev para administrar su entorno de ejecución.
Ver registros
Para transmitir los registros de todos los servicios en ejecución, ejecute el siguiente comando:
agentengine dev logs
Para transmitir registros desde un servicio específico, pase el nombre del servicio como argumento posicional:
agentengine dev logs <service>
En un monorepo, pase --all para transmitir los registros de la pila compartida de todos los espacios de trabajo:
agentengine dev logs --all
Comprobar el estado de la pila local
El comando agentengine dev status muestra el estado actual de la pila de composición local, incluyendo el estado de cada servicio y las URL de host publicadas. El siguiente ejemplo muestra la sintaxis del comando:
agentengine dev status [--workspace <name>] [--all] [--json]
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| (Solo Monorepo) Se dirige a un agente específico por su nombre, tal como se define en la raíz |
| (Solo para Monorepo) Se dirige a la pila de todos los espacios de trabajo. |
| Imprime un objeto de estado legible por máquina en la salida estándar. Incluye |
Reiniciar servicios
El comando agentengine dev restart reinicia los contenedores app y oe de recarga en caliente sin reconstruir la imagen. Úselo después de cambiar las dependencias en el host. El siguiente ejemplo muestra la sintaxis del comando:
agentengine dev restart [--workspace <name>]
Este comando se dirige únicamente a la pila de recarga en caliente. No admite --all ni el modo aislado.
Agregar nuevas dependencias
Cuando agregas una dependencia a tu archivo pyproject.toml, es posible que la pila de desarrollo local no la instale si ya existe un archivo uv.lock. Cuando hay un archivo uv.lock presente, el punto de entrada de desarrollo sincroniza el entorno con la bandera --frozen, que resuelve las dependencias desde el archivo lockfile en lugar de desde el archivo pyproject.toml.
Para instalar la nueva dependencia, ejecute los siguientes comandos para eliminar el archivo uv.lock y reiniciar la pila:
rm uv.lock agentengine dev stop agentengine dev up
Como alternativa, puede ejecutar los siguientes comandos para actualizar el archivo de bloqueo antes de reiniciar la pila:
uv lock agentengine dev stop agentengine dev up
Utilice repositorios de artefactos privados.
Si su agente depende de paquetes alojados en repositorios de artefactos privados, como un PyPI privado o un registro npm en AWS CodeArtifact, declárelos en el bloque artifact_repositories de su archivo agent.yaml. En el modo de recarga en caliente, los comandos agentengine dev up y agentengine dev restart configuran automáticamente las credenciales del registro para las entradas type: pypi. La CLI no configura automáticamente las entradas npm. Para las dependencias privadas de npm, autentíquese a través de su configuración local de npm, como un archivo .npmrc a nivel de proyecto.
Para cada repositorio PyPI declarado, proporcione una credencial a través de uno de los siguientes métodos:
Una variable
UV_INDEX_<NAME>_PASSWORD(y opcionalmente_USERNAME) en su entorno de proceso o archivo.env. Por ejemplo, para un índice llamadocorps-pypi, establezcaUV_INDEX_CORPS_PYPI_PASSWORD.El campo
secretdeclarado, leído desde su archivo.env.Para un índice de AWS CodeArtifact, se requiere un token generado a partir de su perfil activo de AWS o sesión SSO.
Si no se resuelve ninguna credencial para un repositorio declarado, la interfaz de línea de comandos falla e indica el repositorio y las fuentes que se deben comprobar.
Para omitir la autoconfiguración y administrar usted mismo las variables UV_INDEX_*, ejecute el siguiente comando:
agentengine dev up --no-artifact-auth
Nota
Si declara una entrada type: pypi y comienza en modo --isolated o --all, la CLI devuelve un error en lugar de iniciar contenedores que fallan en la instalación de dependencias.
Para obtener información sobre el esquema artifact_repositories, consulte Esquema YAML del agente. Para obtener información sobre cómo funcionan los repositorios de artefactos privados en las compilaciones en la nube,consulte Repositorios de artefactos privados.
Servicios de suspensión
Para pausar el entorno local sin eliminar los contenedores, ejecute el siguiente comando:
agentengine dev stop [--workspace <name>] [--all]
El comando detiene los contenedores sin eliminarlos. Ejecute agentengine dev up nuevamente para reanudar los contenedores sin reconstruirlos.
Restablecer estado local
Para detener todos los contenedores y eliminar todos los volúmenes asociados y los archivos de tiempo de ejecución generados, ejecute el siguiente comando:
agentengine dev clean [--workspace <name>] [--all]
Advertencia
Al ejecutar agentengine dev clean se eliminan permanentemente todos los datos locales almacenados en el volumen local de MongoDB Atlas. Realice una copia de seguridad de los datos que necesite antes de ejecutar este comando.
Después de la limpieza, ejecute agentengine dev up para regenerar los archivos e iniciar nuevos contenedores locales.
Autenticar servidores MCP remotos
Los comandos agentengine dev mcp auth administran las credenciales OAuth para los servidores MCP remotos configurados en su archivo agent.yaml en mcp.servers. Los comandos escriben las credenciales de inicio de sesión en la caché de credenciales de desarrollo en ~/.agentengine/mcp-oauth, y las pilas agentengine dev up generadas montan ese directorio automáticamente.
La caché es independiente para cada proyecto y cada punto final de MCP. Iniciar sesión desde un proyecto no inicia sesión en otro, por lo que debe ejecutar el comando agentengine dev mcp auth login una vez por proyecto. Para obtener información sobre los requisitos de nomenclatura para los servidores MCP, consulte las Reglas de nomenclatura del servidor.
inicio de sesión de autenticación
Utilice el comando agentengine dev mcp auth login para abrir el flujo de autorización del proveedor para un servidor y guardar las credenciales en la caché de desarrollo, como se muestra en el siguiente ejemplo:
agentengine dev mcp auth login <server> [--no-browser]
La bandera --no-browser imprime la URL de inicio de sesión en lugar de abrir la URL en un navegador.
La URL de autorización que anuncia el servidor debe usar el esquema https. Si el servidor anuncia un punto final de autorización que usa cualquier otro esquema, el comando se detiene y genera un error Refused to open unauthorized MCP OAuth URL.
estado de autenticación
Utilice el comando agentengine dev mcp auth status para comprobar si existen credenciales almacenadas en caché para un servidor, como se muestra en el siguiente ejemplo:
agentengine dev mcp auth status [server] [--check]
El indicador --check utiliza las credenciales almacenadas en caché para conectarse al servidor MCP y llama al punto final de la lista de herramientas para confirmar que el servidor las acepta.
carga de autenticación
Utilice el comando agentengine dev mcp auth upload para codificar en base64 la caché OAuth local de un servidor y almacenarla como un secreto de espacio de trabajo llamado AGENTIC_MCP_OAUTH_B64_<SERVER>. Este comando expone las credenciales de autorización a los agentes desplegados.
El siguiente ejemplo muestra la sintaxis del comando:
agentengine dev mcp auth upload <server> [--workspace-id <id>] [--sync]
La bandera --workspace-id especifica el ID del espacio de trabajo, y la bandera ``--sync`` recarga los secretos en las implementaciones activas inmediatamente después de la carga.
Antes de la carga, la interfaz de línea de comandos (CLI) verifica que la URL del servidor registrada en la caché coincida con la URL del archivo agent.yaml. Si la caché se registró para un punto final diferente, la CLI rechaza la carga y le solicita que ejecute el comando agentengine dev mcp auth login nuevamente.
Validar configuración
El comando agentengine agent validate analiza localmente el archivo agent.yaml con el mismo analizador y validador que utiliza el proceso de compilación. Ejecútalo antes de compilar para detectar errores tipográficos, valores no válidos y errores de política de red.
El siguiente ejemplo muestra la sintaxis del comando:
agentengine agent validate [path] [--strict]
La ruta predeterminada es ./agent.yaml. Pase una ruta explícita para validar un archivo en una ubicación diferente, como un espacio de trabajo monorepo.
El comando devuelve los siguientes códigos de salida:
Código de salida | Significado |
|---|---|
|
|
| La validación falló. El resultado identifica los campos no válidos. |
| Error de archivo o de entrada/salida. No se pudo leer el archivo. |
El comando no requiere autenticación y puede ejecutarse en CI sin un token válido.
Cuando artifact_repositories no está vacío, el comando compara los nombres de índice declarados con las herramientas del proyecto en el mismo directorio que agent.yaml. Para los agentes de Python, lee pyproject.toml y uv.lock. Para los agentes de TypeScript, lee package.json, .npmrc y package-lock.json. Se permiten URL privadas no declaradas en los archivos de bloqueo, ya que la inyección de credenciales es opcional. Los mismos errores graves que bloquean las compilaciones en la nube detienen la validación y devuelven el código de salida 1.
Cuando inicie sesión, el comando también imprimirá advertencias no bloqueantes para valores artifact_repositories[].secret faltantes o con ámbito incorrecto, incluyendo WORKSPACE_CONTEXT_NEEDED cuando se declara una entrada con ámbito de espacio de trabajo sin un contexto agentengine init activo. Pase --strict para tratar estas advertencias como código de salida 1. Para obtener información sobre cómo funcionan los repositorios de artefactos privados en las compilaciones en la nube, consulte Repositorios de artefactos privados.
Nota
El comando agentengine agent validate es experimental. Sus indicadores, formato de salida y códigos de salida pueden cambiar a medida que el validador se amplía para cubrir más campos agent.yaml.
Próximos pasos
Una vez que su entorno local esté en funcionamiento, podrá probar el agente y realizar iteraciones en su código. Para aprender a probar manualmente el agente y aplicar cambios en el código, consulte la sección «Probar el agente».