Migrate an Existing LangGraph Agent

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:

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

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:

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

Create an agent.yaml file.

In your project root, create an agent.yaml file that contains the entrypoint field, as shown in the following code:

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

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

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:

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

Register your project on the platform.

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

agentengine init

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

Run the agent locally.

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

agentengine dev up

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