langgraph-cli

`langgraph` CLI 可管理 LangGraph 应用的完整生命周期——从搭建新项目到将其部署到 LangGraph Platform（LangSmith Deployments）。

主要命令：

• langgraph new — 根据模板搭建项目
• langgraph dev — 在本地运行并启用热重载（无需 Docker）
• langgraph build — 构建 Docker 镜像
• langgraph up — 通过 Docker Compose 在本地启动
• langgraph deploy — 部署到 LangGraph Platform
• langgraph dockerfile — 生成 Dockerfile

除 new 外，所有命令都会读取项目根目录中的 langgraph.json 配置文件。

适用场景

当用户希望执行以下操作时，请使用此技能：

• 搭建新的 LangGraph 项目
• 运行本地开发服务器或类似生产环境的服务器
• 构建或部署 LangGraph 应用
• 了解或编辑 langgraph.json 配置
• 管理 LangSmith Deployments（列出、删除、查看日志）

安装

# Python
pip install 'langgraph-cli[inmem]'   # includes langgraph dev support
pip install langgraph-cli             # without dev server (build/up/deploy only)

# if using UV as package manager
uv add "langgraph-cli[inmem]"       # includes langgraph dev support
uv add langgraph-cli                # without dev server (build/up/deploy only)

# JavaScript
npx @langchain/langgraph-cli         # use on demand
npm install -g @langchain/langgraph-cli  # install globally (available as langgraphjs)

命令

langgraph new [PATH]

根据模板搭建新项目。

langgraph new                          # interactive template selection
langgraph new ./my-agent               # create in specific directory
langgraph new --template agent-python  # skip prompt, use template directly

可用模板：deep-agent-python、deep-agent-js、agent-python、new-langgraph-project-python、new-langgraph-project-js

langgraph dev

运行支持热重载的本地开发服务器。无需 Docker。

langgraph dev                              # default: localhost:2024
langgraph dev --port 8000                  # custom port
langgraph dev --config ./langgraph.json    # explicit config path
langgraph dev --no-reload                  # disable hot reload
langgraph dev --no-browser                 # don't auto-open LangGraph Studio
langgraph dev --host 0.0.0.0              # bind to all interfaces (trusted networks only)
langgraph dev --tunnel                     # expose via Cloudflare tunnel for remote access
langgraph dev --debug-port 5678            # enable remote debugger (requires debugpy)
langgraph dev --n-jobs-per-worker 20       # max concurrent jobs per worker (default: 10)

langgraph build

为 LangGraph API 服务构建 Docker 镜像。

langgraph build -t my-image                # required: tag the image
langgraph build -t my-image --no-pull      # use locally-built base images
langgraph build -t my-image -c langgraph.json  # explicit config
langgraph build -t my-image --base-image langchain/langgraph-server:0.2.18  # pin base version

langgraph up

通过 Docker Compose 启动 LangGraph API 服务（包含 Postgres）。

langgraph up                               # default port 8123
langgraph up --port 8000                   # custom port
langgraph up --watch                       # restart on file changes
langgraph up --recreate                    # force fresh build (useful for pre-deploy validation)
langgraph up --postgres-uri postgresql://...  # external Postgres
langgraph up --no-pull                     # use local images (after langgraph build)
langgraph up --image my-image              # skip build, use pre-built image
langgraph up -d docker-compose.yml         # add extra Docker services
langgraph up --debugger-port 8124          # serve debugger UI
langgraph up --wait                        # block until services are healthy

langgraph deploy

构建并部署到 LangGraph Platform（LangSmith Deployments）。需要 Docker。在 Apple Silicon（M1/M2/M3）上，还需要 Docker Buildx，以便交叉编译为 linux/amd64。

langgraph deploy                           # deploy, name defaults to directory name
langgraph deploy --name my-agent           # explicit deployment name
langgraph deploy --deployment-type prod    # production deployment (default: dev)
langgraph deploy --tag v1.2.0              # custom image tag (default: latest)
langgraph deploy --deployment-id <id>      # update an existing deployment by ID
langgraph deploy --config ./langgraph.json # explicit config path
langgraph deploy --no-wait                 # don't wait for deployment status
langgraph deploy --verbose                 # show detailed server logs

前置条件：在环境变量或 .env 中设置 LANGSMITH_API_KEY。

langgraph deploy 还接受构建标志：--base-image、--pull/--no-pull。

langgraph deploy list

langgraph deploy list                      # list all deployments
langgraph deploy list --name-contains bot  # filter by name

langgraph deploy delete

langgraph deploy delete <deployment-id>          # interactive confirmation
langgraph deploy delete <deployment-id> --force  # skip confirmation

langgraph deploy logs

langgraph deploy logs                                  # runtime logs, last 100
langgraph deploy logs --name my-agent                  # by deployment name
langgraph deploy logs --deployment-id <id>             # by deployment ID
langgraph deploy logs --type build                     # build logs instead of runtime
langgraph deploy logs -f                               # follow/stream logs
langgraph deploy logs --level error                    # filter by level (debug|info|warning|error|critical)
langgraph deploy logs -q "timeout"                     # search filter
langgraph deploy logs --limit 500                      # more entries
langgraph deploy logs --start-time 2026-03-08T00:00:00Z  # time range

langgraph dockerfile <SAVE_PATH>

生成 Dockerfile（以及可选的 Docker Compose 文件），但不进行构建。

langgraph dockerfile ./Dockerfile                      # generate Dockerfile
langgraph dockerfile ./Dockerfile --add-docker-compose # also generate compose + .env + .dockerignore

langgraph.json 参考

所有 CLI 命令（dev、build、up、deploy）使用的配置文件。默认使用当前目录中的 langgraph.json。

最简配置（Python）

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

最简配置（JavaScript）

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

包含所有键的完整配置

{
    "dependencies": [".", "langchain_openai", "./local_package"],
    "graphs": {
        "agent": "./my_agent/agent.py:graph",
        "retriever": "./my_agent/rag.py:rag_graph"
    },
    "env": "./.env",
    "python_version": "3.12",
    "pip_config_file": "./pip.conf",
    "dockerfile_lines": [
        "RUN apt-get update && apt-get install -y ffmpeg"
    ]
}

键参考

键	必需	描述
dependencies	是	依赖项数组。"." 会通过 pyproject.toml、setup.py、requirements.txt 或 package.json 查找本地包。也可以是子目录路径（"./my_pkg"）或包名（"langchain_openai"）。
graphs	是	图 ID 到路径的映射。格式：./path/to/file.py:variable（Python）或 ./path/to/file.js:function（JS）。变量必须是 CompiledGraph，或返回该对象的函数。支持多个图。
env	否	.env 文件的路径（字符串），或环境变量名称到值的内联映射（对象）。供本地运行的 langgraph dev 和 langgraph up 使用。langgraph deploy 会读取此文件，并将其中的变量添加为部署密钥。
python_version	否	"3.11"、"3.12" 或 "3.13"。默认为 "3.11"。
node_version	否	JS 项目的 Node.js 版本。
pip_config_file	否	用于自定义包索引的 pip 配置文件路径。
dockerfile_lines	否	附加 Dockerfile 行的数组，会追加在基础镜像导入之后。可用于系统包、二进制文件或自定义设置。

典型工作流

1. 搭建 — 使用 langgraph new 从模板创建项目。
2. 配置 — 编辑 langgraph.json：设置依赖项，将 graphs 指向已编译的图，并添加 .env。
3. 开发 — 使用 langgraph dev 进行快速本地迭代，并启用热重载（无需 Docker，端口为 2024）。
4. 验证 — 使用 langgraph up --recreate 在类似生产环境的 Docker 堆栈中测试（端口为 8123，包含 Postgres）。
5. 部署 — 使用 langgraph deploy 发布到 LangGraph Platform（LangSmith Deployments）。
6. 监控 — 使用 langgraph deploy logs -f 实时查看运行时日志；使用 --type build 查看构建日志。

langgraph dev 与 langgraph up

特性	langgraph dev	langgraph up
是否需要 Docker	否	是
安装	pip install 'langgraph-cli[inmem]'	pip install langgraph-cli
主要用途	快速开发与测试	类似生产环境的验证
状态持久化	内存中／序列化到本地目录	PostgreSQL
热重载	是（默认）	可选（--watch）
默认端口	2024	8123
资源占用	轻量	较高（用于服务、Postgres、Redis 的 Docker 容器）
IDE 调试	内置 DAP 支持（--debug-port）	容器调试

注意事项

• langgraph deploy 需要 Docker — 在 Apple Silicon（M1/M2/M3）上，交叉编译到 linux/amd64 还需要 Docker Buildx。
• langgraph deploy 只能更新其自身创建的部署 — 通过 LangSmith UI 或 GitHub 集成创建的部署无法使用 langgraph deploy 更新。请使用 UI 更新这些部署。
• dependencies 必须包含所有包 — langgraph.json 中的 dependencies 数组必须指向包配置所在的位置（例如，根目录使用 "."）。实际包从该位置的 pyproject.toml、requirements.txt 或 package.json 解析。
• langgraph dev 无需 Docker 即可运行 — 它直接在你的环境中运行。如果代码依赖系统包（例如，ffmpeg），则必须在本地安装。使用 langgraph up 验证 Docker 构建。
• JavaScript CLI — 使用 npx @langchain/langgraph-cli <command>（如果通过 npm install -g @langchain/langgraph-cli 全局安装，也可以使用 langgraphjs）。
• API 密钥 — langgraph deploy 需要 LANGSMITH_API_KEY。对于 langgraph dev，此密钥为可选项：服务无需该密钥即可运行，但你将无法在 LangSmith 中获取追踪记录。也可以通过 LANGGRAPH_HOST_API_KEY 或 LANGCHAIN_API_KEY 设置。