n4nAI
Open console →
Framework tutorialsHow-toLangGraph Multi-Agent Workflows

Deploying LangGraph apps with LangGraph Cloud

A step-by-step guide to deploying LangGraph applications to LangGraph Cloud, covering project setup, configuration, deployment commands, and verification.

n4n Team5 min read1,106 words

Audio narration

Coming soon — every post will get a voice note here.

LangGraph Cloud is the managed platform for running LangGraph applications without managing infrastructure. If you’ve built a multi-agent workflow locally and need to deploy langgraph cloud with minimal operational overhead, this guide walks through the complete process from a working local project to a production endpoint. We assume you have a LangGraph application that runs locally with langgraph dev and a LangSmith account.

Step 1: Prepare your project structure

LangGraph Cloud expects a specific project layout. Your repository needs a langgraph.json configuration file at the root and a Python package containing your graph definition.

my-langgraph-app/
├── langgraph.json
├── pyproject.toml
├── src/
│   └── my_agent/
│       ├── __init__.py
│       ├── graph.py
│       └── state.py
└── tests/
    └── test_graph.py

The langgraph.json file tells the platform how to load your graph. Create it at the repository root:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/my_agent/graph.py:graph"
  },
  "env": ".env"
}

The graphs mapping uses the format module_path:variable_name. The key (agent here) becomes the graph identifier in the API. The dependencies array includes local packages to install — . installs your package in editable mode.

Your pyproject.toml should declare the package and dependencies:

[project]
name = "my-agent"
version = "0.1.0"
description = "LangGraph multi-agent workflow"
requires-python = ">=3.11"
dependencies = [
    "langgraph>=0.2.0",
    "langchain-openai>=0.1.0",
    "pydantic>=2.0",
]

[tool.setuptools.packages.find]
where = ["src"]

Step 2: Define a production-ready graph

Your graph definition needs to be importable without side effects. Avoid top-level code that connects to databases or starts background threads. Keep initialization inside the graph construction function.

# src/my_agent/state.py
from typing import Annotated, List
from typing_extensions import TypedDict
from langgraph.graph import add_messages


class State(TypedDict):
    messages: Annotated[List[dict], add_messages]
    user_id: str
    metadata: dict
# src/my_agent/graph.py
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from .state import State


def call_model(state: State) -> dict:
    model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
    response = model.invoke(state["messages"])
    return {"messages": [response]}


def should_continue(state: State) -> str:
    last_message = state["messages"][-1]
    if last_message.get("tool_calls"):
        return "tools"
    return END


graph = (
    StateGraph(State)
    .add_node("agent", call_model)
    .add_node("tools", lambda state: state)  # placeholder for tool node
    .add_edge("agent", "tools")
    .add_conditional_edges("tools", should_continue)
    .set_entry_point("agent")
    .compile()
)

This graph compiles without requiring environment variables at import time. The ChatOpenAI instantiation happens inside the node function, not at module level.

Step 3: Configure environment variables

LangGraph Cloud injects environment variables at runtime. Create a .env file locally for development (never commit this):

# .env
OPENAI_API_KEY=sk-...
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=my-agent-prod

Add .env to .gitignore. In LangGraph Cloud, you’ll set these same variables in the deployment settings UI. The langgraph.json references .env via the env field so langgraph dev loads it automatically.

Step 4: Test locally with langgraph dev

Before deploying, verify the graph runs correctly with the CLI:

pip install -e ".[dev]"
langgraph dev

This starts a local server at http://localhost:2024 with the LangGraph Studio UI. Test your graph:

curl -X POST http://localhost:2024/runs \
  -H "Content-Type: application/json" \
  -d '{
    "graph_id": "agent",
    "input": {
      "messages": [{"role": "user", "content": "Hello"}],
      "user_id": "test-user",
      "metadata": {}
    }
  }'

Verify the response contains a valid assistant message. Check the Studio UI at http://localhost:2024 to inspect the trace. If this works locally, it will work in Cloud.

Step 5: Push to a Git repository

LangGraph Cloud deploys from Git. Push your project to GitHub, GitLab, or Bitbucket:

git init
git add .
git commit -m "Initial LangGraph Cloud deployment"
git remote add origin https://github.com/your-org/my-langgraph-app.git
git push -u origin main

The platform supports both public and private repositories. For private repos, you’ll need to grant LangGraph Cloud access during project creation.

Step 6: Create a LangGraph Cloud project

Navigate to cloud.langgraph.com and sign in with your LangSmith account. Click New Project and connect your Git repository.

Configure the deployment:

  • Repository: Select your repo and branch (usually main)
  • Build command: Leave blank — the platform detects pyproject.toml and runs pip install -e .
  • Start command: Leave blank — the platform starts the LangGraph API server automatically
  • Environment variables: Add OPENAI_API_KEY, LANGSMITH_API_KEY, LANGSMITH_PROJECT, and any other secrets your graph needs

Click Deploy. The first build takes 3–5 minutes as it installs dependencies and creates the container image.

Step 7: Verify the deployment

Once the deployment shows Healthy, copy the deployment URL (format: https://<deployment-id>.langgraph.cloud). Test the endpoint:

DEPLOYMENT_URL="https://your-deployment.langgraph.cloud"

curl -X POST "${DEPLOYMENT_URL}/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${LANGSMITH_API_KEY}" \
  -d '{
    "graph_id": "agent",
    "input": {
      "messages": [{"role": "user", "content": "Hello from production"}],
      "user_id": "prod-user-123",
      "metadata": {"source": "deployment-test"}
    }
  }'

The Authorization header uses your LangSmith API key. The response should include a run_id and stream events if you use the streaming endpoint.

Check the LangSmith project dashboard — you should see the trace appear within seconds. This confirms the deployment is wired to your observability stack.

Step 8: Configure custom domains (optional)

For production workloads, map a custom domain. In the deployment settings, add a custom domain like api.yourcompany.com. The platform provisions a managed TLS certificate via Let’s Encrypt.

Update your DNS with the provided CNAME target. Verify:

curl -X POST "https://api.yourcompany.com/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${LANGSMITH_API_KEY}" \
  -d '{"graph_id": "agent", "input": {"messages": [{"role": "user", "content": "Custom domain test"}], "user_id": "test", "metadata": {}}}'

Step 9: Set up CI/CD for automatic deployments

LangGraph Cloud supports automatic deployments on push. In the project settings, enable Auto-deploy for your branch. Every push to main triggers a new build and rolling deployment.

For more control, use the GitHub Action:

# .github/workflows/deploy.yml
name: Deploy to LangGraph Cloud

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to LangGraph Cloud
        uses: langchain/langgraph-cloud-deploy@v1
        with:
          deployment-id: ${{ secrets.LANGGRAPH_DEPLOYMENT_ID }}
          api-key: ${{ secrets.LANGSMITH_API_KEY }}

Store LANGGRAPH_DEPLOYMENT_ID and LANGSMITH_API_KEY as repository secrets. The action triggers a deployment and waits for health checks to pass.

Step 10: Monitor and scale

LangGraph Cloud provides built-in metrics. In the deployment dashboard, monitor:

  • Request latency (p50, p95, p99)
  • Error rate by status code
  • Concurrent runs — each run is a graph execution
  • Token usage — if using LLM nodes

The platform autoscales based on concurrent run count. For predictable workloads, set minimum replicas in the deployment settings to avoid cold starts:

// In deployment settings UI or via API
{
  "min_replicas": 2,
  "max_replicas": 20,
  "target_concurrent_runs_per_replica": 10
}

Each replica handles roughly 10 concurrent runs before scaling out. Adjust based on your graph’s latency profile.

Step 11: Handle secrets rotation

Rotate API keys without redeploying. In the deployment settings, update the environment variable value and click Save. The platform performs a rolling restart — zero downtime, but in-flight runs continue on the old version.

For database credentials or other sensitive config, use the same pattern. Never bake secrets into the Docker image.

Step 12: Debug production issues

When something breaks, start with the LangSmith trace. Every run creates a trace in your LangSmith project. Filter by graph_id: agent and look for errors.

Common issues:

Graph compilation fails at startup: Check build logs for import errors. The most common cause is a missing dependency in pyproject.toml or a top-level import that requires environment variables.

Runs timeout: Default timeout is 30 minutes. For long-running graphs, increase the timeout in the deployment settings or implement checkpointing with interrupt and Command for human-in-the-loop workflows.

Memory pressure: Large state objects or unbounded message history can OOM the container. Add a trim_messages node or configure a max_tokens limit in your model call.

# Add to your graph for message history management
from langchain_core.messages import trim_messages

def trim_history(state: State) -> dict:
    trimmed = trim_messages(
        state["messages"],
        max_tokens=8000,
        token_counter=ChatOpenAI(model="gpt-4o-mini"),
        strategy="last",
        start_on="human",
    )
    return {"messages": trimmed}

Step 13: Rollback a bad deployment

If a deployment introduces a regression, rollback from the dashboard. Click the Deployments tab, find the previous healthy deployment, and click Rollback. This triggers a new rolling deployment of the old image — typically under 60 seconds.

You can also rollback via CLI:

pip install langgraph-cloud
langgraph-cloud rollback --deployment-id <id> --target-deployment <previous-id>

Verification checklist

Before considering the deployment production-ready, confirm:

  • Health endpoint returns 200: curl https://your-deployment.langgraph.cloud/health
  • Graph executes end-to-end with realistic input
  • Traces appear in LangSmith with correct metadata
  • Custom domain resolves and serves traffic over HTTPS
  • Auto-deploy triggers on push to main
  • Rollback restores previous version within 60 seconds
  • Environment variables are set in Cloud (not committed to Git)
  • Minimum replicas configured for latency-sensitive workloads

Next steps

You now have a deployed LangGraph application with observability, autoscaling, and CI/CD. From here, consider:

  • Streaming responses: Use the /runs/stream endpoint for token-by-token output
  • Human-in-the-loop: Add interrupt nodes and resume via the /runs/{run_id}/resume endpoint
  • Multi-tenancy: Include tenant_id in state and enforce isolation at the application layer
  • Evaluation: Connect LangSmith datasets to run regression tests on every deploy

The platform handles infrastructure so you can focus on graph logic. When you need to route across 240+ models with automatic fallback and per-token metering, n4n.ai provides an OpenAI-compatible endpoint that integrates with the same LangGraph Cloud deployment pattern — just swap the base URL in your ChatOpenAI client.

Tagslanggraphlanggraph-clouddeploymentagents

Written by

n4n Team

The team building n4n — a single OpenAI-compatible API in front of 240+ models, with automatic fallback, load balancing and pay-per-token metering.

More from n4n Team →
Framework tutorialsLangGraph streaming and interrupting long-running agentsLearn to implement streaming and human-in-the-loop interrupts in LangGraph agents with runnable code examples for long-running workflows.Framework tutorialsPersisting LangGraph state with checkpointersLearn to persist LangGraph state with checkpointers — from in-memory to Postgres, with runnable code and verification steps.Framework tutorialsLangGraph conditional edges: routing between agentsLangGraph conditional edges enable dynamic agent routing based on state — here's how they work, when to use them, and a production-ready example.Framework tutorialsLangGraph human-in-the-loop workflowsBuild production-ready langgraph human in the loop workflows with interrupt handling, state persistence, and approval patterns that scale.Framework tutorialsBuild a multi-agent workflow with LangGraphA practical langgraph multi-agent workflow tutorial: build a supervisor-routed system of specialized agents with LangGraph, from setup to verified run.Framework tutorialsBuilding a customer support graph with LangGraphBuild a langgraph customer support agent with stateful routing, retrieval, and escalation. Step-by-step Python code for a production-ready support workflow.

All langgraph multi-agent workflows posts →