LangGraph CLI 是一个用于在本地构建和运行代理服务器的命令行工具。生成的服务器会暴露所有用于运行、线程、助手等的 API 端点,并包含支持服务,例如用于检查点和存储的托管数据库。
-
确保已安装 Docker(例如,
docker --version)。
-
安装 CLI:
pip install langgraph-cli
-
验证安装
快速命令
| 命令 | 功能 |
|---|
langgraph dev | 启动一个轻量级的本地开发服务器(无需 Docker),非常适合快速测试。 |
langgraph build | 构建你的 LangGraph API 服务器的 Docker 镜像,用于部署。 |
langgraph deploy | 一步构建并直接将 LangGraph 镜像部署到 LangSmith 部署。 |
langgraph dockerfile | 从你的配置生成一个 Dockerfile,用于自定义构建。 |
langgraph up | 在 Docker 中本地启动 LangGraph API 服务器。需要 Docker 正在运行;本地开发需要 LangSmith API 密钥;生产环境需要许可证。 |
对于 JS,使用 npx @langchain/langgraph-cli <command>(如果全局安装,则使用 langgraphjs)。
配置文件
要构建和运行一个有效的应用程序,LangGraph CLI 需要一个遵循此模式的 JSON 配置文件。它包含以下属性:
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 中添加) 包含认证处理器路径的认证配置。示例:./your_package/auth.py:auth,其中 auth 是 langgraph_sdk.Auth 的实例。有关详细信息,请参阅认证指南。 |
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 的对象,用于控制检查点过期。serde(可选,0.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:选择自定义中间件和认证如何交互。auth_first 在自定义中间件之前运行认证钩子,而 middleware_first(默认)先运行你的中间件。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")。默认为最新版本。请查看服务器更新日志以获取每个版本的详细信息。 |
| 键 | 描述 |
|---|
graphs | 必需。从图 ID 到定义编译图或创建图的函数的路径的映射。示例: |
env | .env 文件的路径或从环境变量到其值的映射。 |
store | 用于向 BaseStore 添加语义搜索和/或生存时间(TTL)的配置。包含以下字段:index(可选):语义搜索索引配置,包含字段 embed、dims 和可选的 fields。ttl(可选):项目过期配置。一个包含可选字段的对象:refresh_on_read(布尔值,默认为 true)、default_ttl(浮点数,生命周期以分钟为单位;仅应用于新创建的项目;现有项目不变;默认为不过期)和 sweep_interval_minutes(整数,检查过期项目的频率,默认为不扫描)。
|
node_version | 指定 node_version: 20 以使用 LangGraph.js。 |
dockerfile_lines | 在从父镜像导入后添加到 Dockerfile 的附加行数组。 |
checkpointer | 检查点配置。支持:backend(可选):"default"、"mongo" 或 "custom"。默认为 "default"(PostgreSQL)。请参阅配置检查点后端。path(可选):自定义检查点工厂的路径(当 backend 为 "custom" 时)。请参阅自定义检查点。ttl(可选):包含 strategy、sweep_interval_minutes、default_ttl 的对象,用于控制检查点过期。serde(可选,0.5+):包含 allowed_json_modules 和 pickle_fallback 的对象,用于调整反序列化行为。
|
http | HTTP 服务器配置,镜像 Python 选项:cors,包含 allow_origins、allow_methods、allow_headers、allow_credentials、allow_origin_regex、expose_headers、max_age。configurable_headers 和 logging_headers 模式列表。middleware_order(auth_first 或 middleware_first)。enable_custom_route_auth 以及与上述相同的布尔路由切换。
|
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")。默认为最新版本。请查看服务器更新日志以获取每个版本的详细信息。 |
基本配置
{
"$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 中可用。{
"$schema": "https://langgra.ph/schema.json",
"dependencies": ["."],
"graphs": {
"chat": "chat.graph:graph"
},
"image_distro": "wolfi"
}
向存储添加语义搜索
所有部署都附带一个基于数据库的 BaseStore。向你的 langgraph.json 添加 “index” 配置将启用部署中 BaseStore 的语义搜索。index.fields 配置决定了文档的哪些部分需要嵌入:
- 如果省略或设置为
["$"],则整个文档将被嵌入
- 要嵌入特定字段,请使用 JSON 路径表示法:
["metadata.title", "content.text"]
- 缺少指定字段的文档仍将被存储,但这些字段不会有嵌入
- 你仍然可以在
put 时使用 index 参数覆盖特定项目的嵌入字段
{
"dependencies": ["."],
"graphs": {
"memory_agent": "./agent/graph.py:graph"
},
"store": {
"index": {
"embed": "openai:text-embedding-3-small",
"dims": 1536,
"fields": ["$"]
}
}
}
常见模型维度
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
使用自定义嵌入函数进行语义搜索
如果你想使用带有自定义嵌入函数的语义搜索,可以传递自定义嵌入函数的路径:{
"dependencies": ["."],
"graphs": {
"memory_agent": "./agent/graph.py:graph"
},
"store": {
"index": {
"embed": "./embeddings.py:embed_texts",
"dims": 768,
"fields": ["text", "summary"]
}
}
}
存储配置中的 embed 字段可以引用一个接受字符串列表并返回嵌入列表的自定义函数。示例实现:# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
"""用于语义搜索的自定义嵌入函数。"""
# 使用你首选的嵌入模型的实现
return [[0.1, 0.2, ...] for _ in texts] # 维度向量
添加自定义认证
{
"$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
}
}
有关详细信息,请参阅认证概念指南,有关实际操作过程,请参阅设置自定义认证指南。配置存储项目生存时间
你可以使用 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 分钟)、在读取时刷新并每小时扫描一次的示例:{
"$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,共同设置检查点如何过期。
serde (代理服务器 0.5+):允许你控制检查点有效负载的反序列化行为。
以下是设置默认 TTL 为 30 天(43200 分钟)的示例:{
"$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 反序列化。
{
"checkpointer": {
"serde": {
"allowed_json_modules": [
["my_agent", "auth", "SessionState"]
]
}
}
}
自定义 HTTP 中间件和头
http 块允许你微调请求处理:
-
middleware_order:选择 "auth_first" 在你的中间件之前运行认证,或选择 "middleware_first"(默认)反转该顺序。
-
enable_custom_route_auth:将认证扩展到你通过 http.app 挂载的路由。
-
configurable_headers / logging_headers:每个接受一个包含可选 includes 和 excludes 数组的对象;支持通配符,并且排除在包含之前运行。
-
cors:自定义服务器的 CORS(跨源资源共享)配置。用于配置 CORS 的示例 langgraph.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
}
},
...
}
配置 webhooks
你可以为出站 webhook 请求配置自定义头和 URL 限制:{
"$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 键固定代理服务器的 API 版本。如果你想确保服务器使用特定版本的 API,这很有用。
默认情况下,云部署中的构建使用服务器的最新稳定版本。可以通过将 api_version 键设置为特定版本来固定。{
"$schema": "https://langgra.ph/schema.json",
"dependencies": ["."],
"graphs": {
"chat": "chat.graph:graph"
},
"api_version": "0.2"
}
禁用内置路由
你可以使用 http 配置块中的布尔标志选择性地禁用内置 HTTP 路由组。这对于希望最小化服务器暴露面的生产部署很有用。例如,要禁用系统信息和文档路由:{
"$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 文档 UI
/openapi.json — OpenAPI 规范
即使设置了 disable_meta,/ok 健康检查端点仍然可用,因此 Kubernetes 等编排器仍然可以执行活性探针和就绪探针。其他路由禁用标志包括 disable_assistants、disable_runs、disable_threads、disable_store 和 disable_ui。有关 MCP、A2A 和 webhooks,请参阅各自的指南:禁用 MCP、禁用 A2A、禁用 webhooks。基本配置
{
"$schema": "https://langgra.ph/schema.json",
"graphs": {
"chat": "./src/graph.ts:graph"
}
}
固定 API 版本
(在 v0.3.7 中添加)你可以使用 api_version 键固定代理服务器的 API 版本。如果你想确保服务器使用特定版本的 API,这很有用。
默认情况下,云部署中的构建使用服务器的最新稳定版本。可以通过将 api_version 键设置为特定版本来固定。{
"$schema": "https://langgra.ph/schema.json",
"dependencies": ["."],
"graphs": {
"chat": "./src/chat/graph.ts:graph"
},
"api_version": "0.2"
}
禁用内置路由
你可以使用 http 配置块中的布尔标志选择性地禁用内置 HTTP 路由组。这对于希望最小化服务器暴露面的生产部署很有用。例如,要禁用系统信息和文档路由:{
"$schema": "https://langgra.ph/schema.json",
"graphs": {
"chat": "./src/chat/graph.ts:graph"
},
"http": {
"disable_meta": true
}
}
将 disable_meta 设置为 true 会禁用以下路由:
/ — 根健康检查
/info — 服务器版本和配置信息
/metrics — Prometheus 和 JSON 指标
/docs — API 文档 UI
/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]
LangGraph.js CLI 的基础命令是 langgraphjs。npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS]
我们建议使用 npx 始终使用最新版本的 CLI。
dev
以开发模式运行 LangGraph API 服务器,支持热重载和调试功能。这个轻量级服务器不需要 Docker 安装,适合开发和测试。状态持久化到本地目录。目前,CLI 仅支持 Python >= 3.11。
如果你需要更多信息来了解何时使用 langgraph dev 与 langgraph up,请参阅本地开发和测试指南以获取详细比较。 安装此命令需要安装 “inmem” 扩展:pip install -U "langgraph-cli[inmem]"
用法选项| 选项 | 默认值 | 描述 |
|---|
-c, --config FILE | langgraph.json | 声明依赖项、图和环境变量的配置文件路径 |
--host TEXT | 127.0.0.1 | 绑定服务器的主机 |
--port INTEGER | 2024 | 绑定服务器的端口 |
--no-reload | | 禁用自动重载 |
--n-jobs-per-worker INTEGER | | 每个工作进程的作业数。默认为 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 | | 显示命令文档 |
以开发模式运行 LangGraph API 服务器,支持热重载功能。这个轻量级服务器不需要 Docker 安装,适合开发和测试。状态持久化到本地目录。用法npx @langchain/langgraph-cli dev [OPTIONS]
选项| 选项 | 默认值 | 描述 |
|---|
-c, --config FILE | langgraph.json | 声明依赖项、图和环境变量的配置文件路径 |
--host TEXT | 127.0.0.1 | 绑定服务器的主机 |
--port INTEGER | 2024 | 绑定服务器的端口 |
--no-reload | | 禁用自动重载 |
--n-jobs-per-worker INTEGER | | 每个工作进程的作业数。默认为 10 |
--debug-port INTEGER | | 调试器监听的端口 |
--wait-for-client | False | 在启动服务器之前等待调试器客户端连接到调试端口 |
--no-browser | | 服务器启动时跳过自动打开浏览器 |
--studio-url TEXT | | 要连接的 Studio 实例的 URL。默认为 https://smith.langchain.com |
--allow-blocking | False | 不要为代码中的同步 I/O 阻塞操作引发错误 |
--tunnel | False | 通过公共隧道(Cloudflare)暴露本地服务器,用于远程前端访问。这避免了浏览器或网络阻止 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 部署没有影响。 构建 LangSmith API 服务器 Docker 镜像。用法npx @langchain/langgraph-cli build [OPTIONS]
选项| 选项 | 默认值 | 描述 |
|---|
--platform TEXT | | 构建 Docker 镜像的目标平台。示例:langgraph build --platform linux/amd64,linux/arm64 |
-t, --tag TEXT | | 必需。Docker 镜像的标签。示例:langgraph build -t my-image |
--no-pull | | 使用本地构建的镜像。默认为 false 以使用最新的远程 Docker 镜像进行构建。 |
-c, --config FILE | langgraph.json | 声明依赖项、图和环境变量的配置文件路径。 |
--help | | 显示命令文档。 |
deploy
此命令处于测试阶段,正在积极开发中。预计会有频繁的更新和改进。
构建并直接将 LangGraph 镜像部署到 LangSmith 部署。此命令在本地构建 Docker 镜像,将其推送到托管注册表,并创建或更新部署——所有这些都在一个步骤中完成。先决条件远程构建(无需 Docker)将在未来的更新中推出。
用法langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS]
此命令还接受所有 langgraph build 标志(--platform、-t、--pull、--no-pull、-c)。有关详细信息,请参阅 langgraph build --help。选项| 选项 | 默认值 | 描述 |
|---|
--api-key TEXT | | LangSmith 部署的 API 密钥。也可以通过 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 | dev | 部署类型(dev 或 prod)。在创建新部署时使用。 |
--no-wait | False | 推送后跳过等待部署状态。 |
--verbose | False | 显示详细输出,包括 Docker 构建和推送日志。 |
--help | | 显示命令文档。 |
示例# 使用 .env 文件中的 API 密钥进行部署
langgraph deploy
# 使用内联 API 密钥进行部署
LANGSMITH_API_KEY=lsv2_... langgraph deploy
# 更新现有部署
langgraph deploy --deployment-id abc123
# 使用内联部署名称进行部署
LANGSMITH_DEPLOYMENT_NAME=my-agent langgraph deploy
langgraph deploy 命令只能更新最初由 langgraph deploy 创建的部署。通过其他方法(例如 LangSmith UI 或 GitHub 集成)创建的部署无法使用此命令更新。
deploy list
列出 LangSmith 部署。用法langgraph deploy list [OPTIONS]
选项| 选项 | 默认值 | 描述 |
|---|
--name-contains TEXT | | 仅显示名称包含此值的部署。 |
--api-key TEXT | | API 密钥。也可以通过 LANGGRAPH_HOST_API_KEY、LANGSMITH_API_KEY 或 LANGCHAIN_API_KEY 环境变量或 .env 文件设置。 |
--help | | 显示此消息并退出。 |
deploy revisions
[Beta] 管理部署修订版。用法langgraph deploy revisions [OPTIONS] COMMAND [ARGS]...
选项命令| 命令 | 描述 |
|---|
list | [Beta] 列出 LangSmith 部署的修订版。 |
deploy revisions list
[Beta] 列出 LangSmith 部署的修订版。使用 deploy list 列出部署 ID。用法langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID
选项| 选项 | 默认值 | 描述 |
|---|
--limit INTEGER | 10 | 返回的最大修订版数量。 |
--api-key TEXT | | API 密钥。也可以通过 LANGGRAPH_HOST_API_KEY、LANGSMITH_API_KEY 或 LANGCHAIN_API_KEY 环境变量或 .env 文件设置。 |
--help | | 显示此消息并退出。 |
deploy delete
删除 LangSmith 部署。使用 deploy list 查找要删除的部署 ID。用法langgraph deploy delete [OPTIONS] DEPLOYMENT_ID
选项| 选项 | 默认值 | 描述 |
|---|
--force | | 无需确认即可删除。 |
--api-key TEXT | | API 密钥。也可以通过 LANGGRAPH_HOST_API_KEY、LANGSMITH_API_KEY 或 LANGCHAIN_API_KEY 环境变量或 .env 文件设置。 |
--help | | 显示此消息并退出。 |
deploy logs
获取 LangSmith 部署日志。使用 deploy 获取代理运行时日志,或使用 build 获取远程构建日志。用法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 密钥。也可以通过 LANGGRAPH_HOST_API_KEY、LANGSMITH_API_KEY 或 LANGCHAIN_API_KEY 环境变量或 .env 文件设置。 |
--help | | 显示此消息并退出。 |
启动 LangGraph API 服务器。用于本地测试,需要具有访问 LangSmith 权限的 LangSmith API 密钥。生产使用需要许可证密钥。如果你需要更多信息来了解何时使用 langgraph dev 与 langgraph up,请参阅本地开发和测试指南以获取详细比较。 用法选项| 选项 | 默认值 | 描述 |
|---|
--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 | | 显示命令文档。 |
启动 LangGraph API 服务器。用于本地测试,需要具有访问 LangSmith 权限的 LangSmith API 密钥。生产使用需要许可证密钥。用法npx @langchain/langgraph-cli up [OPTIONS]
选项| 选项 | 默认值 | 描述 |
|---|
--wait | | 等待服务启动后再返回。隐含 —detach |
--base-image TEXT | langchain/langgraph-api | 用于 LangGraph API 服务器的基础镜像。使用版本标签固定到特定版本。 |
--image TEXT | | 用于 langgraph-api 服务的 Docker 镜像。如果指定,则跳过构建并直接使用此镜像。 |
--postgres-uri TEXT | 本地数据库 | 用于数据库的 Postgres URI。 |
--watch | | 文件更改时重新启动 |
-c, --config FILE | langgraph.json | 声明依赖项、图和环境变量的配置文件路径。 |
-d, --docker-compose FILE | | docker-compose.yml 文件的路径,包含要启动的附加服务。 |
-p, --port INTEGER | 8123 | 要暴露的端口。示例:langgraph up --port 8000 |
--no-pull | | 使用本地构建的镜像。默认为 false 以使用最新的远程 Docker 镜像进行构建。 |
--recreate | | 即使容器的配置和镜像未更改也重新创建容器 |
--help | | 显示命令文档。 |
dockerfile
生成用于构建 LangSmith API 服务器 Docker 镜像的 Dockerfile。用法langgraph dockerfile [OPTIONS] SAVE_PATH
选项| 选项 | 默认值 | 描述 |
|---|
-c, --config FILE | langgraph.json | 配置文件的路径,声明依赖项、图和环境变量。 |
--help | | 显示此消息并退出。 |
示例:langgraph dockerfile -c langgraph.json 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_community 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"}'
langgraph dockerfile 命令将你的 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时,每次更新 langgraph.json 文件后都必须重新运行它。否则,你的更改在构建或运行 dockerfile 时不会反映出来。
生成用于构建 LangSmith API 服务器 Docker 镜像的 Dockerfile。用法npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH
选项| 选项 | 默认值 | 描述 |
|---|
-c, --config FILE | langgraph.json | 配置文件的路径,声明依赖项、图和环境变量。 |
--help | | 显示此消息并退出。 |
示例:npx @langchain/langgraph-cli dockerfile -c langgraph.json Dockerfile
这将生成一个类似于以下内容的 Dockerfile:FROM langchain/langgraphjs-api:20
ADD . /deps/agent
RUN cd /deps/agent && yarn install
ENV LANGSERVE_GRAPHS='{"agent":"./src/react_agent/graph.ts:graph"}'
WORKDIR /deps/agent
RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts
npx @langchain/langgraph-cli dockerfile 命令将你的 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时,每次更新 langgraph.json 文件后都必须重新运行它。否则,你的更改在构建或运行 dockerfile 时不会反映出来。
将这些文档连接到 Claude、VSCode 等,通过 MCP 获取实时答案。