Agent Contract Reference

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

Agent Contract Reference

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 the minimum requirements for running an agent on the MongoDB Atlas Agent Engine. This guide covers the files the Atlas Agent Engine needs to discover and run your agent, the agent.yaml schema, and compatible frameworks and LLM providers.

Agents do not implement their own HTTP endpoint. The Atlas Agent Engine imports the agent inside the same process as the agent sandbox.

Minimal Deployable Agent

A minimal deployable agent consists of two files:

• my_agent/main.py: defines the App object and the graph.

• agent.yaml: points to the App object defined in my_agent/main.py.

The following example shows a minimal main.py file that defines an App object named my-agent and builds an agent graph:

from agent_engine_sdk_langgraph import App
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI

app = App(app_name="my-agent")

@app.tool()
def lookup(query: str) -> str:
    """Search the knowledge base."""
    return f"result for {query}"

@app.entrypoint
def build_agent():
    llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
    tools = app.get_tools()

    def call_model(state: MessagesState):
        return {"messages": [llm.invoke(state["messages"])]}

    graph = StateGraph(MessagesState)
    graph.add_node("agent", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.set_entry_point("agent")
    graph.add_edge("tools", "agent")
    return graph.compile(checkpointer=app.checkpointer())

app.run()

The following example shows a minimal agent.yaml file:

entrypoint: my_agent.main:app

In the main.py file, you must execute the following components:

• Define an App object at the module level, usually named app.

• Register an entrypoint to the app with the @app.entrypoint function.

• Register tools with the @app.tool(...) function.

• Call the app.run() function at the bottom of the module.

In the agent.yaml file, you must set the entrypoint YAML key to the App object using the format <module.path>:<attribute>.

Agent Guidelines

Follow these guidelines to ensure your agent works correctly with platform features such as audit logging, policy enforcement, and suspend or resume agent executions:

• Route tool and LLM calls through the app.tool(...) and app.llm(...) functions.

The Atlas Agent Engine uses these wrappers for audit logging, policy enforcement, and replaying tools and LLM calls when you resume a suspended execution. Calls made outside these wrappers are not audited by the Atlas Agent Engine and do not replay correctly after resuming an execution.

• Keep your graph state JSON/BSON-serializable.

Agent sandboxes are ephemeral, so the Atlas Agent Engine saves checkpoint states to MongoDB between suspend and resume actions. Every value in your graph state must be serializable to JSON or BSON for the checkpoint to succeed, such as primitives, lists, dicts, datetime, Enum, and LangChain BaseMessage subclasses. Do not store lambdas, closures, file handles, database connections, or custom classes in your graph state without serialization support.

• Call the app.llm(...) function only while your entrypoint is on the call stack.

When you call app.llm(...) from module top-level code, a tool body, or any other function that your entrypoint does not invoke, the Atlas Agent Engine generates an error that identifies the file and line with the invalid call. To learn more, see [Execution Lifecycle.](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract-lifecycle

Execution Lifecycle

The Atlas Agent Engine loads and runs your agent code at defined points in the lifecycle of the following processes:

• Agent Sandbox, which runs your agent code and builds your graph.

• Tool Sandbox, which runs remote tool bodies in a separate process from the agent sandbox.

Note:

This execution lifecycle is the same across the Python and TypeScript SDKs.

This section describes when individual parts of your agent code run in each process, and uses the following terms:

• Module top-level code is code in your agent's source files that runs at import time, outside of any function body.

• The entrypoint is the function you decorate with @app.entrypoint.

• A local tool runs only inside the agent sandbox's own process. By default, every tool that you register with the @app.tool() decorator is a local tool.

• A remote tool is a tool that you assign to the tool sandbox by listing it in the sandboxes.tool.tools field of your agent.yaml file. The agent sandbox interprets remote tools, but remote tool bodies run in the tool sandbox.

Startup

In both the agent sandbox and the tool sandbox processes, the Atlas Agent Engine performs the following actions at startup:

• Loads your agent's source files.

• Runs your module top-level code.

The platform does not perform the following actions at startup:

• Run your entrypoint.

• Run your tool bodies. The Atlas Agent Engine interprets tool definitions to register their signatures, but does not run them.

Module top-level code can access process-wide secrets, such as [MONGODB_URI](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-contract-env, and MCP OAuth credentials, because these values are available for the lifetime of the process. The Atlas Agent Engine also sets the secrets that you declare for a sandbox, including LLM API keys, when the sandbox starts. As a result, module top-level code in a sandbox can access that sandbox's secrets.

Agent Sandbox Invocation

In the agent sandbox, the Atlas Agent Engine performs the following actions during an invocation:

• Runs your entrypoint once.

• Executes local tool bodies in the agent sandbox's own process.

The platform does not perform the following actions during an agent sandbox invocation:

• Run remote tool bodies. The agent sandbox interprets them, then dispatches the call to the tool sandbox.

Tool Sandbox Invocation

In the tool sandbox, the Atlas Agent Engine performs the following actions during an invocation:

• Loads your entrypoint lazily, exactly once per sandbox lifetime, triggered by the first invoke_llm call. This loading only discovers your app.llm(...) registrations.

• Interprets remote tool bodies, then runs them on demand when the Orchestration Engine routes a tool call to the sandbox.

The Atlas Agent Engine does not perform the following actions during a tool sandbox invocation:

• Execute your graph.

• Run local tool bodies.

The Atlas Agent Engine delivers the secrets that you declare in the sandboxes.tool.secrets field as environment variables in the tool sandbox. Every remote tool body that runs in the tool sandbox can read these environment variables. To learn more about how sandboxes share secrets between tools, see [MongoDB Atlas Agent Engine Limitations.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations

Lifecycle Summary

The following table summarizes when each part of your code runs in each execution process and phase:

Agent YAML Schema

The agent.yaml file configures how the Atlas Agent Engine discovers and runs your agent. It supports two formats: a single-agent manifest for repositories that contain one agent, and a monorepo manifest for repositories that contain multiple agents.

Single-Agent Manifest

The following table describes the fields available for a single-agent agent.yaml file. The Required column indicates whether a field is required for a minimal agent.yaml file.

artifact_repositories credentials are resolved at build time only. To learn how private artifact repositories work in cloud builds and local development, see [Build the Agent Image](https://www.mongodb.com/docs/agentengine/deploy/agent-image.md#std-label-agent-engine-build-artifact-repositories and [Run Agents Locally.](https://www.mongodb.com/docs/agentengine/build/run-local.md#std-label-agent-engine-build-local-artifact-repos

Each session reserves its own agent and tool sandboxes for its lifetime, and the Atlas Agent Engine resets a sandbox before it assigns the sandbox to a new session. As a result, artifacts that one session writes to a sandbox are not visible to later sessions.

The Atlas Agent Engine snapshots scaling values at build time, so changes take effect on the next build and deploy. A change to the platform default doesn't resize a workspace that is already deployed. The workspace keeps the hardware-isolated sandbox count from its most recent build until you build and deploy it again. The idle time-to-live (TTL) values apply project-wide. When several agents in one project set different values, the project applies the values from the most recently deployed agent.

Note:

You must configure local development settings in a separate dev.yaml file in the same directory as the agent.yaml file, not in agent.yaml itself. To learn more, see [Configure Local Development Settings.](https://www.mongodb.com/docs/agentengine/build/run-local.md#std-label-agent-engine-build-local-dev-yaml

The following example shows an agent.yaml file with service port overrides, feature flags, secret access restrictions, and a private artifact repository:

name: my-agent
entrypoint: my_agent.main:app

features:
  guardrails: true

scaling:
  replicas: 4
  agent_idle_ttl_seconds: 900
  tool_idle_ttl_seconds: 300

sandboxes:
  agent:
    secrets: ["*"]
    tools: []
  tool:
    secrets:
      - SEARCH_API_KEY
      - ANTHROPIC_API_KEY
    tools:
      - my_search_tool
      - invoke_llm

artifact_repositories:
  - name: corps-pypi
    type: pypi
    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN
    username: aws
    scope: project

Monorepo Manifest

If your repository contains multiple agents, define them in a single agent.yaml file by using a top-level agents: list. The Atlas Agent Engine detects this list and treats the file as a monorepo manifest instead of a single-agent configuration. The following agent.yaml file is an example of a monorepo manifest with multiple agents:

agents:
  - name: chat
    path: agents/chat
  - name: research
    path: agents/research

Each agent subdirectory must contain its own single-agent agent.yaml file.

.env Requirements

You must set the MONGODB_URI environment variable in your .env file to deploy your agent successfully, if services.mongodb.local is set to false in your dev.yaml file.

Your agent also requires an LLM API key in the .env file to process requests at runtime. The platform itself does not validate or require specific LLM credentials, but the agent will fail at runtime without them. Use the <PROVIDER>_API_KEY syntax to set the environment variable for your LLM provider.

Frameworks and LLM Providers

This section describes the frameworks and LLM providers you can use with the Atlas Agent Engine.

Frameworks

The Atlas Agent Engine supports LangGraph and LangChain through the agent-engine-sdk-langgraph package. The framework adapter handles the following integration points:

• interrupt() for pausing the agent execution for human review before it continues

• MongoDBSaver for saving the agent's graph state to MongoDB so it can be restored when a suspended execution is resumed

• LangChainInstrumentor for recording LLM and tool calls during execution for debugging and monitoring

LLM Providers

You can use any LLM provider with your agent. To use a model, construct a LangChain BaseChatModel for the provider and pass it to the app.llm() method. The Atlas Agent Engine routes that call through the Orchestration Engine.

The following table shows common provider examples with their environment key and LangChain class:

The following code examples show how to configure each provider for the app.llm() method:

## OpenAI
from langchain_openai import ChatOpenAI
llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))

## Anthropic
from langchain_anthropic import ChatAnthropic
llm = app.llm(ChatAnthropic(model="claude-sonnet-4-5"))

## Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
llm = app.llm(ChatGoogleGenerativeAI(model="gemini-2.5-flash-lite"))

## Cerebras
from langchain_cerebras import ChatCerebras
llm = app.llm(ChatCerebras(model="qwen-3-235b-a22b-instruct-2507"))

Next Steps

To learn how to authenticate and invoke a deployed agent, see the [Invoke an Agent](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent guide.