langgraph-cli

`langgraph` CLI は、新しいプロジェクトのひな形作成から LangGraph Platform（LangSmith Deployments）へのデプロイまで、LangGraph アプリケーションのライフサイクル全体を管理します。

主なコマンド：

• 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）では、linux/amd64 向けのクロスコンパイルに Docker Buildx も必要です。

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、または 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
主な用途	迅速な開発とテスト	本番環境に近い状態での検証
状態の永続化	インメモリ／ローカルディレクトリへの pickle 保存	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）に依存している場合は、ローカルにインストールする必要があります。Docker ビルドの検証には langgraph up を使用してください。
• 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 を使って設定することもできます。