Migrate an Existing LangGraph Agent

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

Migrate an Existing LangGraph Agent

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 tutorial, you can learn how to migrate an existing LangGraph agent to the MongoDB Atlas Agent Engine. The tutorial shows how to add the MongoDB Atlas Agent Engine SDK to your project, wrap your agent code with the App class, create the required configuration files, and register your project on the Atlas Agent Engine.

Prerequisites

Before you begin, perform the following prerequisite tasks:

  • Install the agentengine CLI and authenticate your account. To learn more, see [Install and Authenticate.](https://www.mongodb.com/docs/agentengine/build/install-authenticate.md#std-label-agent-engine-set-up-install-authenticate

  • Open the pyproject.toml file within your existing LangGraph agent project.

  • Confirm that your pyproject.toml file has a [build-system] block that sets the requires and build-backend keys. The agentengine init command requires this block. You can run uv init --package in your project root to generate a file that meets this requirement.

  • Install uv.

  • Run Docker Desktop or Docker Engine on your machine.

Tutorial

Complete the following steps to add the platform SDK, update your agent code, and register your project on the Atlas Agent Engine.

  1. Add the SDK dependencies to your project.

Navigate to your pyproject.toml file, then run the following command from your project root to add the SDK dependencies:

bash uv add agent-engine-runner-shared agent-engine-sdk-langgraph

  1. Wrap your agent with the App class.

Update your agent's entry module to use the platform SDK by making the following changes:

  • Import App from agent_engine_sdk_langgraph and create an App instance at the module level.

  • Register each tool by using the @app.tool() decorator.

  • Add the @app.entrypoint decorator to your agent build function.

  • Wrap your LLM with the app.llm() method to route LLM calls through the platform's audited execution path.

  • Replace your checkpointer with app.checkpointer() to use the platform's MongoDB-backed checkpointer.

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

The following example shows a complete migrated agent module:

```python 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() ```

  1. Create an agent.yaml file.

In your project root, create an agent.yaml file that contains the entrypoint field and a network egress policy for the agent sandbox, as shown in the following code:

yaml entrypoint: my_agent.main:app name: my-agent framework: langgraph sandboxes: agent: network: egress_mode: deny_all

The entrypoint field must point to the App instance in module.path:attribute format.

The sandboxes.agent.network.egress_mode field declares the agent sandbox's outbound access policy. The preceding example blocks all outbound traffic other than the platform's base policy. To learn how to enable outbound access to specific destinations, see [Manage Network Egress Policies.](https://www.mongodb.com/docs/agentengine/network-egress.md#std-label-agent-engine-network-egress

Tip:

To view all available agent.yaml fields, see [Agent Contract Reference.](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract

  1. Create a .env file.

In your project root, create a .env file that specifies your MongoDB connection string and LLM provider API key, as shown in the following code:

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

Important:

The container reads secrets only from the .env file at runtime. Do not commit your secrets to your version control system.

  1. Register your project on the platform.

From your project root, run the following command to register your project and generate local development files:

bash agentengine init

The CLI guides you through selecting or creating an organization and project, then generates local development files.

  1. Run the agent locally.

To confirm that your migrated agent runs correctly, start the local development environment by running the following command:

bash agentengine dev up

When the stack is ready, open http://localhost:3000 in your browser to interact with your agent.

Note:

The UI might run on a different port than the default port 3000. To view your URL, check the ui field in the agentengine dev up command output.

Next Steps

After confirming that your migrated agent runs locally, you can perform the following tasks:

  • To provision secrets and build the agent image, see [Provision Cloud Secrets.](https://www.mongodb.com/docs/agentengine/deploy/provision-secrets.md#std-label-agent-engine-deploy-provision-secrets

  • To add platform features such as memory and guardrails, see [Add Memory to Your Agent.](https://www.mongodb.com/docs/agentengine/add-features/memory.md#std-label-agent-engine-add-memory