Overview
En esta guía, aprenderá a configurar un monorepo para administrar varios agentes desde un único repositorio. Un monorepo utiliza un archivo agent.yaml en la raíz del repositorio que enumera el nombre de cada agente y la ruta del subdirectorio. La interfaz de línea de comandos (CLI) detecta automáticamente el formato de monorepo cuando el archivo raíz agent.yaml contiene una clave agents en lugar de una clave entrypoint.
Antes de configurar un monorepo, asegúrese de instalar y autenticar el motor del agente de MongoDB Atlas.
Estructura de directorios
Un monorepo requiere un directorio raíz agent.yaml y un directorio de agente único agent.yaml en el subdirectorio de cada agente. El siguiente ejemplo muestra la estructura de archivos para un monorepo que contiene dos agentes:
my-repo/ ├── agent.yaml # Monorepo root file ├── .env # Shared secrets for the local dev stack ├── pyproject.toml # Shared Python dependencies (optional) ├── agents/ │ ├── chat/ │ │ ├── agent.yaml # Per-agent configuration file with entrypoint │ │ ├── pyproject.toml │ │ ├── .env # Per-agent secrets │ │ └── src/ │ └── search/ │ ├── agent.yaml # Per-agent configuration file with entrypoint │ ├── pyproject.toml │ ├── .env # Per-agent secrets │ └── src/ └── shared/ # Shared libraries, included in all builds
Configurar el Monorepo
Los siguientes pasos muestran cómo configurar los archivos necesarios del monorepo e inicializarlo.
Configure el archivo raíz agent.yaml.
Crea un archivo agent.yaml en la raíz del repositorio. Usa una lista agents para declarar el nombre y la ruta de cada agente. No incluyas un campo entrypoint en el archivo raíz.
Cada entrada en la lista agents requiere los siguientes campos:
Campo | Requerido | Descripción |
|---|---|---|
| Sí | Identificador del agente. Configure este campo con un valor alfanumérico en minúsculas con guiones. No utilice guiones al principio ni al final, y asegúrese de que el nombre sea único dentro del monorepo. |
| Sí | Ruta relativa desde la raíz del repositorio hasta el directorio del agente. La ruta no puede ser absoluta ni escapar de la raíz del repositorio usando |
El siguiente archivo de ejemplo agent.yaml configura un monorepo con dos agentes llamados chat y search:
agents: - name: chat path: agents/chat - name: search path: agents/search
Configure el archivo agent.yaml de cada agente.
En cada subdirectorio del agente, cree un archivo agent.yaml con formato de agente único. Este archivo debe incluir un campo entrypoint que apunte al objeto de aplicación del agente y un campo sandboxes que defina las herramientas que ejecutan los agentes y los secretos a los que pueden acceder. Para ver todos los campos disponibles, consulte la lista de campos de agent.yaml en la guía «Crear un proyecto».
El siguiente archivo de ejemplo agent.yaml configura el agente chat:
entrypoint: chat_agent.graph:app name: chat sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
El siguiente archivo de ejemplo agent.yaml configura el agente search:
entrypoint: search_agent.graph:app name: search sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
El entorno aislado agent se utiliza para herramientas que deben ejecutarse en el agente, como las herramientas de interrupción. El entorno aislado tool se utiliza para herramientas que se ejecutan de forma independiente del agente. Enumere las herramientas de cada entorno aislado en su campo tools. Configure el acceso a secretos en el campo secrets de cada entorno aislado. Reemplace ["*"] con una lista de nombres de secretos específicos cuando el entorno aislado solo deba recibir secretos seleccionados.
Importante
Cada subdirectorio debe contener un archivo pyproject.toml que declare las dependencias de Python del agente. Este archivo debe establecer la clave [project].name e incluir una tabla [build-system] que establezca las claves requires y build-backend. Para generar un archivo que cumpla con estos requisitos, ejecute uv init --package en el subdirectorio del agente.
Crea los archivos .env.
Un monorepo utiliza dos tipos de archivos .env: un archivo raíz .env para los secretos que el entorno de desarrollo local comparte entre todos los agentes, y un archivo .env por agente en cada subdirectorio de agente para los secretos propios de ese agente. Créelos manualmente antes de iniciar el entorno local.
En la raíz del repositorio, cree un archivo .env que contenga los secretos que el motor de orquestación y cada agente consumen durante el desarrollo local, como se muestra en el siguiente ejemplo:
MONGODB_URI=<your-mongodb-connection-string> <PROVIDER>_API_KEY=<your-api-key>
En cada subdirectorio de agente, cree un archivo .env para los secretos que solo ese agente consume, como las claves API específicas del agente.
Importante
No confíes tus secretos al control de versiones.
Inicializa el monorepo.
Ejecute el siguiente comando desde la raíz del repositorio para registrar cada agente y generar archivos de desarrollo locales:
agentengine init
La interfaz de línea de comandos (CLI) detecta automáticamente el formato monorepo y registra cada agente listado en la raíz agent.yaml como un espacio de trabajo separado en el Atlas Agent Engine.
Migrar de un agente único a un monorepositorio
Para convertir un repositorio de un solo agente existente en un monorepo, mueva los archivos de su agente a un subdirectorio y vuelva a inicializar el proyecto.
Los siguientes pasos muestran cómo migrar a un monorepo.
Crea el subdirectorio del agente y mueve tus archivos.
Ejecute los siguientes comandos para crear un subdirectorio para su agente y mueva los siguientes archivos a él:
mkdir -p agents/<agent-name> mv agent.yaml pyproject.toml .env src/ agents/<agent-name>/
Reemplace el marcador de posición <agent-name> con el nombre de su agente.
Nota
Estructura de directorios
El ejemplo anterior crea un subdirectorio en el directorio agents/. Puede utilizar una estructura de directorios diferente, pero el valor path en la raíz agent.yaml debe especificar la ruta relativa correspondiente.
Mueva el directorio .agentengine/ al subdirectorio del agente.
Al ejecutar agentengine init, la CLI genera un directorio oculto .agentengine/ que contiene el estado de registro del espacio de trabajo en el archivo .agentengine/state.json. En un monorepo, cada agente requiere su propio directorio .agentengine/.
Ejecute el siguiente comando para mover el directorio existente al subdirectorio del agente, lo que conserva el registro del espacio de trabajo del agente:
mv .agentengine/ agents/<agent-name>/.agentengine/
Importante
Si no mueve el directorio .agentengine/, al ejecutar agentengine init se registra un nuevo espacio de trabajo para su agente y se deja huérfano el registro del espacio de trabajo anterior.
Crea el archivo raíz agent.yaml.
En la raíz del repositorio, cree un nuevo agent.yaml que liste su agente usando la clave agents, como se describe en la sección anterior Configurar el Monorepo.
Inicializa el monorepo.
Ejecute el siguiente comando desde la raíz del repositorio para inicializar el monorepo:
agentengine init
La interfaz de línea de comandos (CLI) detecta el formato monorepo, genera artefactos dev-container por agente y registra los agentes que aún no tienen un archivo .agentengine/state.json. Los agentes con un archivo state.json existente conservan su registro de espacio de trabajo actual.
Próximos pasos
Tras configurar tu monorepo, puedes compilar e implementar tus agentes. Para saber cómo hacerlo, consulta las siguientes guías: