LangGraph CLI

LangGraph CLI 是一个用于在本地构建和运行 Agent Server 的命令行工具。生成的服务器会暴露运行、线程、助手等所有 API 端点，并包含支持服务，例如用于检查点和存储的托管数据库。

安装

确保已安装 Docker（例如 docker --version）。
安装 CLI：

[Python (pip)]JavaScript

bash

pip install langgraph-cli

bash

# Use latest on demand
npx @langchain/langgraph-cli

# Or install globally (available as `langgraphjs`)
npm install -g @langchain/langgraph-cli

验证安装

[Python (pip)]JavaScript

bash

langgraph --help

bash

npx @langchain/langgraph-cli --help

快速命令

命令	作用
`langgraph dev`	启动一个轻量级的本地开发服务器（无需 Docker），非常适合快速测试。
`langgraph build`	构建用于部署的 LangGraph API 服务器的 Docker 镜像。
`langgraph deploy`	一步完成构建并将 LangGraph 镜像直接部署到 LangSmith Deployments。
`langgraph dockerfile`	根据配置生成 Dockerfile，用于自定义构建。
`langgraph up`	在 Docker 中本地启动 LangGraph API 服务器。需要 Docker 正在运行；本地开发需要 LangSmith API key；生产环境需要许可证。

对于 JS，使用 npx @langchain/langgraph-cli <command>（如果全局安装，则使用 langgraphjs）。

配置文件

要构建并运行一个有效的应用，LangGraph CLI 需要一个遵循此 schema 的 JSON 配置文件。它包含以下属性：

NOTE

LangGraph CLI 默认使用当前目录下名为 langgraph.json 的配置文件。

键	描述
`dependencies`	必需。LangSmith API 服务器的依赖项数组。依赖项可以是以下之一：单个句点（`"."`），用于查找本地 Python 包。 `pyproject.toml`、`setup.py` 或 `requirements.txt` 所在的目录路径。例如，如果 `requirements.txt` 位于项目目录的根目录，请指定 `"./"`。如果它位于名为 `local_package` 的子目录中，请指定 `"./local_package"`。不要指定字符串 `"requirements.txt"` 本身。一个 Python 包名称。
`graphs`	必需。从图 ID 到路径的映射，该路径指向已编译的图或用于创建图的函数。示例： `./your_package/your_file.py:variable`，其中 `variable` 是 `langgraph.graph.state.CompiledStateGraph` 的一个实例 `./your_package/your_file.py:make_graph`，其中 `make_graph` 是一个接受配置字典（`langchain_core.runnables.RunnableConfig`）并返回 `langgraph.graph.state.StateGraph` 或 `langgraph.graph.state.CompiledStateGraph` 实例的函数。更多详情请参阅如何在运行时重建图。
`auth`	（v0.0.11 新增）身份认证与授权配置。包含： `path`（必需）：身份认证处理程序的路径（例如 `./your_package/auth.py:auth`），其中 `auth` 是 `langgraph_sdk.Auth` 的一个实例。参见身份认证指南。 `disable_studio_auth`（可选）：如果为 `true`，Studio 不能将 LangSmith auth 用作回退。默认为 `false`。 `allow_langsmith_api_keys`（可选，Agent Server v0.14.0rc2+）：如果为 `true`，则在自定义身份认证的同时运行 LangSmith API key 身份认证。带有 `Authorization` 请求头的请求交由自定义身份认证处理；其他所有请求交由 LangSmith（`x-api-key`）处理。自定义 `@auth.on` 处理程序仍会执行。默认为 `false`。 `openapi`（可选）：要在 OpenAPI 中记录的安全方案。参见 OpenAPI 安全。
`base_image`	可选。用于 LangGraph API 服务器的基础镜像。默认为 `langchain/langgraph-api` 或 `langchain/langgraphjs-api`。可用它将构建固定到特定版本的 langgraph API，例如 `"langchain/langgraph-server:0.2"`。更多详情参见 https://hub.docker.com/r/langchain/langgraph-server/tags。（`langgraph-cli==0.2.8` 中新增）
`image_distro`	可选。基础镜像所用的 Linux 发行版。必须是 `"debian"`、`"wolfi"`、`"bookworm"` 或 `"bullseye"` 之一。若省略，默认为 `"debian"`。在 `langgraph-cli>=0.2.11` 中可用。
`env`	`.env` 文件的路径，或从环境变量到其值的映射。
`store`	用于为 BaseStore 添加语义搜索和/或存活时间（TTL）的配置。包含以下字段： `index`（可选）：语义搜索索引配置，包含 `embed`、`dims` 字段以及可选的 `fields` 字段。 `ttl`（可选）：条目过期配置。一个对象，包含以下可选字段：`refresh_on_read`（布尔值，默认为 `true`）、`default_ttl`（浮点数，生命周期以分钟为单位；仅应用于新建条目；已有条目不受影响；默认不过期）和 `sweep_interval_minutes`（整数，检查过期条目的频率，默认不扫描）。
`ui`	可选。智能体发出的 UI 组件的命名定义，每项指向一个 JS/TS 文件。（`langgraph-cli==0.1.84` 中新增）
`python_version`	`3.11`、`3.12` 或 `3.13`。默认为 `3.11`。
`node_version`	指定 `node_version: 20` 以使用 LangGraph.js。
`pip_config_file`	`pip` 配置文件的路径。
`pip_installer`	（v0.3 新增）可选。Python 包安装器选择器。它可以设为 `"auto"`、`"pip"` 或 `"uv"`。从 0.3 版本起，默认策略是运行 `uv pip`，通常能带来更快的构建速度，同时仍是直接替换方案。在 `uv` 无法处理你的依赖关系图或 `pyproject.toml` 结构的不常见情况下，可在此指定 `"pip"` 以回退到之前的行为。
`keep_pkg_tools`	（v0.3.4 新增）可选。控制在最终镜像中是否保留 Python 打包工具（`pip`、`setuptools`、`wheel`）。可接受的值： `true`：保留全部三个工具（跳过卸载）。 `false` / 省略：卸载全部三个工具（默认行为）。 `list[str]`：要保留的工具名称。每个值必须是 "pip"、"setuptools"、"wheel" 之一。。默认情况下，三个工具都会被卸载。
`dockerfile_lines`	在从父镜像导入之后添加到 Dockerfile 的额外行数组。
`checkpointer`	检查点器的配置。支持： `backend`（可选）：`"default"`、`"mongo"` 或 `"custom"`。默认为 `"default"`（PostgreSQL）。参见配置检查点器后端。 `path`（可选）：自定义检查点器工厂的路径（当 `backend` 为 `"custom"` 时）。参见自定义检查点器。 `ttl`（可选）：包含 `strategy`、`sweep_interval_minutes`、`default_ttl` 和 `sweep_limit`（Agent server v0.8+）的对象，用于控制检查点过期。 `serde`（可选，Agent server v0.5+）：包含 `allowed_json_modules` 和 `pickle_fallback` 的对象，用于调优反序列化行为。
`http`	HTTP 服务器配置，包含以下字段： `app`：自定义 Starlette/FastAPI 应用的路径（例如 `"./src/agent/webapp.py:app"`）。参见自定义路由指南。 `cors`：CORS 配置，包含 `allow_origins`、`allow_methods`、`allow_headers`、`allow_credentials`、`allow_origin_regex`、`expose_headers` 和 `max_age` 等字段。 `configurable_headers`：通过 `includes` / `excludes` 模式定义将哪些请求头暴露为可配置值。 `logging_headers`：`configurable_headers` 的对应项，用于从日志中排除敏感请求头。 `middleware_order`：选择自定义 middleware 与身份认证如何交互。`auth_first` 在自定义 middleware 之前运行身份认证钩子，而 `middleware_first`（默认）先运行你的 middleware。 `enable_custom_route_auth`：对通过 `app` 添加的路由应用身份认证检查。路由禁用标志，可选择性地关闭内置的端点分组： `disable_meta`：禁用 `/`（根）、`/info`、`/metrics`、`/docs` 和 `/openapi.json` 系统路由。`/ok` 健康检查仍然可用。 `disable_assistants`：禁用所有 `/assistants/` 路由。 `disable_runs`：禁用所有 `/runs/` 路由。 `disable_threads`：禁用所有 `/threads/` 路由。 `disable_store`：禁用所有 `/store/` 路由。 `disable_ui`：禁用所有 `/ui/` 路由。 `disable_mcp`：禁用 `/mcp` 端点。参见禁用 MCP。 `disable_a2a`：禁用 `/a2a/` 端点。参见禁用 A2A。 `disable_webhooks`：禁用运行完成时的 webhook 投递（不是路由开关）。参见禁用 webhooks。 `mount_prefix`：挂载路由的前缀（例如 "/my-deployment/api"）。
`webhooks`	（v0.5.36 新增）出站 webhook 投递配置。包含： `env_prefix`：请求头模板中引用的环境变量所必需的前缀（默认为 `LG_WEBHOOK_`）。 `headers`：随 webhook 请求一起发送的静态请求头。值可以包含形如 `${ env.VAR }` 的模板。 `url`：URL 校验策略，包含 `allowed_domains`、`allowed_ports`、`require_https`、`disable_loopback` 和 `max_url_length`。
`api_version`	（v0.3.7 新增）要使用的 LangGraph API 服务器的语义版本（例如 `"0.3"`）。默认为最新版本。有关每个版本的详情，请查看服务器更新日志。

示例

基础配置

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  }
}

使用 Wolfi 基础镜像

你可以使用 image_distro 字段为基础镜像指定 Linux 发行版。可选值为 debian、wolfi、bookworm 或 bullseye。推荐使用 Wolfi，因为它提供的镜像更小、更安全。该功能在 langgraph-cli>=0.2.11 中可用。

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "image_distro": "wolfi"
}

为 store 添加语义搜索

所有部署都带有数据库支持的 BaseStore。在 langgraph.json 中添加 "index" 配置，即可在你的部署的 BaseStore 中启用语义搜索。

index.fields 配置决定要嵌入文档的哪些部分：

如果省略或设为 ["$"]，将嵌入整个文档
若要嵌入特定字段，请使用 JSON 路径表示法：["metadata.title", "content.text"]
缺少指定字段的文档仍会被存储，但不会为这些字段生成嵌入向量
你仍然可以在 put 时通过 index 参数覆盖某个具体条目要嵌入的字段

json

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}

NOTE

常见模型维度

openai:text-embedding-3-large: 3072
openai:text-embedding-3-small: 1536
openai:text-embedding-ada-002: 1536
cohere:embed-english-v3.0: 1024
cohere:embed-english-light-v3.0: 384
cohere:embed-multilingual-v3.0: 1024
cohere:embed-multilingual-light-v3.0: 384

使用自定义嵌入函数进行语义搜索

如果你想通过自定义嵌入函数使用语义搜索，可以传入自定义嵌入函数的路径：

json

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "./embeddings.py:embed_texts",
      "dims": 768,
      "fields": ["text", "summary"]
    }
  }
}

store 配置中的 embed 字段可以引用一个自定义函数，该函数接受字符串列表并返回嵌入向量列表。实现示例：

python

# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
    """Custom embedding function for semantic search."""
    # Implementation using your preferred embedding model
    return [[0.1, 0.2, ...] for _ in texts]  # dims-dimensional vectors

添加自定义身份认证

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "auth": {
    "path": "./auth.py:auth",
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [{ "apiKeyAuth": [] }]
    },
    "disable_studio_auth": false,
    "allow_langsmith_api_keys": false
  }
}

有关详情，请参阅身份认证概念指南；有关该流程的实践演练，请参阅设置自定义身份认证指南。

配置 store 条目的存活时间

你可以使用 store.ttl 键为 BaseStore 中的条目/记忆配置默认的数据过期时间。它决定条目在最后一次被访问后保留多久（读取可能会根据 refresh_on_read 刷新计时器）。注意，这些默认值可以通过修改 get、search 等方法中相应的参数在每次调用时被覆盖。

ttl 配置是一个包含以下可选字段的对象：

refresh_on_read：如果为 true（默认值），通过 get 或 search 访问条目会重置其过期计时器。设为 false 则仅在写入（put）时刷新 TTL。
default_ttl：条目的默认生命周期，以分钟为单位。仅应用于新建条目；已有条目不会被修改。如果未设置，条目默认不过期。
sweep_interval_minutes：系统运行后台进程删除过期条目的频率（以分钟为单位）。如果未设置，则不会自动进行扫描。

下面是一个启用 7 天 TTL（10080 分钟）、读取时刷新并每小时扫描一次的示例：

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080
    }
  }
}

配置检查点的存活时间

你可以使用 checkpointer 键配置检查点的存活时间（TTL）。它决定检查点数据在按指定策略（例如删除）被自动处理之前保留多久。支持两个可选的子对象：

ttl：包含 strategy、sweep_interval_minutes、default_ttl 和 sweep_limit（Agent server v0.8+），共同决定检查点如何过期。
serde （Agent server v0.5+）：让你控制检查点载荷的反序列化行为。

下面是一个将默认 TTL 设为 30 天（43200 分钟）的示例：

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}

在此示例中，超过 30 天的检查点将被删除，并且每 10 分钟执行一次检查。

配置检查点器 serde

checkpointer.serde 对象用于决定反序列化行为：

allowed_json_modules 定义一个允许列表，列出你希望服务器能够从以 "json" 模式保存的载荷中反序列化的自定义 Python 对象。这是一个由 [path, to, module, file, symbol] 序列组成的列表。如果省略，则只允许 LangChain 安全的默认值。你可以不安全地设为 true，以允许反序列化任何模块。
pickle_fallback：当 JSON 解码失败时，是否回退到 pickle 反序列化。

json

{
  "checkpointer": {
    "serde": {
      "allowed_json_modules": [
        ["my_agent", "auth", "SessionState"]
      ]
    }
  }
}

自定义 HTTP middleware 与请求头

http 代码块让你对请求处理进行微调：

middleware_order：选择 "auth_first" 以在你的 middleware 之前运行身份认证，或选择 "middleware_first"（默认）来反转该顺序。
enable_custom_route_auth：将身份认证扩展到通过 http.app 挂载的路由。
configurable_headers / logging_headers：各自接受一个包含可选 includes 和 excludes 数组的对象；支持通配符，且排除先于包含执行。

cors：自定义服务器的 CORS（跨源资源共享）配置。配置 CORS 的 langgraph.json 文件示例：

json

{
  ...
  "http": {
    "cors": {
      "allow_origins": ["https://example.com", "https://app.example.com"],
      "allow_methods": ["GET", "POST"],
      "allow_headers": ["Authorization", "Content-Type"],
      "allow_credentials": true,
      "allow_origin_regex": "^https://.*\\.example\\.com$",
      "expose_headers": ["x-pagination-total", "x-pagination-next", "x-request-id"],
      "max_age": 600
    }
  },
  ...
}

NOTE

  自定义服务器的 CORS 配置将覆盖设置 [`CORS_ALLOW_ORIGINS` 环境变量](/langsmith/env-var-cloud) 的功能。

配置 webhooks

你可以为出站 webhook 请求配置自定义请求头和 URL 限制：

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "webhooks": {
    "headers": {
      "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}"
    },
    "url": {
      "allowed_domains": ["*.mycompany.com"],
      "require_https": true
    }
  }
}

有关请求头配置、环境变量模板化和 URL 限制的详情，请参阅使用 webhooks。

固定 API 版本

（v0.3.7 新增）

你可以使用 api_version 键固定 Agent Server 的 API 版本。如果你想确保服务器使用特定版本的 API，这会很有用。默认情况下，云部署中的构建使用服务器的最新稳定版本。可以通过将 api_version 键设为特定版本来固定它。

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "api_version": "0.2"
}

禁用内置路由

你可以使用 http 配置块中的布尔标志选择性地禁用内置的 HTTP 路由分组。这在生产部署中很有用，因为你可能希望尽量减少服务器暴露的面。

例如，要禁用系统信息和文档路由：

json

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "http": {
    "disable_meta": true
  }
}

将 disable_meta 设为 true 会禁用以下路由：

/ — 根健康检查
/info — 服务器版本和配置信息
/metrics — Prometheus 与 JSON 指标
/docs — API 文档界面
/openapi.json — OpenAPI 规范

即使设置了 disable_meta，/ok 健康检查端点仍然可用，因此 Kubernetes 等编排系统仍可执行存活和就绪探针。

其他路由禁用标志包括 disable_assistants、disable_runs、disable_threads、disable_store 和 disable_ui。关于 MCP、A2A 和 webhooks，请参阅各自的指南：禁用 MCP、禁用 A2A、禁用 webhooks。

命令

用法

LangGraph CLI 的基础命令是 langgraph。

langgraph [OPTIONS] COMMAND [ARGS]

`dev`

以开发模式运行 LangGraph API 服务器，具备热重载和调试能力。这个轻量级服务器无需安装 Docker，适合开发和测试。状态会持久化到本地目录。

NOTE

目前，CLI 仅支持 Python 3.11 或更高版本

TIP

如果你需要更多关于何时使用 langgraph dev 与 langgraph up 的信息，请参阅本地开发与测试指南以获取详细对比。

安装

此命令需要安装 "inmem" 额外依赖：

bash

pip install -U "langgraph-cli[inmem]"

用法

langgraph dev [OPTIONS]

选项

选项	默认值	描述
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径
`--host TEXT`	`127.0.0.1`	服务器绑定的主机
`--port INTEGER`	`2024`	服务器绑定的端口
`--no-reload`		禁用自动重载
`--n-jobs-per-worker INTEGER`		每个 worker 的作业数。默认为 10
`--debug-port INTEGER`		调试器监听的端口
`--wait-for-client`	`False`	在启动服务器之前等待调试器客户端连接到调试端口
`--no-browser`		服务器启动时不自动打开浏览器
`--studio-url TEXT`		要连接的 Studio 实例的 URL。默认为 https://smith.langchain.com
`--allow-blocking`	`False`	不对代码中的同步 I/O 阻塞操作抛出错误（`0.2.6` 中新增）
`--tunnel`	`False`	通过公共隧道（Cloudflare）暴露本地服务器，以便远程前端访问。这可以避免 Safari 等浏览器或网络阻止 localhost 连接的问题
`--help`		显示命令文档

`build`

构建 LangSmith API 服务器的 Docker 镜像。

用法

langgraph build [OPTIONS]

选项

选项	默认值	描述
`--platform TEXT`		构建 Docker 镜像的目标平台。示例：`langgraph build --platform linux/amd64,linux/arm64`
`-t, --tag TEXT`		必需。Docker 镜像的标签。示例：`langgraph build -t my-image`
`--pull / --no-pull`	`--pull`	使用最新的远程 Docker 镜像进行构建。使用 `--no-pull` 则通过本地构建的镜像运行 LangSmith API 服务器。
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--build-command TEXT`^*		要运行的构建命令。从 `langgraph.json` 文件所在目录运行。示例：`langgraph build --build-command "yarn run turbo build"`
`--install-command TEXT`^*		要运行的安装命令。从你调用 `langgraph build` 的目录运行。示例：`langgraph build --install-command "yarn install"`
`--help`		显示命令文档。

^*仅支持 JS 部署，对 Python 部署没有影响。

`deploy`

NOTE

此命令处于 beta 阶段，并正在积极开发中。预计会有频繁的更新和改进。

构建 LangGraph 镜像并直接部署到 LangSmith Deployments。该命令会在本地构建 Docker 镜像、将其推送到托管镜像仓库，并创建或更新部署——全部在一步内完成。如果未安装 Docker，它会触发远程构建。

前置条件

一个具有 Deployments 访问权限的 LangSmith API key。
（可选）本地构建必须安装 Docker 且 Docker 守护进程必须正在运行。远程构建不需要。安装 Docker Desktop。

NOTE

在 LangSmith Cloud 上，CLI 会推送到托管镜像仓库。自托管 LangSmith，以及通过你自己集群中的 listener 进行部署的云工作区，则会通过 --push-to 推送到你管理的镜像仓库。参见从你管理的镜像仓库部署。

用法

langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS]

该命令还接受 langgraph build 的所有标志（--platform、-t、--pull、--no-pull、-c）。有关详情，请参阅 langgraph build --help。

选项

选项	默认值	描述
`--api-key TEXT`		LangSmith Deployments 的 API key。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量或 `.env` 文件设置。
`--name TEXT`	当前目录名	部署名称。也可以通过 `LANGSMITH_DEPLOYMENT_NAME` 环境变量或 `.env` 文件设置。
`--deployment-id TEXT`		要更新的现有部署的 ID。如果省略，则使用 `--name` 来查找或创建部署。
`--deployment-type TEXT`	`serverless`	在 Cloud 上创建新部署时的部署类型：在新的按用量计费模式下为 `serverless` 或 `dedicated`；对于仍使用旧计费方式的组织为 `dev` 或 `prod`。
`--remote / --no-remote`		强制远程或本地构建。默认情况下，如果本地没有可用的 Docker，则进行远程构建。
`--push-to TEXT`		将镜像推送到你管理的镜像仓库中的该仓库（例如 `123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent`），然后从该仓库部署。自托管 LangSmith 以及通过 listener 部署的工作区必需此选项。使用你现有的 Docker 凭证。可以在值中给出标签，或使用 `-t` 指定。不能与 `--remote` 同时使用。
`--image TEXT`		使用已有的本地镜像（例如 `my-agent:dev`）而不是进行构建。该镜像必须面向 `linux/amd64`。配合 `--push-to` 使用时，镜像会被重新打标签并推送。
`-t, --tag TEXT`	`latest`	已推送镜像的标签。
`--listener-id TEXT`		运行该部署的 listener，适用于通过你自己集群中的 listener 部署的工作区。仅在使用 `--push-to` 创建部署时使用。在 LangSmith Cloud 上，默认为工作区唯一的 listener。
`--k8s-namespace TEXT`		listener 部署到的 Kubernetes 命名空间。仅在使用 `--push-to` 创建部署时使用。默认为该 listener 唯一的命名空间。
`--no-wait`	`False`	推送后跳过等待部署状态。
`--verbose`	`False`	显示详细输出，包括 Docker 构建和推送日志。
`--help`		显示命令文档。

NOTE

在新的按用量计费模式下，请传入 --deployment-type serverless 或 --deployment-type dedicated。在 2026 年 10 月 1 日之前仍使用旧计费方式的组织，请传入 --deployment-type dev 或 --deployment-type prod 以创建 Development 或 Production 部署。有关过渡时间表，请参阅管理计费。

示例

bash

# Deploy with API key from .env file
langgraph deploy

# Deploy with inline API key
LANGSMITH_API_KEY=lsv2_... langgraph deploy

# Update an existing deployment
langgraph deploy --deployment-id abc123

# Deploy with inline deployment name
LANGSMITH_DEPLOYMENT_NAME=my-agent langgraph deploy

# Deploy to EU region
LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com langgraph deploy

NOTE

通过其他方式（例如 LangSmith UI 或 GitHub 集成）创建的部署，也可以使用 langgraph deploy 命令进行更新。

从你管理的镜像仓库部署

自托管 LangSmith，以及通过你自己集群中的 listener 部署的 LangSmith Cloud 工作区（传统混合模式），会从你管理的镜像仓库运行镜像。请传入 --push-to 并指定该镜像仓库中的仓库。CLI 会构建镜像，使用你现有的 Docker 凭证推送它，并从已推送的镜像创建或更新部署。

bash

# Log in to your registry first, for example with AWS ECR
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Self-hosted: point the CLI at your LangSmith instance
LANGSMITH_ENDPOINT=https://langsmith.example.com/api \
langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent

# LangSmith Cloud workspace with a listener: only the image location changes
langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent --tag v1.2.0

# Push an image you already built
langgraph deploy --image my-agent:dev --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent

控制平面 URL 由 LANGSMITH_ENDPOINT 推导而来，该变量从项目的 .env 文件或环境中读取：对于自托管实例为 https://<host>/api-host，对于云端点则为对应的 LangSmith Cloud 控制平面。若要覆盖它，请将 LANGGRAPH_HOST_URL 环境变量设置为完整的控制平面 URL，自托管实例需包含 /api-host（例如 https://langsmith.example.com/api-host）。

选择 listener 与命名空间

当工作区通过 listener 部署时，控制平面需要知道哪个 listener 运行新部署，以及它部署到哪个 Kubernetes 命名空间。

在 LangSmith Cloud 上，如果只有一个可能的答案，你无需传入两者。如果你的工作区只有一个 listener 且该 listener 只服务于一个命名空间，CLI 会使用它：

bash

langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent

当存在选择时，CLI 会列出各 listener 及其集群和命名空间，由你选择其中一个：

bash

langgraph deploy --push-to 123456789.dkr.ecr.us-east-1.amazonaws.com/agents/my-agent \
  --listener-id 2b1f0e9c-2d4a-4f1e-9a3b-2c7d8e5f4a10 --k8s-namespace agents

在自托管实例上，只有当你传入 --listener-id 或 --k8s-namespace 时，CLI 才会查找 listener。

listener 和命名空间在创建部署时即被固定，之后无法更改，因此对已存在的部署会拒绝这两个选项。后续的修订只需要 --push-to。

使用 --push-to 创建的部署使用 external_docker 源。未使用 --push-to 创建的部署无法切换到该源；请改用新的 --name。

`deploy list`

列出 LangSmith Deployments。

用法

bash

langgraph deploy list [OPTIONS]

选项

选项	默认值	描述
`--name-contains TEXT`		仅显示名称包含该值的部署。
`--api-key TEXT`		API key。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量或 `.env` 文件设置。
`--help`		显示此消息并退出。

`deploy revisions`

[Beta] 管理部署修订版本。

用法

bash

langgraph deploy revisions [OPTIONS] COMMAND [ARGS]...

选项

选项	默认值	描述
`--help`		显示此消息并退出。

命令

命令	描述
`list`	[Beta] 列出 LangSmith Deployment 的修订版本。

`deploy revisions list`

[Beta] 列出 LangSmith Deployment 的修订版本。

使用 deploy list 列出部署 ID。

用法

bash

langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID

选项

选项	默认值	描述
`--limit INTEGER`	`10`	返回的修订版本最大数量。
`--api-key TEXT`		API key。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量或 `.env` 文件设置。
`--help`		显示此消息并退出。

`deploy delete`

删除一个 LangSmith Deployment。

使用 deploy list 找到要删除的部署 ID。

用法

bash

langgraph deploy delete [OPTIONS] DEPLOYMENT_ID

选项

选项	默认值	描述
`--force`		删除时无需确认提示。
`--api-key TEXT`		API key。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量或 `.env` 文件设置。
`--help`		显示此消息并退出。

`deploy logs`

获取 LangSmith Deployment 日志。使用 deploy 获取智能体运行时日志，或使用 build 获取远程构建日志。

用法

bash

langgraph deploy logs [OPTIONS]

选项

选项	默认值	描述
`-f, --follow`	`False`	持续轮询新日志。
`--end-time TEXT`		ISO8601 结束时间。示例：`2026-03-08T00:00:00Z`。
`--start-time TEXT`		ISO8601 开始时间。示例：`2026-03-08T00:00:00Z`。
`-q, --query TEXT`		搜索字符串过滤器。
`--limit INTEGER`	`100`	获取的最大日志条目数。
`--level [DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL]`		按日志级别过滤。
`--revision-id TEXT`		指定的修订版本 ID。对于构建日志，默认为最新修订版本。
`--type [deploy\|build]`	`deploy`	要获取的日志流。`deploy` 显示智能体服务器运行时日志。`build` 显示远程构建日志。
`--deployment-id TEXT`		部署 ID。如果省略，则使用 `--name` 查找部署。
`--name TEXT`	当前目录名称	部署名称。也可以通过 `LANGSMITH_DEPLOYMENT_NAME` 环境变量或 `.env` 文件设置。在未提供 `--deployment-id` 时使用。
`--api-key TEXT`		API key。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量或 `.env` 文件设置。
`--help`		显示此消息并退出。

`up`

启动 LangGraph API 服务器。进行本地测试需要一个可访问 LangSmith 的 LangSmith API key。生产环境使用需要 license key。

TIP

如果你需要了解何时使用 langgraph dev 与 langgraph up 的更多信息，请参阅本地开发与测试指南获取详细对比。

用法

langgraph up [OPTIONS]

选项

选项	默认值	描述
`--wait`		等待服务启动后再返回。隐含 --detach
`--base-image TEXT`	`langchain/langgraph-api`	用于 LangGraph API 服务器的基础镜像。可使用版本标签锁定到特定版本。
`--image TEXT`		用于 langgraph-api 服务的 Docker 镜像。如果指定，则跳过构建并直接使用该镜像。
`--postgres-uri TEXT`	本地数据库	用于数据库的 Postgres URI。
`--watch`		文件变更时重启
`--debugger-base-url TEXT`	`http://127.0.0.1:[PORT]`	调试器用于访问 LangGraph API 的 URL。
`--debugger-port INTEGER`		在本地拉取调试器镜像，并在指定端口上提供 UI
`--verbose`		显示更多来自服务器日志的输出。
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`-d, --docker-compose FILE`		包含要启动的附加服务的 docker-compose.yml 文件路径。
`-p, --port INTEGER`	`8123`	要暴露的端口。示例：`langgraph up --port 8000`
`--pull / --no-pull`	`pull`	拉取最新镜像。使用 `--no-pull` 以本地构建的镜像运行服务器。示例：`langgraph up --no-pull`
`--recreate / --no-recreate`	`no-recreate`	即使容器的配置和镜像未发生变化，也重新创建容器
`--help`		显示命令文档。

`dockerfile`

生成用于构建 LangSmith API 服务器 Docker 镜像的 Dockerfile。

用法

langgraph dockerfile [OPTIONS] SAVE_PATH

选项

选项	默认值	描述
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--help`		显示此消息并退出。

示例：

bash

langgraph dockerfile -c langgraph.json Dockerfile

这将生成一个类似如下的 Dockerfile：

dockerfile

FROM langchain/langgraph-api:3.11

ADD ./pipconf.txt /pipconfig.txt

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_anthropic langchain_openai wikipedia scikit-learn

ADD ./graphs /deps/__outer_graphs/src
RUN set -ex && \
    for line in '[project]' \
                'name = "graphs"' \
                'version = "0.1"' \
                '[tool.setuptools.package-data]' \
                '"*" = ["**/*"]'; do \
        echo "$line" >> /deps/__outer_graphs/pyproject.toml; \
    done

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*

ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}'

NOTE

langgraph dockerfile 命令会将你 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，每当你更新 langgraph.json 文件，都必须重新运行它。否则，在构建或运行该 dockerfile 时，你的更改将不会生效。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织