Overview
En esta guía, aprenderá a administrar las organizaciones, proyectos y espacios de trabajo de MongoDB Atlas Agent Engine. Esta guía describe los siguientes comandos de administración:
Organización agentengine: Lista y visualiza organizaciones.
Proyecto agentengine: Lista y visualiza proyectos.
Espacio de trabajo de agentengine: Crea y gestiona espacios de trabajo para un agente desplegado.
agentengine service-account: Crea y gestiona cuentas de servicio para tu proyecto u organización.
versión del motor del agente: Gestiona la versión de la CLI.
Requisitos previos
Antes de comenzar, asegúrese de instalar y autenticar la interfaz de línea de comandos agentengine. Para obtener más información, consulte la guía de instalación y autenticación.
Ver organizaciones
Las organizaciones son la agrupación de nivel superior para sus equipos y recursos en el motor del agente de MongoDB Atlas. La CLI agentengine puede listar y ver las organizaciones, pero no puede modificarlas. Para modificar una organización respaldada por Atlas, utilice MongoDB Atlas:
Si su organización no utiliza MongoDB Atlas, use la interfaz de usuario de Atlas Agent Engine para modificarla.
Lista de todas las organizaciones
Para ver todas las organizaciones a las que pertenece tu cuenta, ejecuta el siguiente comando:
agentengine organization list
Obtenga detalles de la organización
Para obtener detalles de una organización específica, ejecute el siguiente comando. Reemplace <org-id> con el ID de su organización:
agentengine organization get <org-id>
Ver proyectos
Los proyectos existen dentro de una organización y agrupan los recursos para un agente o equipo específico. La CLI agentengine puede listar y ver proyectos, pero no puede modificarlos. Para modificar un proyecto respaldado por Atlas, utilice MongoDB Atlas:
Para crear, actualizar o eliminar un proyecto, consulte la guía de Gestión de proyectos.
Para agregar, actualizar o eliminar usuarios del proyecto, consulte la guía "Administrar el acceso a un proyecto".
Si tu proyecto no utiliza MongoDB Atlas, usa la interfaz de usuario de Atlas Agent Engine para modificarlo.
Listar todos los proyectos
Para listar todos los proyectos de su organización, ejecute el siguiente comando:
agentengine project list [--org-id <org-id>]
Puedes usar el indicador --org-id para especificar el ID de la organización. De forma predeterminada, la CLI lee este valor del estado de autenticación almacenado localmente.
Obtenga detalles del proyecto
Para obtener detalles de un proyecto específico, ejecute el siguiente comando. Reemplace <project-id> con el ID de su proyecto:
agentengine project get <project-id>
Administrar espacios de trabajo
Un espacio de trabajo es el entorno de ejecución de un agente implementado en un proyecto. Utilice los siguientes comandos para crear y administrar espacios de trabajo. Los ejemplos de esta sección utilizan el marcador de posición <workspace-id>. Reemplace este marcador de posición con el ID de su espacio de trabajo.
Listar todos los espacios de trabajo
Para listar todos los espacios de trabajo de tu proyecto, ejecuta el siguiente comando:
agentengine workspace list [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| ID |
| ID de organización para enrutamiento multi-organización |
| URL base de la API de |
| Generar JSON sin procesar en lugar de una tabla legible para humanos. |
Obtenga detalles del espacio de trabajo
Para recuperar los detalles de un espacio de trabajo específico, ejecute el comando agentengine workspace get:
agentengine workspace get <workspace-id> [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| ID |
| ID de organización para enrutamiento |
| URL base de la API de la plataforma |
| Genera JSON sin procesar en lugar de pares clave-valor legibles por humanos. |
Crear un espacio de trabajo
El comando agentengine workspace create crea un nuevo espacio de trabajo en la plataforma. Ejecute este comando desde un directorio de agente que contenga un archivo agent.yaml que incluya los campos name y entrypoint.
El comando lee automáticamente description, framework, features y agent_card de agent.yaml y detecta automáticamente los campos de GitOps del repositorio Git local, si están presentes. Utilice las opciones --description y --framework para sobrescribir los valores de agent.yaml.
Si ya existe un espacio de trabajo para el proyecto, el comando imprime el ID del espacio de trabajo existente y finaliza correctamente.
agentengine workspace create [--description <desc>] [--framework <fw>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| Descripción del espacio de trabajo. Sobrescribe el valor de |
| Marco del agente (por ejemplo, |
| ID |
| ID de organización para enrutamiento |
| URL base de la API de la plataforma |
| Generación JSON con los campos |
Actualizar un espacio de trabajo
El comando agentengine workspace update actualiza parcialmente un espacio de trabajo existente. Solo se incluyen en la solicitud de actualización los parámetros que se proporcionan explícitamente.
agentengine workspace update <workspace-id> [flags]
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| Nombre para mostrar del espacio de trabajo |
| Descripción del espacio de trabajo |
| Marco de agente |
| Nombre del modelo LLM |
| Herramientas habilitadas (separadas por comas) |
| Habilitar o deshabilitar barandillas ( |
| Habilitar o deshabilitar la memoria ( |
| Texto de resumen de la ficha del agente |
| Capacidades de la tarjeta de agente (separadas por comas) |
| Proveedor de GitOps |
| URL del repositorio GitOps |
| Rama GitOps |
| Ruta del manifiesto de GitOps |
| Referencia de conexión de GitOps |
| ID |
| ID de organización para enrutamiento |
| URL base de la API de la plataforma |
Gestiona espacios de trabajo mediante la API.
Los comandos del espacio de trabajo llaman a la API de Atlas Agent Engine. Para administrar los espacios de trabajo mediante programación, llame directamente a estos puntos finales.
Cada punto final del espacio de trabajo está asociado a un único proyecto. Si llama a puntos finales de más de un proyecto, incluya el ID del proyecto en la solicitud.
La siguiente tabla describe los puntos finales disponibles. Reemplace {project-id} con el ID de su proyecto y {workspace-id} con el ID de su espacio de trabajo:
Endpoint | Descripción |
|---|---|
| Enumera los espacios de trabajo del proyecto. |
| Crea un espacio de trabajo en el proyecto. |
| Devuelve los detalles de un único espacio de trabajo. |
| Actualiza los campos que incluyas en el cuerpo de la solicitud. |
| Elimina el espacio de trabajo. |
Administrar cuentas de servicio
Una cuenta de servicio es una identidad programática que pertenece a un proyecto o una organización, en lugar de a una persona. Utilice los siguientes comandos para crear, listar, rotar y eliminar cuentas de servicio.
Para recuperar el token de acceso a su cuenta de servicio, envíe su ID de cliente y su secreto en una solicitud POST al punto final /api/v1/oauth/token. Para obtener más información, consulte Invocar un agente.
Los ejemplos de esta sección utilizan los siguientes marcadores de posición:
<name>: El nombre de la cuenta de servicio.<role>: El rol al que se le otorgará la cuenta de servicio. Para una cuenta de proyecto, usePROJECT_OWNERoPROJECT_READ_ONLY. Para una cuenta de organización, useORG_GROUP_CREATORoORG_READ_ONLY.<client-id>: El ID de cliente de la cuenta de servicio.
Crea una cuenta de servicio
Para crear una nueva cuenta de servicio, ejecute el siguiente comando:
agentengine service-account create <name> --role <role> [--org-id <id> | --project-id <id>] [--description <text>] [--secret-expires-in <duration>] [--ip-access-list <ip-or-cidr>,...] [--json]
El comando muestra el secreto del cliente en texto plano y los detalles de la cuenta de servicio, como se muestra en el siguiente ejemplo:
Client Secret: agp_sa_sk_... Client ID: agp_sa_id_... Name: ci-pipeline ...
Importante
Guarda la clave secreta del cliente cuando se muestre. Solo se muestra una vez.
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| Obligatorio. Rol otorgado a la cuenta de servicio. |
| ID de organización para una cuenta con ámbito de organización. |
| ID de proyecto para una cuenta con ámbito de proyecto. |
| Descripción legible para humanos. |
| Duración del secreto en horas, como |
| Direcciones IP o bloques CIDR autorizados para usar la credencial. |
| Muestra la cuenta de servicio creada, el secreto de cliente de un solo uso y el contexto resuelto en formato JSON. Las advertencias no aparecen en la salida estándar. |
Lista de cuentas de servicio
Para listar todas las cuentas de servicio del proyecto u organización actual, ejecute el siguiente comando:
agentengine service-account list [--org-id <id>] [--project-id <id>] [--limit <n>]
El comando muestra una tabla con el ID del cliente, el nombre, los roles, el estado activo, la fecha de vencimiento del secreto, la fecha del último uso del secreto y la descripción de cada cuenta de servicio.
De forma predeterminada, el comando muestra las cuentas de servicio del proyecto en el estado de autenticación almacenado localmente. Utilice la bandera --org-id o --project-id para mostrar las cuentas de servicio de una organización o proyecto diferente.
Rotar una clave secreta de cuenta de servicio
Para emitir un nuevo secreto de cliente para una cuenta de servicio, ejecute el siguiente comando:
agentengine service-account rotate <client-id> [--org-id <id>] [--project-id <id>] [--secret-expires-in <duration>]
El comando genera la nueva clave secreta del cliente en texto plano. La clave secreta anterior permanece válida durante un máximo de siete días o hasta su fecha de caducidad, lo que ocurra primero.
Tip
Para revocar inmediatamente la clave secreta anterior, cámbiela por segunda vez o elimine la cuenta de servicio.
Eliminar una cuenta de servicio
Para eliminar permanentemente una cuenta de servicio, ejecute el siguiente comando:
agentengine service-account delete <client-id> [--org-id <id>] [--project-id <id>]
Tras eliminar una cuenta de servicio, esta ya no podrá solicitar tokens de acceso, y cualquier token que posea dejará de funcionar en su próximo uso.
Administrar versiones de la CLI
Esta sección describe los comandos que puede utilizar para recuperar y actualizar su versión de la interfaz de línea de comandos (CLI).
Compruebe la versión de la CLI
El comando agentengine version imprime la versión de lanzamiento de la CLI, la confirmación de Git a partir de la cual se compiló el binario y las etiquetas de imagen de contenedor predeterminadas utilizadas por la pila de desarrollo local.
Para obtener la versión de la CLI, ejecute el siguiente comando:
agentengine version [--json]
Tip
Por defecto, este comando imprime una cadena de texto plano legible para humanos. Pase el indicador --json para imprimir un objeto JSON estable y legible por máquina que incluya los campos schema_version, status, version, git_commit, build y el campo images incrustado.
La salida es similar a la siguiente:
0.1.94-alpha (commit: <hash>) image registry: ECR runner-base: <registry>/runner-base:0.1.94-alpha runner-base-typescript-langgraph: <registry>/runner-base-typescript-langgraph:0.1.94-alpha playground-ui: <registry>/playground-ui:0.1.94-alpha orchestrator: <registry>/orchestration-engine:<version> memory-server: <registry>/memory-server:<version>
Actualizar la CLI
El comando agentengine self-update descarga el último recurso de lanzamiento compatible con su sistema operativo y arquitectura actuales, verifica la suma de comprobación SHA-256 de ese recurso y reemplaza el binario existente en su ruta de instalación actual.
Cuando inicias sesión en Atlas Agent Engine, la interfaz de línea de comandos (CLI) recupera la lista de versiones disponibles desde la puerta de enlace API de la plataforma.
Nota
El comando agentengine self-update descarga el nuevo binario en el directorio donde se encuentra el binario actual, por lo que debe tener permisos de escritura en ese directorio. Si no tiene permisos de escritura, anteponga sudo al comando o reinstale la interfaz de línea de comandos en un directorio diferente.
Para actualizar la interfaz de línea de comandos (CLI), ejecute el siguiente comando:
agentengine self-update [--force] [--auto[=true|false]]
La siguiente tabla describe las banderas disponibles:
Flag | Descripción |
|---|---|
| Descargue e instale la última versión, incluso si la interfaz de línea de comandos (CLI) actual ya está actualizada. |
| Habilite las actualizaciones automáticas antes de que se ejecuten la mayoría de los comandos. Pase el indicador |
Al ejecutar la mayoría de los comandos agentengine, la CLI imprime un aviso de una línea en stderr si hay una versión más reciente disponible. La CLI realiza la comprobación de actualizaciones una vez cada 24 horas. Para desactivar la comprobación por completo, configure la variable de entorno AGENTENGINE_NO_UPDATE_CHECK=1 en su intérprete de comandos.
Nota
En Windows, el comando agentengine self-update descarga el binario actualizado para su reemplazo manual porque un agentengine.exe en ejecución no se puede reemplazar en el mismo lugar.
Límites de recursos
Cada organización puede tener hasta 100 cuentas de servicio de organización. Si supera este límite, la solicitud devuelve un error 400 Bad Request con un mensaje RESOURCE_LIMIT_EXCEEDED.
La siguiente tabla enumera los límites de recursos para cada proyecto:
Resource | Limit |
|---|---|
Espacios de trabajo | 25 |
API keys | 100 |
Proveedores de credenciales | 100 |
Cuentas de servicio de proyectos | 100 |
Si supera un límite de recursos, la solicitud devuelve un error 400 Bad Request con un mensaje RESOURCE_LIMIT_EXCEEDED.
Para consultar todas las limitaciones que se aplican durante la versión preliminar pública, consulte Limitaciones del motor del agente de MongoDB Atlas.
Próximos pasos
Una vez configuradas tus organizaciones, proyectos y espacios de trabajo, puedes crear y ejecutar tu agente localmente. Para saber cómo hacerlo, consulta la sección «Crea tu entorno local».