Overview
En esta guía, aprenderá a crear la imagen del agente desde la interfaz de línea de comandos (CLI). El proceso de compilación carga el código fuente del agente en el almacenamiento en la nube e inicia una tarea de compilación remota que genera una imagen de Docker.
Sintaxis y opciones del comando de compilación
Utilice la siguiente sintaxis para crear la imagen del agente:
agentengine build [--label <str>] [--no-wait] [--context <name>] [--workspace <name>] [--all] [--json] [--upload-build-secrets]
Este comando empaqueta el código fuente del agente como un archivo tar.gz, lo carga en un bucket de Simple Storage Service (S3) a través de una URL pre-firmada y luego inicia un trabajo de AWS CodeBuild para producir una imagen de Docker en el Elastic Container Registry (ECR).
Banderas de comando
Al crear la imagen del agente, puede utilizar las siguientes opciones:
Flag | Descripción |
|---|---|
| La etiqueta de compilación. Por defecto, este valor se lee de su repositorio git local en el formato |
| Indica a la interfaz de línea de comandos que regrese inmediatamente después de iniciar el trabajo de compilación sin consultar el estado de la compilación. |
| El contexto local con nombre del archivo |
| (Solo para Monorepo) Crea un espacio de trabajo específico por nombre, tal como se define en la raíz |
| (Solo para Monorepo) Compila todos los espacios de trabajo secuencialmente. La CLI crea el archivo fuente una vez y luego ejecuta los pasos de carga y compilación para cada espacio de trabajo. Una vez que comienzan todas las compilaciones, las consulta hasta que alcanzan un estado terminal. Esta opción es mutuamente excluyente con |
| Genera un único resultado de compilación legible por máquina. |
| Carga cada |
Contenido del archivo
Antes de cargar el código fuente del agente, la CLI crea el archivo tar.gz al que se hace referencia en la sección anterior. Esta sección describe qué directorio incluye el archivo y qué archivos excluye.
Archivo raíz
Por defecto, el comando agentengine build empaqueta únicamente el directorio del agente. Si el archivo de configuración del espacio de trabajo o del monorepo incluye el directorio del agente como miembro, el comando empaqueta desde la raíz del espacio de trabajo o del monorepo. El requisito de inclusión depende del tipo de espacio de trabajo, como se describe en la siguiente tabla:
Tipo de espacio de trabajo | Requisitos de membresía |
|---|---|
espacio de trabajo UV | El directorio del agente debe coincidir con un patrón |
Monorepo | El directorio del agente debe aparecer exactamente como está escrito en la lista |
Para encontrar la raíz del espacio de trabajo o monorepo, la CLI busca hacia arriba en los directorios superiores del directorio del agente un archivo que marque la raíz. La búsqueda se detiene en el directorio raíz del repositorio Git y nunca continúa en tu directorio personal, por lo que el comando no puede empaquetar archivos desde fuera del repositorio.
Si el directorio del agente es un submódulo de Git o un árbol de trabajo vinculado, la búsqueda no se detiene en ese límite. La búsqueda continúa en el repositorio principal, y las reglas de pertenencia descritas en la tabla anterior determinan desde qué directorio se obtienen los paquetes del comando.
Archivos excluidos
Un archivo .agentengineignore a nivel de proyecto en la raíz del archivo controla qué archivos incluye la CLI en el archivo. Este archivo utiliza la sintaxis estándar .gitignore, incluyendo comodines, ** y negación !. El comando agentengine init crea el archivo con los siguientes patrones predeterminados:
.git.venv*__pycache__.pytest_cache.mypy_cache.ruff_cachenode_modulesdistbuild.agentengine*.pyc.env.env.*.DS_Store*.pem*.key
Si el archivo no existe, la CLI utiliza los mismos patrones predeterminados que el comando agentengine init.
Los siguientes archivos siempre se excluyen, y no se puede utilizar una negación ! en el archivo .agentengineignore para anular esa exclusión:
.envy archivos.env.**.pemy archivos*.keyClaves privadas comunes de OpenSSH:
id_rsa,id_dsa,id_ecdsa,id_ed25519yid_ed448.gitdirectorioAlmacenes de credenciales en la nube y de herramientas:
.aws,.kube,.ssh,.netrc,.git-credentials,.azure,.config/gh,.docker/config.jsony.config/gcloud
El archivo .npmrc a nivel de proyecto no forma parte de este conjunto de archivos excluidos. La compilación de la plataforma lee el archivo .npmrc del repositorio para resolver los registros privados de npm declarados. La compilación también lee pyproject.toml para resolver los registros privados de PyPI declarados. Para obtener información sobre cómo configurar las credenciales de registro privado para la compilación, consulte Repositorios de artefactos privados.
Advertencia
Dado que la compilación incluye los archivos .npmrc y pyproject.toml, no almacene tokens de registro ni credenciales en ellos. En su lugar, declare las credenciales en el archivo artifact_repositories de su archivo agent.yaml. Para obtener más información, consulte Repositorios de artefactos privados.
Depósitos privados de artefactos
Si su agente depende de paquetes alojados en repositorios de artefactos privados como AWS CodeArtifact, declare dichos repositorios en el bloque artifact_repositories de su archivo agent.yaml. El motor del agente de Atlas resuelve las credenciales del registro durante la compilación a partir del secreto del motor del agente de Atlas especificado en cada entrada y las inyecta en el entorno de compilación. Las credenciales no se almacenan en sus archivos fuente ni se exponen a los pods en ejecución. Si no declara ningún repositorio, el motor del agente de Atlas resuelve las dependencias de los registros públicos utilizando su configuración de herramientas existente, sin modificaciones.
Las URL del registro se encuentran en las herramientas de tu proyecto, no en agent.yaml. Para los agentes de Python, declara cada índice privado en una entrada [[tool.uv.index]] en pyproject.toml. El campo name en agent.yaml debe coincidir con el nombre del índice. Para los agentes de TypeScript, declara cada registro con ámbito privado en un archivo .npmrc. Establece npm_scope en agent.yaml con el ámbito que se corresponde con el registro. Los siguientes ejemplos muestran el archivo de herramientas y la entrada agent.yaml correspondientes para cada lenguaje:
[[tool.uv.index]] name = "corps-pypi" url = "https://<domain>-<account>.d.codeartifact.<region>.amazonaws.com/pypi/<repo>/simple/" explicit = true
artifact_repositories: - name: corps-pypi type: pypi secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN username: aws scope: project
@acme:registry=https://npm.pkg.github.com/
artifact_repositories: - name: corp-npm type: npm secret: ARTIFACT_REPO_CORP_NPM_TOKEN npm_scope: "@acme" scope: project
Para obtener información sobre el esquema completo artifact_repositories, consulte el Esquema YAML del agente.
Antes de que comience la compilación, el motor del agente de Atlas valida los repositorios declarados con las herramientas de su proyecto. Si la validación falla, la compilación se detiene con un error procesable. Para detectar problemas antes de compilar, ejecute agentengine agent validate localmente. Para obtener más información, consulte Validar configuración.
Cada artifact_repositories[].secret declarado debe existir en el ámbito declarado en los secretos de Atlas Agent Engine antes de que comience la compilación. Para tokens de registro de corta duración que caducan entre compilaciones, utilice la bandera --upload-build-secrets para cargar cada secreto desde una variable de entorno con el mismo nombre. El siguiente ejemplo crea un token de AWS CodeArtifact y lo carga en un comando de compilación:
export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \ --domain my-domain --query authorizationToken --output text)" agentengine build --upload-build-secrets
Para credenciales de larga duración, configure cada secreto una sola vez con agentengine secret set y compile sin la bandera. Para obtener más información sobre el aprovisionamiento de secretos, consulte Aprovisionamiento de secretos en la nube.
Comandos de administración de compilaciones
La siguiente tabla describe los comandos de administración de compilaciones que puede utilizar para supervisar y administrar las compilaciones de su agente:
Comando | Descripción |
|---|---|
| Envía los registros de compilación a |
| Muestra todas las compilaciones del espacio de trabajo en formato de tabla. La tabla incluye el ID de la compilación, el estado, la etiqueta y la hora de creación. |
| Cancela una compilación específica que esté en ejecución o en cola. Este comando devuelve un error si la compilación ya se ha completado con éxito o ha fallado. |
| Promueve una imagen de compilación exitosa a otro espacio de trabajo sin reconstruir la imagen desde el origen. Para obtener más información, consulte Promover una compilación. |
| Devuelve el estado de una promoción de compilación específica. La salida incluye el ID de la compilación de destino y el motivo del fallo, si la promoción falló. |
Tip
Banderas de comando
Cada comando de gestión de compilación acepta los indicadores --workspace-id y --project-id para especificar el espacio de trabajo y el proyecto. Si no se proporcionan, la interfaz de línea de comandos lee estos valores del archivo .agentengine/state.json.
Promocionar una construcción
Al promocionar una compilación, el motor del agente de Atlas copia una imagen de compilación probada de un espacio de trabajo a otro sin reconstruir la imagen desde el origen. Dado que la imagen promocionada es idéntica byte a byte a la imagen de origen, el agente que se ejecuta en el espacio de trabajo de destino es el mismo que se probó en el espacio de trabajo de origen.
Nota
La página de detalles de compilación de la interfaz de usuario de la plataforma no muestra una sección Build Logs para una compilación promocionada, porque una promoción reutiliza una imagen existente en lugar de ejecutar una nueva compilación.
Por defecto, la compilación del código fuente debe tener al menos un despliegue exitoso, lo que confirma que la imagen es desplegable. Para omitir este requisito, utilice la bandera --force.
Utilice la siguiente sintaxis para promover una compilación:
agentengine build promote <source_build_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--context <name>] [--force] [--yes] [--json]
La interfaz de línea de comandos (CLI) identifica la compilación de origen mediante su ID y la resuelve dentro de su organización actual. No puede promover una compilación a un proyecto en una organización diferente.
Al promocionar una compilación, puede utilizar las siguientes opciones:
Flag | Descripción |
|---|---|
| (Solo Monorepo) El nombre del espacio de trabajo de destino, tal como se define en el archivo raíz |
| El ID del espacio de trabajo de la plataforma de destino. |
| El ID del proyecto de la plataforma de destino. |
| El contexto local con nombre del archivo |
| Omite el requisito de implementación exitosa. Este indicador requiere el rol |
| Omite la solicitud de confirmación interactiva. Utilice esta opción cuando ejecute el comando en una canalización de integración continua (CI) u otro entorno no interactivo. Sin ella, el comando fallará fuera de una terminal interactiva. |
| Genera el resultado de la promoción en formato JSON. |
Advertencia
La promoción no copia la configuración de tiempo de ejecución ni del proyecto del espacio de trabajo de origen. Los secretos, la configuración de conexión de Atlas y las políticas de salida no se transfieren al espacio de trabajo de destino. Antes de implementar la compilación promocionada, configure estos ajustes en el proyecto y el espacio de trabajo de destino.
Una vez que la promoción se haya realizado correctamente, implemente la compilación promocionada en el espacio de trabajo de destino. Para obtener información sobre cómo implementar una compilación, consulte Implementar su compilación.
Ejemplo
El siguiente comando crea la imagen del agente sin consultar el estado de la compilación y, a continuación, muestra la información de la compilación:
agentengine build --no-wait && agentengine build list
Si la compilación se realiza correctamente, la salida del comando se asemeja al siguiente ejemplo:
Initialising build... build_id: <build_id> Creating archive... Uploading archive... Starting build... ✓ Build started (build_id: ...) URL: https://agentengine.mongodb.com/api/v1/workspaces/<workspace_id>/builds/<build_id> BUILD_ID STATUS LABEL CREATED_AT <build_id> running main@abc123def456 2026-04-01T10:30:00Z
Próximos pasos
Tras crear la imagen del agente, puede implementarlo en producción. Para obtener información sobre cómo implementar el agente, consulte la guía Implementar su compilación.