MongoDB Atlas Agent Engine Limitations

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

MongoDB Atlas Agent Engine Limitations

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

This page lists the limitations that apply to the MongoDB Atlas Agent Engine during Public Preview. Each limitation also appears on the page that covers the affected feature.

Important: Public Preview Limitations

The MongoDB Atlas Agent Engine is in Public Preview. MongoDB does not recommend that you run production workloads on the platform, and does not provide service-level agreements (SLAs) or service-level objectives (SLOs) for platform availability during Public Preview.

Scaling and Concurrency

The Atlas Agent Engine does not autoscale agent deployments. The scaling.replicas field in the agent.yaml file sets a fixed sandbox count, and each session reserves one agent sandbox and one tool sandbox for its lifetime. As a result, this field sets the number of sessions that a deployment can serve concurrently.

The scaling.replicas field accepts a value from 1 to 512 and defaults to 4 when you omit it. When every sandbox is reserved, a new invoke request fails with a pool full error.

The 512 concurrent sandbox limit applies to the Orchestration Engine, which is scoped to a project and can serve more than one agent. The scaling.replicas values of all agents in a project count toward the same ceiling. To run more sandboxes than one project allows, distribute your agents across multiple projects.

The Orchestration Engine also limits the number of concurrent requests that it can serve. As a result, a project might not be able to run 512 agents at the same time. To learn about this limit, see [Orchestration Engine Capacity.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations-oe-capacity

If you have capacity issues, choose one of the following options:

A session ID must be 1 to 128 characters long and can contain letters, numbers, underscores (_), and hyphens (-). Pass the session ID in the --session option of the agentengine invoke command, or in the X-Session-ID header of an API request.

Because the Atlas Agent Engine snapshots scaling values at build time, you must build and deploy the agent again for a change to take effect. To learn more about these fields, see [Agent Contract Reference.](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract

Orchestration Engine Capacity

An Orchestration Engine can serve up to 50 concurrent requests per second across all agents in its project.

If your workload requires higher concurrency, create a new project and deploy the additional agents in that project, or contact MongoDB Support for assistance.

Compute Resources

You can't configure the compute resources for an agent or for the Orchestration Engine. Each agent has 0.5 vCPU and 2 GB of memory, and each Orchestration Engine has 0.5 vCPU and 512 MB of memory. These values are fixed and don't change with your workload.

If your workload requires different resource allocations, contact MongoDB Support for assistance.

Agent Builds

The platform enforces the following build limits for each project:

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

To learn more about building and deploying an agent, see [Deploy Your Build.](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build

GitHub App Integration

The Atlas Agent Engine GitHub App is not available during Public Preview. You can't install the app on your GitHub organization, so you can't use the Connect Repository flow in the Atlas Agent Engine UI, create a workspace from a GitHub repository, or recieve GitHub App webhook events.

To create and deploy a workspace during Public Preview, run the agentengine deploy command from a local clone of your repository instead.

To learn how to deploy from a local clone, see [Deploy Your Build.](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build

Secrets

The platform enforces the following limits on secrets:

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

To learn how to set, read, and delete secrets, see [Provision Cloud Secrets.](https://www.mongodb.com/docs/agentengine/deploy/provision-secrets.md#std-label-agent-engine-deploy-provision-secrets

Organization, Project, and Workspace Resources

Each organization can have up to 100 organization service accounts. If you exceed this limit, the request returns a 400 Bad Request error with a RESOURCE_LIMIT_EXCEEDED message.

The following table lists the resource limits for each project:

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

To learn how to manage these resources, see [View Organizations](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-org and [Manage Organizations, Projects, and Workspaces.](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-project

Public API Stability

Note: Public Preview

The Atlas Agent Engine public API is subject to change during Public Preview. Endpoints, request formats, and response formats might change without a backward-compatible migration path.

To maintain compatibility with future API versions, see the [pinning API contracts](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-api-contract-pinning section.

Pin an API Contract

The Atlas Agent Engine API publishes versioned contracts. To keep your integration compatible when a new version ships, pin a specific contract version by including the version in the Accept header of every request and follow-up read. Without a version in the header, requests receive the latest published contract, which can change over time. The Atlas Agent Engine supports the 2026-09-20-preview contract version.

Pinning Behavior

When you pin a contract version, the Atlas Agent Engine returns the request and response shapes defined in that version. A pinned version is a per-request selection, not account-level or first-use behavior.

Pinning the API contract doesn't freeze:

• Agent logic or agent deployments

• Stored data (sessions, memory, traces)

• Permissions and roles

• CLI releases

• SDK releases

• Model versions

Pinning preserves only the API request and response shapes.

Pinned Request Examples

The following examples show unpinned and pinned requests to the invocation API.

Unpinned Request

curl --include \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -d '{"message": "Hello, agent!"}'

The response resembles the following output:

HTTP/2 200
content-type: application/json; charset=utf-8

{
  "success": true,
  "response": "Agent response",
  "execution_id": "9f8ba6a9-9c4d-44d7-8118-9300795b57db",
  "status": "completed"
}

Pinned to a Specific Version

curl --include \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.agent-engine-<VERSION>+json" \
  -H "Content-Type: application/json" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -d '{"message": "Hello, agent!"}'

The response resembles the following output:

HTTP/2 200
content-type: application/vnd.agent-engine-<VERSION>+json; charset=utf-8

{
  "success": true,
  "response": "Agent response",
  "execution_id": "a0ad6e8b-60f1-47d4-8d25-fdd2e4d44bcf",
  "status": "completed"
}

The response body is identical in both cases. The content-type header reflects the pinned version when a selector is provided. All responses include a vary: Accept header.

Pinned Streaming Request

curl -N --include \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: text/event-stream, application/vnd.agent-engine-<VERSION>+json" \
  -H "Content-Type: application/json" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invokeStream" \
  -d '{"message": "Hello, agent!"}'

The response resembles the following output:

HTTP/2 200
content-type: text/event-stream

The response content type for streaming is text/event-stream, not a versioned type. The version selector applies to individual event structure, not to the transport. To learn more about streaming responses and event formats, see [Invoke an Agent.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent

Follow-Up Reads with Pinning

After invoking an agent, you may need to check the execution status or retrieve results. When you read an execution by ID, include the same version in the Accept header to ensure consistency with the pinned version:

curl --include \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.agent-engine-<VERSION>+json" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/executions/$EXECUTION_ID?workspace_id=$WORKSPACE_ID"

The response resembles the following output:

HTTP/2 200
content-type: application/vnd.agent-engine-<VERSION>+json

{
  "success": true,
  "execution": {
    "execution_id": "a0ad6e8b-60f1-47d4-8d25-fdd2e4d44bcf",
    "status": "completed",
    "message": "Hello, agent!",
    "session_id": "e243a75e-7452-4167-bee7-d687095a81e1"
  }
}

Resume Suspended Executions

When you resume a suspended execution for human-in-the-loop approval, pin the contract version on the resume request just as you did on the initial invocation. Include the X-Session-ID header from the suspend response:

curl --include -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.agent-engine-<VERSION>+json" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: $SESSION_ID" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -d "{\"resume_map\": {\"$INTERRUPT_ID\": {\"decision\": \"approve\", \"reviewer_notes\": \"optional context\"}}}"

The response follows the same pinning behavior as the initial invoke request. To learn more about suspending and resuming executions, see [Human-in-the-Loop Agent Execution.](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-human-in-the-loop

Routes That Ignore Version Selectors

Some API routes don't participate in contract versioning and return plain application/json regardless of the version selector. These routes include:

• GET /health (health check)

• POST /api/v1/oauth/token (OAuth token endpoint)

• GET|POST|DELETE /api/v1/projects/{id}/mcp (MCP routes)

• Authentication and login routes (/auth/*, /login, and similar)

Pinning a version selector on these routes has no effect. The API ignores the header.

Pin the CLI Version

The agentengine CLI version is separate from the API contract version. Pin the CLI version in your automation by specifying an exact version tag in your build or deployment configuration:

agentengine@X.Y.Z

Replace X.Y.Z with the version that you want. Pinning the version ensures that the CLI doesn't advance automatically when you upgrade other dependencies.

To find available CLI versions, see the agentengine CLI releases.

Authenticate API Requests

Authenticate API requests by including an Authorization header with a service account access token:

Authorization: Bearer $ACCESS_TOKEN

Obtain access tokens through the POST /api/v1/oauth/token client-credentials OAuth flow. To learn how to create and manage service accounts, see [Manage Service Account Credentials.](https://www.mongodb.com/docs/agentengine/api-keys-service-accounts.md#std-label-agent-engine-api-keys-service-accounts

Troubleshooting

Unsupported or Malformed Version

If you pin a version that doesn't exist or is malformed, the API returns 406 Not Acceptable:

curl --include \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.agent-engine-2099-01-01-preview+json" \
  -H "Content-Type: application/json" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -d '{"message": "Hello, agent!"}'

The response resembles the following output:

HTTP/2 406
content-type: application/json; charset=utf-8

{
  "error": 406,
  "errorCode": "UNSUPPORTED_API_VERSION",
  "detail": "The requested API version is not supported. Supported versions: 2026-09-20-preview.",
  "reason": "Not Acceptable",
  "parameters": ["Accept"]
}

The error response is application/json (not the dated vendor type) because no version was accepted.

To resolve this error:

• Remove the version selector to revert to the latest published contract.

• Use a supported version from the error response list.

• Ensure the version string includes the required -preview suffix.

Streaming Endpoint Without Event Stream Support

If you exclude text/event-stream from the Accept header on a streaming endpoint, the API returns 406 Not Acceptable:

curl --include \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.agent-engine-2026-09-20-preview+json" \
  "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invokeStream" \
  -d '{"message": "Hello, agent!"}'

The response resembles the following output:

{
  "error": 406,
  "errorCode": "UNACCEPTABLE_MEDIA_TYPE",
  "detail": "This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value.",
  "reason": "Not Acceptable",
  "parameters": ["Accept"]
}

Resolve this error by including text/event-stream in the Accept header for streaming endpoints.

To learn about service accounts to authenticate API requests, see [Manage Service Account Credentials.](https://www.mongodb.com/docs/agentengine/api-keys-service-accounts.md#std-label-agent-engine-api-keys-service-accounts

Security

Secret Access

Agents have access to all secrets in their project. New secrets are added at the project level, not the workspace level, by default. Agents that you deploy into an existing project can access every secret in the project, including the MONGODB_URI that other agents use.

To restrict a secret to one workspace, append the --workspace-scope flag when you call the agentengine secret set command.

Database Access

When you use the agentengine atlas setup command to create an Atlas connection, the connection grants readWriteAnyDatabase access on the destination cluster.

If you need database access with a narrower scope, manually create a database user in Atlas. Then, set a MONGODB_URI workspace secret with credentials scoped to the MDB_AGENTIC_STORE_DB and MONGOMEM_DB_NAME databases.

Agent Isolation

All agents deployed in a project share the same Orchestration Engine, or agent control plane. The Orchestration Engine does not enforce authentication or authorization against the calling agents.

If you need stronger agent isolation, deploy your agents in independent projects.

Tool Isolation

Tools run in the agent sandbox by default. To run a tool in the tool sandbox instead, list it in the sandboxes.tool.tools field of your agent.yaml file. You can list the tool name or a glob pattern that matches the tool name. Tools that request delegated credentials can run only in the tool sandbox.

The agent sandbox and the tool sandbox isolate their workloads from each other. For example, tools in the tool sandbox run separately from your agent's control flow in the agent sandbox. However, tools that run in the same sandbox are not isolated from each other.

Tools in the same sandbox can access all secrets and egress destinations that you configure for that sandbox. The Atlas Agent Engine does not scope secrets or network access to individual tools. Tools that run in the agent sandbox also share the agent sandbox's secrets and egress destinations with your agent code. If your agent requires isolation between tools, do not treat either sandbox as a per-tool security boundary.

If your agent uses a tool sandbox, each session reserves one tool sandbox while the session is active. All tool calls in the session that the Atlas Agent Engine routes to the tool sandbox run in that sandbox. The Atlas Agent Engine does not create a new tool sandbox for each tool call. If a session is idle for longer than the scaling.tool_idle_ttl_seconds value, the Atlas Agent Engine releases its tool sandbox. When the session becomes active again, it uses a new tool sandbox.

To configure sandbox secrets and egress destinations, see [Agent YAML Schema](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract-yaml and [Manage Network Egress Policies.](https://www.mongodb.com/docs/agentengine/network-egress.md#std-label-agent-engine-network-egress