Set Up a Monorepo

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Set Up a Monorepo

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

Overview

In this guide, you can learn how to set up a monorepo to manage multiple agents from a single repository. A monorepo uses an agent.yaml file at the repository root that lists each agent's name and subdirectory path. The CLI automatically detects the monorepo format when the root agent.yaml contains an agents key instead of an entrypoint key.

Before setting up a monorepo, ensure that you [install and authenticate](https://www.mongodb.com/docs/agentengine/build/install-authenticate.md#std-label-agent-engine-set-up-install-authenticate the MongoDB Atlas Agent Engine.

Directory Structure

A monorepo requires a root agent.yaml and a single-agent agent.yaml in each agent's subdirectory. The following example shows the file structure for a monorepo containing two agents:

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 the Monorepo

The following steps show how to configure the required monorepo files and initialize the monorepo.

1. Configure the root agent.yaml file.

Create an agent.yaml file at the repository root. Use an agents list to declare each agent's name and path. Do not include an entrypoint field in the root file.

Each entry in the agents list requires the following fields:

The following sample agent.yaml file configures a monorepo with two agents named chat and search:

yaml agents: - name: chat path: agents/chat - name: search path: agents/search

1. Configure each agent's agent.yaml file.

In each agent subdirectory, create an agent.yaml file that uses the single-agent format. The file must include an entrypoint field that points to the agent's application object, and a sandboxes field that defines what the agents tools run and which secrets they can access. To view all available fields, see the [list of agent.yaml fields](https://www.mongodb.com/docs/agentengine/build/create-project.md#std-label-agent-engine-agent-yaml-config in the Create a Project guide.

The following sample agent.yaml file configures the chat agent:

yaml entrypoint: chat_agent.graph:app name: chat sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []

The following sample agent.yaml file configures the search agent:

yaml entrypoint: search_agent.graph:app name: search sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: []

The agent sandbox is for tools that must run on the agent, such as interrupt tools. The tool sandbox is for tools that run separately from the agent. List the tools for each sandbox under its tools field. Configure secret access under each sandbox's secrets field. Replace [“*”] with a list of specific secret names when the sandbox should receive only selected secrets.

Important:

Each subdirectory must also contain a pyproject.toml file that declares the agent's Python dependencies. The file must set the [project].name key and include a [build-system] table that sets the requires and build-backend keys. To generate a file that meets these requirements, run uv init --package in the agent subdirectory.

1. Create the .env files.

A monorepo uses two types of .env files: a root .env for secrets that the local dev stack shares across all agents, and a per-agent .env in each agent subdirectory for that agent's own secrets. Create them manually before you start the local environment.

In the repository root, create a .env file that contains the secrets the orchestration engine and every agent consume during local development, as shown in the following example:

none MONGODB_URI=<your-mongodb-connection-string> <PROVIDER>_API_KEY=<your-api-key>

In each agent subdirectory, create a .env file for the secrets that only that agent consumes, such as agent-specific API keys.

Important:

Do not commit your secrets to version control.

1. Initialize the monorepo.

Run the following command from the repository root to register each agent and generate local development files:

bash agentengine init

The CLI detects the monorepo format automatically and registers each agent listed in the root agent.yaml as a separate workspace on the Atlas Agent Engine.

Migrate from a Single Agent to a Monorepo

To convert an existing single-agent repository to a monorepo, move your agent files into a subdirectory and re-initialize the project.

The following steps show how to migrate to a monorepo.

1. Create the agent subdirectory and move your files.

Run the following commands to create a subdirectory for your agent and move the following files into it:

bash mkdir -p agents/<agent-name> mv agent.yaml pyproject.toml .env src/ agents/<agent-name>/

Replace the <agent-name> placeholder with the name of your agent.

Note: Directory Structure

The preceding example creates a subdirectory in the agents/ directory. You can use a different directory structure, but the path value in the root agent.yaml must specify the corresponding relative path.

1. Move the .agentengine/ directory to the agent subdirectory.

When you run agentengine init, the CLI generates a hidden .agentengine/ directory that contains workspace registration state in the .agentengine/state.json file. In a monorepo, each agent requires its own .agentengine/ directory.

Run the following command to move the existing directory into the agent subdirectory, which preserves the agent's workspace registration:

bash mv .agentengine/ agents/<agent-name>/.agentengine/

Important:

If you do not move the .agentengine/ directory, running agentengine init registers a new workspace for your agent and orphans the previous workspace registration.

1. Create the root agent.yaml file.

In the repository root, create a new agent.yaml that lists your agent using the agents key, as described in the previous [Configure the Monorepo](https://www.mongodb.com/docs/agentengine/manage/monorepo.md#std-label-agent-engine-monorepo-agent-yaml section.

1. Initialize the monorepo.

Run the following command from the repository root to initialize the monorepo:

bash agentengine init

The CLI detects the monorepo format, generates per-agent dev-container artifacts, and registers any agents that don’t already have an .agentengine/state.json file. Agents with an existing state.json retain their current workspace registration.

Next Steps

After setting up your monorepo, you can build and deploy your agents. To learn how, see the following guides:

• [Build the Agent Image](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-deploy-agent-image

• [Deploy Your Build](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build