Visão geral
Neste guia, você pode aprender como configurar um monorepo para gerenciar vários agentes de um único repositório. Um monorepo usa um arquivo agent.yaml na raiz do repositório que lista o nome de cada agente e o caminho do subdiretório. A CLI detecta automaticamente o formato monorepo quando a raiz agent.yaml contém uma chave agents em vez de uma chave entrypoint.
Antes de configurar um monorepo, certifique-se de instalar e autenticar o MongoDB Atlas Agent Engine.
Estrutura de Diretórios
Um monorepo requer um agent.yaml raiz e um único agente agent.yaml no subdiretório de cada agente. O exemplo a seguir mostra a estrutura de arquivo de um monorepo contendo dois 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
Configure o Monorepo
As etapas a seguir mostram como configurar os arquivos de monorepo necessários e inicializar o monorepo.
Configure o arquivo raiz agent.yaml.
Crie um arquivo agent.yaml na raiz do repositório. Use uma lista agents para declarar o nome e o caminho de cada agente. Não inclua um campo entrypoint no arquivo raiz.
Cada entrada na lista agents exige os seguintes campos:
Campo | Obrigatório | Descrição |
|---|---|---|
| sim | Identificador do agente. Configure este campo para um valor alfanumérico minúsculo com hífens. Não use hífens iniciais ou finais e certifique-se de que o nome seja exclusivo dentro do monorepo. |
| sim | Caminho relativo da raiz do repositório até o diretório do agente. O caminho não pode ser absoluto ou escapar da raiz do repositório usando |
O seguinte arquivo de amostra agent.yaml configura um monorepo com dois agentes denominados chat e search:
agents: - name: chat path: agents/chat - name: search path: agents/search
Configure o arquivo agent.yaml de cada agente.
Em cada subdiretório do agente , crie um arquivo agent.yaml que usa o formato de agente único. O arquivo deve incluir um campo entrypoint que aponta para o objeto de aplicação do agente e um campo sandboxes que define o que as ferramentas do agente executam e quais segredos eles podem acessar. Para ver todos os campos disponíveis, consulte a lista de campos .yaml do agente no guia Como criar um projeto.
O seguinte arquivo de amostra agent.yaml configura o agentechat :
entrypoint: chat_agent.graph:app name: chat sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
O seguinte arquivo de amostra agent.yaml configura o agentesearch :
entrypoint: search_agent.graph:app name: search sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []
A sandbox agent é para ferramentas que devem ser executadas no agente, como ferramentas de interrupção. A sandbox tool é para ferramentas executadas separadamente do agente. Liste as ferramentas para cada sandbox em seu campotools . Configure o acesso secreto no camposecrets de cada sandbox. Substitua ["*"] por uma lista de nomes de segredos específicos quando a sandbox deve receber somente segredos selecionados.
Importante
Cada subdiretório também deve conter um arquivo pyproject.toml que declara as dependências do Python do agente. O arquivo deve definir a chave [project].name e incluir uma tabela [build-system] que define as chaves requires e build-backend. Para gerar um arquivo que atenda a esses requisitos, execute uv init --package no subdiretório do agente .
Crie os arquivos .env.
Um monorepo usa dois tipos de arquivos .env: um .env raiz para segredos que a pilha de desenvolvimento local compartilha em todos os agentes e um .env por agente em cada subdiretório do agente para os segredos do próprio agente. Crie-os manualmente antes de iniciar o ambiente local.
Na raiz do repositório, crie um arquivo .env que contenha os segredos que o mecanismo de orquestração e cada agente consome durante o desenvolvimento local, conforme mostrado no exemplo a seguir:
MONGODB_URI=<your-mongodb-connection-string> <PROVIDER>_API_KEY=<your-api-key>
Em cada subdiretório do agente , crie um arquivo .env para os segredos que somente esse agente consome, como chaves de API específicas do agente.
Importante
Não confie seus segredos no controle de versão.
Inicialize o monorepo.
Execute o seguinte comando a partir da raiz do repositório para registrar cada agente e gerar arquivos de desenvolvimento local:
agentengine init
O CLI detecta o formato monorepo automaticamente e registra cada agente listado na raiz agent.yaml como um espaço de trabalho separado no Atlas Agent Engine.
Migrar de um único agente para um Monorepo
Para converter um repositório de agente único existente em um monorepo, mova seus arquivos de agente para um subdiretório e reinicialize o projeto.
As etapas a seguir mostram como migrar para um monorepo.
Crie o subdiretório do agente e mova seus arquivos.
Execute os seguintes comandos para criar um subdiretório para seu agente e mover os seguintes arquivos para ele:
mkdir -p agents/<agent-name> mv agent.yaml pyproject.toml .env src/ agents/<agent-name>/
Substitua o espaço reservado <agent-name> pelo nome do seu agente.
Observação
Estrutura de Diretórios
O exemplo anterior cria um subdiretório no diretório agents/. Você pode usar uma estrutura de diretório diferente, mas o valor path na raiz agent.yaml deve especificar o caminho relativo correspondente.
Mova o diretório .agentengine/ para o subdiretório do agente .
Quando você executa o agentengine init, a CLI gera um diretório .agentengine/ oculto que contém o estado de registro do espaço de trabalho no arquivo .agentengine/state.json. Em um monorepo, cada agente exige seu próprio diretório .agentengine/.
Execute o seguinte comando para mover o diretório existente para o subdiretório do agente , que preserva o registro do espaço de trabalho do agente:
mv .agentengine/ agents/<agent-name>/.agentengine/
Importante
Se você não mover o diretório .agentengine/, executar agentengine init registrará um novo workspace para seu agente e tornará órfão o registro de workspace anterior.
Crie o arquivo raiz agent.yaml.
Na raiz do repositório, crie um novo agent.yaml que liste seu agente usando a chave agents, conforme descrito na seção anterior Configurar o Monorepo.
Inicialize o monorepo.
Execute o seguinte comando a partir da raiz do repositório para inicializar o monorepo:
agentengine init
A CLI detecta o formato monorepo, gera artefatos dev-container por agente e registra todos os agentes que ainda não tenham um arquivo .agentengine/state.json. Os agentes com state.json existente mantêm o registro do workspace atual.
Próximos passos
Depois de configurar seu monorepo, você pode criar e implementar seus agentes. Para saber como, consulte os seguintes guias: