LangGraph CLI¶
LangGraph CLI 是一個命令列工具,用於在本地建置和運行 Agent Server。產生的 Agent Server 會公開所有用於 runs、threads、assistants 等的 API 端點,並包含一些支援服務,例如用於檢查點和儲存的託管資料庫。
Installation¶
- 確保已安裝 Docker (e.g.,
docker --version) -
安裝 CLI
-
驗證安裝
Info
Usage: langgraph [OPTIONS] COMMAND [ARGS]... Options: --version Show the version and exit. --help Show this message and exit. Commands: build 📦 Build LangGraph API server Docker image. dev 🏃♀️➡️ Run LangGraph API server in development mode with... dockerfile 🐳 Generate a Dockerfile for the LangGraph API server, with... new 🌱 Create a new LangGraph project from a template. up 🚀 Launch LangGraph API server
Quick commands¶
| Command | What it does |
|---|---|
langgraph dev | 啟動一個輕量級的本機開發伺服器(無需 Docker),非常適合快速測試。 |
langgraph build | 建置 LangGraph API 伺服器的 Docker 映像以進行部署。 |
langgraph dockerfile | 產生一個基於你的配置的 Dockerfile,用於自訂建置。 |
langgraph up | 在本機 Docker 容器中啟動 LangGraph API 伺服器。需要 Docker 運作;本機開發環境需要 LangSmith API 金鑰;生產環境需要授權。 |
對於 JS,請使用 npx @langchain/langgraph-cli <command>(如果 globally 安裝了 langgraphjs,則可以使用 langgraphjs)。
Configuration file¶
要建置和運行有效的應用程序,LangGraph CLI 需要一個符合以下 schema 的 JSON 設定檔。它包含以下屬性:
Info
LangGraph CLI 預設使用目前目錄中名為 langgraph.json 的設定檔。
| Key | Description |
|---|---|
dependencies | Required. LangSmith API 伺服器的依賴項列垃。依賴項可以是以下幾種:
|
graphs | Required. 將 graph ID 對應到已編譯 graph 或產生 graph 的函數所在的路徑。 Example:
|
auth | (Added in v0.0.11) 身份驗證配置,包含身份驗證處理程序的路徑。Example: ./your_package/auth.py:auth,其中 auth 是 langgraph_sdk.Auth 查看 authentication guide 了解更多詳情。 |
base_image | Optional. 用於 LangGraph API 伺服器的基礎鏡像。預設為 langchain/langgraph-api 或 langchain/langgraphjs-api。使用此選項可將建置版本鎖定至特定版本的 LangGraph API,例如 "langchain/langgraph-server:0.2"。 查看 https://hub.docker.com/r/langchain/langgraph-server/tags 了解更多詳情。(added in langgraph-cli==0.2.8) |
image_distro | Optional. 基礎鏡像的 Linux 發行版。必須是 "debian"、"wolfi"、"bookworm" 或 "bullseye" 之一。如果省略,則預設為 "debian"。適用於 langgraph-cli>=0.2.11。 |
env | .env 檔案的路徑或環境變數與其值的對應。 |
store | 用於在 BaseStore 中新增語義搜尋和/或生存時間 (TTL) 的配置。包含以下欄位:
|
ui | Optional. 由 agent 程式發出的 UI 元件的命名定義,每個定義都指向一個 JS/TS 檔案。(added in 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 | (Added in v0.3) Optional. Python 套件安裝程式選擇器。它可以設定為 "auto"、"pip" 或 "uv"。從 0.3 版本開始,預設策略是運行 uv pip,這通常可以加快建置速度,同時保持無縫替換。在極少數情況下,如果 uv 無法處理您的依賴關係或 pyproject.toml 檔案的結構,請在此處指定 "pip" 以恢復到先前的行為。 |
keep_pkg_tools | (Added in v0.3.4) Optional. 控制是否在最終映像中保留 Python 打包工具(pip、setuptools、wheel)。可接受的值:
|
dockerfile_lines | 從父映像匯入後,要新增至 Dockerfile 中的附加行列表。 |
checkpointer | Checkpointer 配置。支持:
|
http | HTTP 伺服器配置,包含以下欄位:
|
api_version | (Added in v0.3.7) 要使用哪個語意版本的 LangGraph API 伺服器 (e.g., "0.3")。 預設使用最新版本。請查看伺服器變更日誌以了解每個版本的詳細資訊。 |
| Key | Description |
|---|---|
graphs | Required. 將 graph ID 對應到已編譯 graph 或產生 graph 的函數所在的路徑。 Example:
|
env | .env 檔案的路徑或環境變數與其值的對應。 |
store | 用於在 BaseStore 中新增語義搜尋和/或生存時間 (TTL) 的配置。包含以下欄位:
|
node_version | 指定 node_version: 20 以使用 LangGraph.js。 |
dockerfile_lines | 從父映像匯入後,要新增至 Dockerfile 中的附加行列表。 |
checkpointer | 檢查點配置。支持:
|
http | HTTP 伺服器配置與 Python 選項相對應:
|
api_version | (Added in v0.3.7) 要使用哪個語意版本的 LangGraph API 伺服器 (e.g., "0.3")。 efaults 更新至最新版本。請查看伺服器變更日誌以了解每個版本的詳細資訊。 |
Examples¶
Basic configuration
{
"$schema": "https://langgra.ph/schema.json",
"dependencies": ["."],
"graphs": {
"chat": "chat.graph:graph"
}
}
Using Wolfi base images
您可以使用 image_distro 欄位指定基礎鏡像的 Linux 發行版。有效選項包括 debian, wolfi, bookwor 和 bullseye。建議使用 Wolfi,因為它提供的鏡像體積更小、安全性更高。此功能在 langgraph-cli >= 0.2.11 版本中可用。
{
"$schema": "https://langgra.ph/schema.json",
"dependencies": ["."],
"graphs": {
"chat": "chat.graph:graph"
},
"image_distro": "wolfi"
}
Adding semantic search to the store
所有部署都包含一個基於資料庫的 BaseStore。在 langgraph.json 檔案中新增 index配置即可在部署的 BaseStore 中啟用語意搜尋。
index.fields 配置決定了要嵌入文件的哪些部分: - 如果省略或設定為 ["$"],則會嵌入整個文件。 - 若要嵌入特定字段,請使用 JSON 路徑表示法:["metadata.title", "content.text"] - 缺少指定欄位的文件仍會被存儲,但不會嵌入這些欄位。 - 您仍然可以在建立文件時使用 index 參數來覆蓋要嵌入的欄位。
{
"dependencies": ["."],
"graphs": {
"memory_agent": "./agent/graph.py:graph"
},
"store": {
"index": {
"embed": "openai:text-embedding-3-small",
"dims": 1536,
"fields": ["$"]
}
}
}
Common model dimensions
- 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
Semantic search with a custom embedding function
如果要將語義搜尋與自訂嵌入函數一起使用,可以將自訂嵌入函數的路徑傳遞給它:
{
"dependencies": ["."],
"graphs": {
"memory_agent": "./agent/graph.py:graph"
},
"store": {
"index": {
"embed": "./embeddings.py:embed_texts",
"dims": 768,
"fields": ["text", "summary"]
}
}
}
Store 配置中的 embed 欄位可以引用自訂函數,該函數接受字串列表並傳回一個嵌入列表。範例實作:
# 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
Adding custom authentication
{
"$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
}
}
有關詳細信息,請參閱身份驗證概念指南;有關流程的實際操作步驟,請參閱設定自訂身份驗證指南。
Configuring store item Time-to-Live
您可以使用 store.ttl 鍵為 BaseStore 中的項目/記憶體配置預設資料過期時間。此鍵決定了專案在上次存取後保留的時間(讀取操作可能會根據 refresh_on_read 刷新計時器)。請注意,這些預設值可以透過修改 get, search 等方法中的對應參數來逐次覆寫。
ttl 配置是一個包含可選字段的物件:
refresh_on_read: 如果為真(預設值),則透過get或search存取項目時會重設其過期計時器。設定為false則僅在寫入put操作時刷新 TTL。default_ttl: Item 的預設生存時間(以分鐘為單位)。僅適用於新創建的 item;現有 item 不會被修改。如果未設置,item 預設不會過期。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
}
}
}
Configuring checkpoint Time-to-Live 您可以使用檢查點鍵配置檢查點的生存時間 (TTL)。這決定了檢查點資料在根據指定策略(例如,刪除)自動處理之前保留多長時間。支援兩個可選子物件:
ttl: 包括 strategy、sweep_interval_minutes 和 default_ttl,它們共同決定檢查點的過期時間。serde(Agent server 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 分鐘運行一次。
Configuring checkpointer 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"]
]
}
}
}
Customizing HTTP middleware and headers
http 配置區塊可讓您微調請求處理:
middleware_order: 選擇auth_first可在中間件之前執行身份驗證,或選擇middleware_first(預設)以反轉該順序。enable_custom_route_auth: 將身份驗證擴展到透過 http.app 掛載的路由。configurable_headers / logging_headers: 每個函數都接受一個 object,該 object 帶有可選的包含和排除數組;支援通配符,排除操作在包含操作之前執行。cors: 除了allow_origins,allow_methods和allow_headers之外,您還可以設定allow_credentials,allow_origin_regex,expose_headers和max_age來進行更詳細的瀏覽器控制。
Pinning API version
您可以使用 api_version 鍵來鎖定代理伺服器的 API 版本。如果您希望確保伺服器使用特定版本的 API,這將非常有用。預設情況下,雲端部署中的建置使用伺服器的最新穩定版本。您可以將 api_version 鍵設定為特定版本來鎖定此版本。
Basic configuration
Pinning API version
您可以使用 api_version 鍵來鎖定 Agent Server 的 API 版本。如果您希望確保伺服器使用特定版本的 API,這將非常有用。預設情況下,雲端部署中的建置使用伺服器的最新穩定版本。您可以將 api_version 鍵設定為特定版本來鎖定此版本。
Commands¶
Usage
dev¶
以開發模式運行 LangGraph API 伺服器,支援熱重載和調試功能。這款輕量級伺服器無需安裝 Docker,適用於開發和測試。狀態持久化到本地目錄。
Info
目前,CLI 僅支援 Python >= 3.11。
Installation
此命令需要安裝 "inmem" 附加元件:
Usage
Options
| Option | Default | Description |
|---|---|---|
-c, --config FILE | langgraph.json | 配置檔案路徑,該檔案聲明依賴項、graph 和環境變數 |
--host TEXT | 127.0.0.1 | 要將伺服器綁定到的 host name |
--port INTEGER | 2024 | 伺服器綁定的 port |
--no-reload | 停用自動重新加載 | |
--n-jobs-per-worker INTEGER | 每位 worker 負責的工作數。預設值為 10。 | |
--debug-port INTEGER | 調試器監聽的 port | |
--wait-for-client | False | 等待 debugger client 連接到調試連接埠後再啟動伺服器。 |
--no-browser | 伺服器啟動時跳過自動開啟瀏覽器的操作 | |
--studio-url TEXT | 要連線的 LangSmith Studio 實例的 URL。預設為 https://smith.langchain.com | |
--allow-blocking | False | 不要在程式碼中對同步 I/O 阻塞操作引發錯誤(0.2.6 版本新增) |
--tunnel | False | 透過公共 tunnel(例如 Cloudflare)暴露本機伺服器,以便進行遠端前端存取。這樣可以避免 Safari 等瀏覽器或網路阻止本地主機連線的問題。 |
--help | 顯示 command 文檔 |
build¶
Options
| Option | Default | Description |
|---|---|---|
--platform TEXT | 要建置 Docker 映像的目標平台。例如: langgraph build --platform linux/amd64,linux/arm64 | |
-t, --tag TEXT | Required. Docker映像的標籤。例如: langgraph build -t my-image | |
--no-pull | 使用本地建置的鏡像。預設為 false,即使用最新的遠端 Docker 映像進行建置。 | |
-c, --config FILE | langgraph.json | 設定檔路徑,用於聲明依賴項、graph 和環境變數。 |
--help | 顯示 command 文件。 |
up¶
Options
| Option | Default | Description |
|---|---|---|
--wait | 等待服務啟動後再返回。 | |
--base-image TEXT | langchain/langgraph-api | 用於 LangGraph API 伺服器的基礎鏡像。使用版本標籤鎖定到特定版本。 |
--image TEXT | 用於 langgraph-api 服務的 Docker 映像。如果指定,則跳過建置步驟並直接使用此鏡像。 | |
--postgres-uri TEXT | Local database | 要用於資料庫的Postgres URI。 |
--watch | 文件更改後重新啟動 | |
-c, --config FILE | langgraph.json | 設定檔路徑,用於聲明依賴項、graph 和環境變數。 |
-d, --docker-compose FILE | 包含要啟動的其他服務的 docker-compose.yml 檔案路徑。 | |
-p, --port INTEGER | 8123 | 要暴露的連接埠。例如:langgraph up --port 8000 |
--no-pull | 使用本地建置的鏡像。預設為 false,即使用最新的遠端 Docker 映像進行建置。 | |
--recreate | 即使容器的配置和鏡像沒有改變,也要重新建立容器。 | |
--help | 顯示 command 文件。 |
dockerfile¶
產生用於建置 LangSmith API 伺服器 Docker 映像的 Dockerfile。
Usage
Options
| Option | Default | Description |
|---|---|---|
-c, --config FILE | langgraph.json | 設定檔路徑,該檔案聲明依賴項、graph 和環境變數。 |
--help | 顯示此訊息並退出。 |
Example
這將產生一個類似於以下內容的 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"}'
Info
langgraph dockerfile 指令會將 langgraph.json 檔案中的所有設定轉換為 Dockerfile 指令。使用此命令時,每次更新 langgraph.json 檔案後都需要重新執行它。否則,在建置或執行 Dockerfile 時,您的變更將不會生效。
產生用於建置 LangSmith API 伺服器 Docker 映像的 Dockerfile。
Usage
Options
| Option | Default | Description |
|---|---|---|
-c, --config FILE | langgraph.json | 設定檔路徑,該檔案聲明依賴項、graph 和環境變數。 |
--help | 顯示此訊息並退出。 |
Example
這將產生一個類似於以下內容的 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
Info
npx @langchain/langgraph-cli dockerfile 指令會將 langgraph.json 檔案中的所有設定轉換為 Dockerfile 指令。使用此命令後,每次更新 langgraph.json 檔案時都需要重新執行它。否則,在建置或執行 Dockerfile 時,您的變更將不會生效。