Provision Cloud Secrets

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

Provision Cloud Secrets

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 perform the first step in the deployment process: setting secrets for deployed workspaces in the AWS Secrets Manager. These secrets are used to authenticate and access the resources required for cloud deployment.

Secret Syntax and Options

Use the following syntax to set secrets in the CLI, which saves them in the AWS Secrets Manager:

agentengine secret set NAME VALUE [--description <text>] [--sync] [--project-scope | --workspace-scope] [--org-id <id>] [--project-id <id>] [--workspace-id <id>]

The following table lists the secret values that are required for some or all deployments:

Secret Description
MONGODB_URI The connection string for your MongoDB deployment. This key is required for all deployments.
LLM Key The private key for your LLM provider credentials. The available keys are ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, and CEREBRAS_API_KEY. You must set at least one of these values.
VOYAGE_API_KEY The private key for your Voyage AI credentials. This key is required if features.memory is set to true in your agent.yaml file. It is also required for all TypeScript agent deployments.
MONGOMEM_DB_NAME Optional. The MongoDB database name the memory server writes to. Defaults to mdb_memory_<project-id>. Set this secret to customize the database name used for memory storage.

Tip:

If you run agentengine atlas setup, the CLI sets the MONGODB_URI and VOYAGE_API_KEY secrets automatically.

If you configure other secrets, ensure that the secret names meet the following requirements:

  • Use only uppercase letters, digits, and underscores

  • Do not start values with AGENTIC_PLATFORM_, because this prefix is reserved for platform-injected variables

  • Do not use the following reserved names: RUNNER_MODE, APP_ID, ORG_ID, GROUP_ID, AER_ENDPOINT, or TOOL_ENDPOINT

  • Use a maximum of 128 characters

If your agent.yaml file declares artifact_repositories entries, set each entry's secret value by using agentengine secret set with the same naming rules. To learn more, see [Private Artifact Repositories.](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-build-artifact-repositories

Command Flags

When setting secrets, you can use the following optional flags:

Flag Description
--description Human-readable description of the secret.
--sync Syncs the secrets to your deployments after setting them.
--project-scope Targets project-scoped secrets, shared across all workspaces in the project. This is the default.
--workspace-scope Targets a workspace-scoped secret instead of a project-scoped secret.
--org-id <id> Targets a specific organization ID directly.
--project-id <id> Targets a specific project ID directly.
--workspace-id <id> Targets a specific workspace ID directly.

Delete a Secret

Use the following syntax to permanently delete a secret from the AWS Secrets Manager:

agentengine secret delete NAME [--yes] [--project-scope | --workspace-scope] [--org-id <id>] [--project-id <id>] [--workspace-id <id>]

Before asking you to confirm, the CLI looks up the target organization, project, and, for workspace-scoped secrets, the workspace from the server. The confirmation prompt shows their names and IDs so that you see the resolved destination rather than the values in your local files. If a name lookup fails, the prompt shows only the ID.

To skip the confirmation prompt in a script, use the --yes flag. The CLI still prints the target. Without the --yes flag, the command fails in a non-interactive environment instead of deleting the secret.

Warning:

You cannot undo a secret deletion. Deployments that read the secret do not succeed until you set the secret again.

Limits on Secrets

The platform enforces the following limits on secrets:

Scope Limit
Per project 100
Per workspace 100

If you exceed a secret limit, the request returns a 400 Bad Request error with a RESOURCE_LIMIT_EXCEEDED message.

To review all limitations that apply during Public Preview, see [MongoDB Atlas Agent Engine Limitations.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations

Configure Atlas Network Access

If your MONGODB_URI points to an Atlas cluster, run the agentengine atlas setup command. The CLI automatically adds the Atlas Agent Engine data plane IP addresses to the cluster's IP access list so that the deployed agent can connect to your cluster.

For more information on Atlas setup, see the [Set Up Atlas Resources](https://www.mongodb.com/docs/agentengine/deploy/atlas-setup.md#std-label-agent-engine-deploy-atlas-setup page.

Configuration Example

The following example shows how to configure your MongoDB URI, Anthropic API key, and Voyage API key from the CLI. To set these secrets, run the following commands from your terminal:

agentengine secret set MONGODB_URI 'mongodb+srv://example.mongodb.net'
agentengine secret set ANTHROPIC_API_KEY sk-ant-api-test-key
agentengine secret set VOYAGE_API_KEY sk-voy-api-test-key

Then, run the following command to sync the secrets to all running deployments:

agentengine secret sync

Alternatively, you can set and sync your secrets in a single command by using the --sync flag, as shown in the following example:

agentengine secret set MONGODB_URI 'mongodb+srv://example.mongodb.net' --sync

Next Steps

After you provision secrets, declare which secrets each tool can access in your agent.yaml file. To learn more, see [Agent YAML Schema](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract-yaml in the Agent Contract Reference.

To prepare for cloud deployment, build the agent image. To learn more, see the [Build the Agent Image](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-deploy-agent-image guide.