agent-image

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

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: artifact-repos-python, artifact-repos-typescript -->

Build the Agent Image

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 build the agent image from the CLI. The build process uploads your agent source code to cloud storage and starts a remote build job that produces a Docker image.

Build Command Syntax and Options

Use the following syntax to build the agent image:

agentengine build [--label <str>] [--no-wait] [--context <name>] [--workspace <name>] [--all] [--json] [--upload-build-secrets]

This command packages the agent source as a tar.gz file, uploads it to a Simple Storage Service (S3) bucket through a presigned URL, and then starts an AWS CodeBuild job to produce a Docker image in the Elastic Container Registry (ECR).

Command Flags

When building the agent image, you can use the following optional flags:

Archive Contents

Before uploading your agent source, the CLI builds the tar.gz archive referenced in the preceding section. This section describes which directory the archive packages and which files it excludes.

Archive Root

By default, the agentengine build command packages only the agent directory. The command packages from the workspace or monorepo root instead if the workspace or monorepo configuration file lists the agent directory as a member. The listing requirement depends on the workspace type, as described in the following table:

To find the workspace or monorepo root, the CLI searches upward through the agent directory's parent directories for a file that marks a root. The search stops at the git repository's root directory and never continues into your home directory, so the command cannot package files from outside the repository.

If the agent directory is a git submodule or a linked worktree, the search does not stop at that boundary. The search continues into the parent repository, and the membership rules described in the preceding table determine which directory the command packages from.

Excluded Files

A project-level .agentengineignore file at the archive root controls which files the CLI packs into the archive. This file uses standard .gitignore syntax, including globs, **, and ! negation. The agentengine init command creates the file with the following default patterns:

• .git

• .venv*

• __pycache__

• .pytest_cache

• .mypy_cache

• .ruff_cache

• node_modules

• dist

• build

• .agentengine

• *.pyc

• .env

• .env.*

• .DS_Store

• *.pem

• *.key

If the file is absent, the CLI uses the same default patterns as the agentengine init command.

The following files are always excluded, and you cannot use a ! negation in the .agentengineignore file to override that:

• .env and .env.* files

• *.pem and *.key files

• Common OpenSSH private keys: id_rsa, id_dsa, id_ecdsa, id_ed25519, and id_ed448

• .git directory

• Cloud and tooling credential stores: .aws, .kube, .ssh, .netrc, .git-credentials, .azure, .config/gh, .docker/config.json, and .config/gcloud

A project-level .npmrc file is not part of this set of excluded files. The platform build reads the .npmrc file from the archive to resolve declared private npm registries. The build also reads pyproject.toml to resolve declared private PyPI registries. To learn how to configure private registry credentials for the build, see [Private Artifact Repositories.](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-build-artifact-repositories

Warning:

Because the build includes your .npmrc and pyproject.toml files, do not store registry tokens or credentials in those files. Instead, declare credentials in artifact_repositories in your agent.yaml file. To learn more, see [Private Artifact Repositories.](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-build-artifact-repositories

Private Artifact Repositories

If your agent depends on packages hosted in private artifact repositories such as AWS CodeArtifact, declare those repositories in the artifact_repositories block of your agent.yaml file. The Atlas Agent Engine resolves the registry credentials at build time from the Atlas Agent Engine secret named in each entry and injects them into the build environment. The credentials are not stored in your source files and are not exposed to running pods. If you do not declare any repositories, the Atlas Agent Engine resolves dependencies from public registries using your existing tooling configuration, unchanged.

Registry URLs live in your project tooling, not in agent.yaml. For Python agents, declare each private index in a [[tool.uv.index]] entry in pyproject.toml. The name field in agent.yaml must match the index name. For TypeScript agents, declare each private scoped registry in an .npmrc file. Set npm_scope in agent.yaml to the scope that maps to the registry. The following examples show the matching tooling file and agent.yaml entry for each language:

Python

[[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

To learn about the full artifact_repositories schema, see [Agent YAML Schema.](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract-yaml

Before the build starts, the Atlas Agent Engine validates declared repositories against your project tooling. If validation fails, the build stops with an actionable error. To catch issues before building, run agentengine agent validate locally. To learn more, see [Validate Configuration.](https://www.mongodb.com/docs/agentengine/build/run-local.md#std-label-agent-engine-build-validate

Each declared artifact_repositories[].secret must exist at the declared scope in your Atlas Agent Engine secrets before the build starts. For short-lived registry tokens that expire between builds, use the --upload-build-secrets flag to upload each secret from an environment variable of the same name. The following example mints an AWS CodeArtifact token and uploads it in one build command:

export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \
  --domain my-domain --query authorizationToken --output text)"
agentengine build --upload-build-secrets

For long-lived credentials, set each secret once with agentengine secret set and build without the flag. To learn more about provisioning secrets, see [Provision Cloud Secrets.](https://www.mongodb.com/docs/agentengine/deploy/provision-secrets.md#std-label-agent-engine-deploy-provision-secrets

Build Management Commands

The following table describes the build management commands you can use to monitor and manage your agent builds:

Tip: Command Flags

Each build management command accepts the --workspace-id and --project-id flags to specify the workspace and project. If not provided, the CLI reads these values from the .agentengine/state.json file.

Promote a Build

When you promote a build, the Atlas Agent Engine copies a tested build image from one workspace into another workspace without rebuilding the image from source. Because the promoted image is byte-identical to the source image, the agent that runs in the target workspace is the same one you tested in the source workspace.

Note:

The Atlas Agent Engine UI build detail page does not show a Build Logs section for a promoted build, because a promotion reuses an existing image rather than running a new build.

By default, the source build must have at least one successful deployment, which confirms that the image is deployable. To bypass this requirement, use the --force flag.

Use the following syntax to promote a build:

agentengine build promote <source_build_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--context <name>] [--force] [--yes] [--json]

The CLI identifies the source build by ID and resolves it within your current organization. You cannot promote a build to a project in a different organization.

When promoting a build, you can use the following flags:

Warning:

Promotion does not copy runtime or project configuration from the source workspace. Secrets, Atlas connection configuration, and egress policies do not transfer to the target workspace. Before you deploy the promoted build, configure these settings on the target project and workspace.

After the promotion succeeds, deploy the promoted build in the target workspace. To learn how to deploy a build, see [Deploy Your Build.](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build

Example

The following command builds the agent image without polling for the build status and then lists the build information:

agentengine build --no-wait && agentengine build list

If the build is successful, the command output resembles the following example:

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

Next Steps

After building the agent image, you can deploy the agent to production. To learn how to deploy the agent, see the [Deploy Your Build](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build guide.