LangGraph Studioのデバッグは、グラフ可視化・state確認・Interruptの3操作を押さえれば始められます。2026年10月3日時点の製品ページ名は「LangSmith Studio」です。Python 3.11以上とLangSmith APIキーを用意し、langgraph-cli[inmem]を入れてlanggraph devを実行すると、ローカルのAgent Serverへブラウザ版Studioから接続できます。
- インストール：
pip install -U "langgraph-cli[inmem]" - 可視化：
langgraph.jsonへcompiled graphを登録し、Graph modeでノードとエッジを確認 - 状態確認：thread logを開き、各ノードのstateを
PrettyまたはJSONで比較 - ブレークポイント：
Interruptでノードの実行前または実行後に停止し、Continueで再開
以下では外部LLMを呼ばない最小グラフを使います。モデルAPIの課金や出力の揺らぎを持ち込まず、Studioそのものの操作に集中できる構成です。
LangGraph Studioは現在「LangSmith Studio」
検索では「LangGraph Studio」という名前が広く使われていますが、2026年10月3日時点の製品ページ名はLangSmith Studioです。一方、CLIの出力や一部の公式ページでは、現在も「LangGraph Studio」と表示される場合があります。公式の説明では、Agent Server APIを実装したエージェントを可視化し、実行し、状態を調べるための専用IDEです。旧URLのlangchain-ai.github.io/langgraphは現行のLangChain Docsへ移動しているため、古い画面やインストール方法をそのまま追わないでください。
2024年8月1日のLangGraph Studio発表記事はApple Silicon向けデスクトップアプリを案内していました。その後、2024年11月19日のAgent Protocol発表記事で、ローカルバックエンドとWeb版Studioを組み合わせる方式が公開されました。現在のLangSmith Studioのローカル開発手順も、このブラウザ方式を案内しています。
| 確認項目 | 2026年10月3日時点の選択 | 古い記事で見かける選択 |
|---|---|---|
| 名称 | LangSmith Studio | LangGraph Studio |
| 画面 | ブラウザ版Studio | macOSデスクトップアプリ |
| ローカル起動 | langgraph dev |
デスクトップアプリ内のビルド |
| Docker | devでは不要 |
旧デスクトップ手順では必要 |
| 対応OS | ローカルCLIとブラウザを使える環境 | 旧版はmacOS中心 |
LangGraphのStateGraph、checkpointer、interrupt自体を先に整理したい場合は、既刊のLangGraph完全ガイド｜StateGraph実装とv1.2新機能を参照してください。この記事ではフレームワーク全体の説明を繰り返さず、Studio画面でどこを見て、どう止め、どう分岐させるかに絞ります。
- graph.py：ノード、エッジ、stateを定義する
- langgraph.json：画面へ公開するgraph IDと変数を指定する
- Agent Server：
langgraph devでローカル起動する - LangSmith Studio：ブラウザからグラフ、run、threadを操作する
インストール前にそろえる4項目
公式のStudioセットアップが示す前提は、LangSmithアカウント、LangSmith APIキー、Python 3.11以上、LangGraph CLIです。ローカルのlanggraph devは開発・テスト用の軽量サーバーで、LangGraph CLIリファレンスではDocker不要と明記されています。Dockerが必要なのはlanggraph upやイメージビルドへ進む場面であり、今回の画面デバッグには不要です。
空の作業フォルダで仮想環境を作り、LangGraph本体とCLIを入れます。
動作環境：Python 3.11以上、pip、ブラウザ、LangSmithアカウント。
注意：本番環境で使用する前に、必ずテスト環境で動作確認してください。
mkdir langgraph-studio-debug
cd langgraph-studio-debug
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U langgraph "langgraph-cli[inmem]"Windowsでは仮想環境の有効化コマンドが異なりますが、以後のファイル構成とlanggraph devは同じです。インストール確認は次の1行で行えます。
langgraph --helpプロジェクト直下に.envを作り、LangSmithの設定画面で発行したAPIキーを入れます。値は例示用のプレースホルダーへ置き換えてください。
注意：APIキーをソースコードへ直書きせず、.envをGitの管理対象から外してください。
LANGSMITH_API_KEY=lsv2_replace_with_your_key
# LangSmithへtraceを送信しない場合だけ有効化
LANGSMITH_TRACING=false公式ドキュメントは、LANGSMITH_TRACING=falseを設定するとtraceデータをLangSmithへ送らないと説明しています。ただし、Studioへのログインと接続にはLangSmithアカウントとAPIキーが必要です。チームのデータ取扱方針に合わせて、traceを有効にするか決めてください。なお、現行CLIでは開発サーバーのstateはローカルディレクトリへ保存されます。tracing無効化はローカル保存を消す設定ではないため、機密データの保存・削除方針も別途決めてください。
可視化用の最小グラフを1ファイルで作る
画面操作を確かめるには、外部モデルを呼ぶ複雑なエージェントより、stateの変化が読みやすい決定的なグラフが向いています。次のgraph.pyは入力文字列を整形し、長さを判定し、2経路のどちらかへ送ります。20文字というしきい値は説明用のサンプルであり、製品仕様や推奨値ではありません。
動作環境：Python 3.11以上、langgraph。
注意：本番環境で使用する前に、必ずテスト環境で動作確認してください。
import operator
from typing import Annotated, Literal
from typing_extensions import NotRequired, TypedDict
from langgraph.graph import END, START, StateGraph
class DebugState(TypedDict):
text: str
events: Annotated[list[str], operator.add]
normalized: NotRequired[str]
label: NotRequired[str]
output: NotRequired[str]
def normalize_input(state: DebugState) -> dict:
return {
"normalized": state["text"].strip().lower(),
"events": ["normalize_input"],
}
def classify_length(state: DebugState) -> dict:
label = "long" if len(state["normalized"]) >= 20 else "short"
return {"label": label, "events": [f"classify:{label}"]}
def route_by_label(
state: DebugState,
) -> Literal["short_reply", "long_reply"]:
return "long_reply" if state["label"] == "long" else "short_reply"
def short_reply(state: DebugState) -> dict:
return {"output": "短い入力として処理しました", "events": ["short_reply"]}
def long_reply(state: DebugState) -> dict:
return {"output": "長い入力として処理しました", "events": ["long_reply"]}
builder = StateGraph(DebugState)
builder.add_node("normalize_input", normalize_input)
builder.add_node("classify_length", classify_length)
builder.add_node("short_reply", short_reply)
builder.add_node("long_reply", long_reply)
builder.add_edge(START, "normalize_input")
builder.add_edge("normalize_input", "classify_length")
builder.add_conditional_edges("classify_length", route_by_label)
builder.add_edge("short_reply", END)
builder.add_edge("long_reply", END)
graph = builder.compile()ポイントはgraphという名前でcompiled graphを公開していることです。Studioはソースファイルを眺めて自動推測するのではなく、次に作るlanggraph.jsonの指定先から、この変数を読み込みます。また、ルーティング関数の戻り値をLiteralで限定しているため、画面には到達し得る2経路だけが描画されます。
langgraph.jsonを登録して開発サーバーを起動する
プロジェクト直下にlanggraph.jsonを置きます。graphsの左側はStudioに表示されるgraph ID、右側は「ファイルパス:変数名」です。dependenciesには公式CLIリファレンスで許可されているPythonパッケージ名を指定します。
{
"dependencies": ["langgraph"],
"graphs": {
"studio_debug": "./graph.py:graph"
},
"env": ".env"
}studio_debug
Studioで選ぶ名前
./graph.py
グラフ定義の場所
graphbuilder.compile()の結果
準備ができたら、仮想環境を有効にしたターミナルで開発サーバーを起動します。
注意：本番環境で使用する前に、必ずテスト環境で動作確認してください。
langgraph dev公式のローカルAgent Server手順では、既定のAPIは127.0.0.1のポート2024で起動し、Studio UIのリンクもターミナルに表示されます。ブラウザが自動で開かない場合は、そのリンクを開いてください。画面にstudio_debugが表示されれば、設定ファイルからcompiled graphまでの読み込みは成功です。
コードを書き換えると開発サーバーのhot reloadが反映します。依存関係やlanggraph.jsonを大きく変えた場合は、ターミナルのエラーを確認してから再読み込みしてください。
Graph modeでノードと実行経路を読む
StudioにはGraph modeとChat modeがあります。LangSmith Studioの機能概要によると、Graph modeは通過したノード、中間state、LangSmith連携まで見られる詳細画面です。Chat modeは会話テスト向けで、stateがMessagesStateを含むグラフに限られます。今回のDebugStateは独自stateなので、Graph modeを使います。
| モード | 主に見るもの | 今回の用途 |
|---|---|---|
| Graph mode | ノード、エッジ、入力、中間state、thread log | 可視化とデバッグに使用 |
| Chat mode | 会話メッセージとtool call | MessagesState系の確認に使用 |
Graph modeの左側にあるInputへ入力します。state schemaからフォームが自動生成されますが、構造をそのまま確認したいときはView Rawを選び、次の値を入れます。
{
"text": " LangGraph Studioを画面で確認したい ",
"events": []
}Submitを押すとrunが作成されます。threadを選択していない場合は新しいthreadも作成され、右側の履歴にノードの実行順が現れます。中央のグラフでは、normalize_inputからclassify_lengthへ進み、判定に応じてshort_replyまたはlong_replyへ移動した経路を追えます。
フォーム／View Raw
Submitと実行設定
ノードとエッジ
今回通った経路
runの履歴
各ノードのstate
stateをPrettyとJSONで比較する
可視化だけで原因が分からないときは、右側のthread logを開きます。公式のStudio操作ガイドでは、履歴の粒度をスライダーで調整し、turn、node、state keyを展開できると説明しています。まずは各ノードの出力を順に開き、どのkeyが初めて想定外になったかを探してください。
| 確認地点 | 増えるstate | 異常時に見る点 |
|---|---|---|
| 入力直後 | text、events |
入力schemaと型が合っているか |
normalize_input後 |
normalized |
空白除去や文字変換が想定どおりか |
classify_length後 |
label |
しきい値と分岐条件が合っているか |
| replyノード後 | output |
選ばれた経路と最終出力が一致するか |
Prettyはメッセージや入れ子の値を読みやすく確認するための表示です。JSONはkey名、配列、null、型の違いを正確に追うときに向きます。「画面では同じに見えるが、後段が反応しない」という場合はJSONへ切り替え、余分な階層や文字列化された数値がないか確認してください。
View stateとRe-run from hereを右側で選べます。出典：LangChain公式動画「LangSmith Studio v2」（2025年5月14日公開、2026年10月3日参照）- Input：
textと空のevents - normalize：
normalizedを追加 - classify：
labelを追加 - reply：
outputを追加
探す場所：期待値から初めて外れたノード
Interruptでノードの前後にブレークポイントを置く
Studioでいうブレークポイントは、Pythonの特定行で止める機能ではなく、グラフのノード境界でrunを一時停止する機能です。公式操作はInterruptを開き、対象ノードと「実行前」または「実行後」を選び、runを送信します。停止したらthread logでstateを確認し、Continueで続きを実行します。
- 画面の
Interruptをクリックする classify_lengthを選択する- 最初は実行前に停止する設定を選ぶ
- Inputを送信し、
normalizedがあることを確認する Continueを押し、判定後のlabelを確認する- 必要なら実行後に停止する設定へ切り替え、同じ入力で比較する
Continueが表示されています。出典：LangChain公式動画「LangSmith Studio v2」（2025年5月14日公開、2026年10月3日参照）| 停止位置 | 確認できること | 向いている不具合 |
|---|---|---|
| ノード実行前 | そのノードへ渡されるstate | 上流ノードの出力不足、入力schemaの崩れ |
| ノード実行後 | そのノードが返した更新後のstate | 判定、tool結果、state更新の誤り |
ここで止めても、関数内部の各行を順に進めるわけではありません。ノード内の例外箇所やローカル変数まで追う場合は、CLIの行デバッガ用オプションを使います。CLIリファレンスには--debug-portと--wait-for-clientが用意されています。次の5678は接続例のポート番号です。
注意：本番環境で使用する前に、必ずテスト環境で動作確認してください。
python -m pip install -U debugpy
langgraph dev --debug-port 5678 --wait-for-clientこの場合は、利用中のIDE側から同じポートへ接続します。StudioのInterruptはstateと経路を調べるため、IDEのブレークポイントはノード関数の内部処理を調べるため、と役割を分けると迷いません。
Re-runとForkで過去のcheckpointからやり直す
同じエラーを最初から何度も再現する必要はありません。thread historyの目的のノードでRe-run from hereを選ぶと、そのcheckpointから新しい分岐runを作れます。stateを書き換えて別の条件を試したい場合はEdit node stateを開き、値を変更してForkします。
LangGraphのtime travel公式ガイドによると、過去checkpointより前のノード結果は保存済みとして扱われ、checkpointより後のノードは再実行されます。再実行範囲にLLM呼び出しや外部APIがあれば再度呼ばれ、結果が変わる可能性があります。副作用のあるtoolを含むグラフでは、テスト環境やモックへ切り替えてから操作してください。外部APIを含む構成例は、既刊のAIエージェントでローカライゼーション自動化でも確認できます。
| 操作 | state編集 | 使う場面 | 元の履歴 |
|---|---|---|---|
Continue |
しない | Interruptの停止地点からそのまま進む | 同じthreadの停止checkpointから再開 |
Re-run from here |
しない | コードやassistant設定を変えて再実行する | 残したまま新しい分岐を作る |
Edit node state＋Fork |
する | 入力や中間結果を仮に修正して後段を試す | 残したまま新しい分岐を作る |
- 経路とノード境界を見たい →
Interrupt＋Continue - 同じcheckpointから再試行したい →
Re-run from here - 中間stateを変えて後段を試したい →
Edit node state＋Fork - 関数内部の行やローカル変数を見たい →
--debug-port＋IDEデバッガ
接続・表示トラブルを症状から切り分ける
Studioが開かないときは、ブラウザ画面だけを更新するより、Agent Server、設定ファイル、ブラウザ接続の順に切り分ける方が早く原因へ到達します。
| 症状 | 最初に確認する場所 | 対処 |
|---|---|---|
| graphが一覧に出ない | langgraph.jsonのgraphs |
graph ID、ファイルパス、変数名を./graph.py:graphの形で照合する |
| ImportErrorで起動しない | 仮想環境とdependencies |
対象環境でimportできるかを確認し、パッケージ名を設定へ追加する |
| ポート2024を使えない | ターミナルのbindエラー | langgraph dev --port 2025のように空きポートを明示する |
| Safariでlocalhostへ接続できない | ブラウザのローカル接続制限 | langgraph dev --tunnelを実行し、StudioのConnect to a local serverでtunnel URLをallowed originsへ追加する |
| 入力フォームが扱いにくい | state schemaとInput表示 | View Rawへ切り替え、JSONでkeyと型を確認する |
| コード変更が反映されない | 開発サーバーのログ | 構文・importエラーを直し、hot reload完了後にrunを再送する |
Safari向けにはlanggraph dev --tunnelを実行し、StudioのConnect to a local serverを開いて、表示されたtunnel URLをallowed originsへ追加してから接続します。--tunnelは外部から到達可能なURLを作る操作です。機密データを入力せず、利用後は開発サーバーを停止してください。ポート変更時はStudioの接続先baseUrlも同じポートへ合わせます。
失敗しやすい4パターンと直し方
旧デスクトップアプリの手順から始める
❌ 2024年の画面を見て、macOSアプリとDockerの導入から始める。
⭕ 現行の公式ドキュメントを開き、langgraph-cli[inmem]とブラウザ版Studioを使う。
なぜ重要か：現在のローカル開発経路はlanggraph devです。古い環境構築に時間を使うと、UI名や接続方法の違いで切り分けが難しくなります。
graph IDとPython変数名を同じものだと思う
❌ studio_debugというPython変数が存在する前提で設定する。
⭕ 左側のstudio_debugは画面上のID、右側の./graph.py:graphは実際のファイルと変数、と分けて確認する。
なぜ重要か：Studioが読み込む対象はコロンの後ろに書いたcompiled graphです。IDの名前が正しくても、参照先が違えば一覧には出ません。
実行後の値を見たいのにbeforeで止める
❌ classify_lengthの実行前で停止し、labelがないことを不具合と判断する。
⭕ 入力stateを見るならbefore、ノードが返した更新を見るならafterを選ぶ。
なぜ重要か：ブレークポイントの位置によって、まだ存在しないstate keyがあります。比較したい値が「ノードへ入る値」か「ノードから出る値」かを先に決めてください。
stateを直すために元の履歴を上書きしようとする
❌ 過去runの値を直接置換し、元の失敗状態を消そうとする。
⭕ Edit node stateからForkし、失敗runと修正版runを並べて比較する。
なぜ重要か：Forkは過去checkpointから新しい分岐を作るため、元の履歴を残したまま仮説を検証できます。デバッグでは「直った結果」だけでなく「どこから違ったか」が重要です。
よくある質問
LangGraph StudioとLangSmith Studioは同じものですか？
同じStudioを指しています。2026年10月3日時点の製品ページ名はLangSmith Studioですが、CLIの出力や一部の公式ページにはLangGraph Studioという表記も残っています。機能と操作を確認するときは、現行のLangSmith Studio公式ページを参照してください。
LangGraph Studioは無料ですか？
公式ドキュメントはローカル開発向けStudioを無料の可視化インターフェースとして案内し、LangSmithアカウントも無料で作成できるとしています。ただし、グラフから外部のLLMや検索APIを呼ぶ場合、その提供元の利用料は別です。今回の最小例は外部APIを呼びません。
Dockerなしで使えますか？
はい。langgraph devはDocker不要の軽量開発サーバーです。Dockerを使うlanggraph upとは用途が異なるため、画面デバッグを始める段階ではdevを選んでください。
WindowsやLinuxでも使えますか？
ローカルCLIとWeb版Studioを使う方式は、旧macOSデスクトップ版の制約を解消する経路として公式に公開されました。OSごとに仮想環境の有効化コマンドは異なりますが、langgraph.jsonとStudioの操作は共通です。
Graph modeとChat modeはどう使い分けますか？
ノード、エッジ、中間state、threadを詳しく追うならGraph modeです。Chat modeは会話全体を素早く試す画面で、MessagesStateを含むグラフが対象です。独自stateをデバッグするこの記事の例ではGraph modeを使います。
PrettyとJSONはどちらを見るべきですか？
まずPrettyで全体を読み、型や入れ子、null、配列要素まで正確に調べる場面でJSONへ切り替えてください。表示上は似ていても、文字列と数値、単一オブジェクトと配列の違いはJSONの方が見つけやすくなります。
Interruptのbeforeとafterは何が違いますか？
beforeは対象ノードへ入る直前、afterは対象ノードがstate更新を返した直後に停止します。上流から渡された値を調べるならbefore、対象ノードの処理結果を調べるならafterです。
ForkとRe-run from hereは何が違いますか？
Re-run from hereはstateを編集せず、選んだcheckpointから再実行します。ForkはEdit node stateで値を変更し、その変更を起点に別の実行経路を作ります。どちらも元の履歴を残して比較できます。
ブレークポイントでPythonの1行ずつを追えますか？
StudioのInterruptはノード境界で停止する機能です。関数内部を1行ずつ追う場合はlanggraph dev --debug-port PORT --wait-for-clientを使い、IDEのデバッガを接続してください。
コードを変えるたびにサーバー再起動が必要ですか？
通常のソース変更はhot reloadの対象です。反映されない場合は、まずターミナルに構文エラーやimportエラーが出ていないか確認してください。依存関係や設定ファイルを変更したときは、サーバーが正常に再読み込みできたことを確認してからrunを送り直します。
LangGraphのワークフロー設計から学ぶには何を読めばよいですか？
Studioは設計済みのグラフを観察する道具です。分岐、ループ、並列化、オーケストレータ・ワーカーなど、グラフ自体の組み方はAIエージェントのワークフロー設計パターン5選で整理しています。
運営元 Uravation よりAIエージェントを構想から本番運用まで進める順番と、体制・KPIの決め方をまとめた資料を無料で公開しています。 AIエージェント導入ロードマップを受け取る（無料）
参考・出典
- LangSmith Studio — LangChain公式。ローカルセットアップ、Python要件、APIキー、hot reload、tracing設定を確認（参照日: 2026年10月3日）
- LangSmith Studio overview — LangChain公式。Graph mode、Chat mode、time travelなどの機能を確認（参照日: 2026年10月3日）
- How to use Studio — LangChain公式。Input、Interrupt、Continue、Pretty／JSON、Fork、Re-runの画面操作を確認（参照日: 2026年10月3日）
- LangGraph CLI — LangChain公式。
dev、Python 3.11以上、既定ポート、--debug-port、--tunnelを確認（参照日: 2026年10月3日） - Run a local server — LangChain公式。Agent ServerとStudioの接続先を確認（参照日: 2026年10月3日）
- Use time-travel — LangChain公式。checkpointからのReplayとForkの挙動を確認（参照日: 2026年10月3日）
- LangSmith Studio v2: The Ultimate Agent Development Environment — LangChain公式動画。Graph mode、thread log、Interrupt、Continue、state編集、Forkの実画面を確認。2025年5月14日公開（参照日: 2026年10月3日）
- LangGraph Studio: The first agent IDE — LangChain公式ブログ、2024年8月1日公開（参照日: 2026年10月3日）
- Agent Protocol: Interoperability for LLM agents — LangChain公式ブログ、2024年11月19日公開（参照日: 2026年10月3日）
結論
LangGraph Studioを2026年10月3日時点で使うなら、製品ページ名がLangSmith Studioとなっているブラウザ版を開き、langgraph devで動かしたローカルAgent Serverへ接続します。最初に見る順番は、中央のグラフで経路、右のthread logでstate、Interruptでノードの前後です。
原因を切り分けたら、同じcheckpointで試すときはRe-run from here、中間stateを変えるときはEdit node stateとForkを選びます。関数内部まで追う必要があるときだけIDEデバッガへ進むと、画面デバッグと行デバッグの役割が混ざりません。
この記事を読んで導入イメージが固まってきた方へ
UravationではAIエージェント導入の研修・コンサルを行っています。
この記事はAIgent Lab編集部がお届けしました。
