🐷

LangGraphエージェントにPLD(Phase Loop Dynamics)を組み込んで挙動を観測する｜JSONLログ付き実装例

に公開
AI
Observability
LangChain
LLM
LangGraph
tech

👋 はじめに

LangGraphでマルチターンLLMエージェントを動かしていると、次のような現象に遭遇することがあります：

  • エラーは出ていないのに動作が崩れる
  • ツール呼び出しが無限に続く
  • 指示を忘れて意図しない挙動を始める
  • 一度改善しても次のターンで再発する

例外やリトライでは検出できない、**「ランタイムの挙動のズレ（drift）」**が原因です。

この記事では、こうした挙動を観測可能（observable）にするための試みとして、
PLD (Phase Loop Dynamics) を LangGraph に Observer Mode で組み込む方法を紹介します。

※ PLDはまだ実験段階の概念・実装です。

🎯 この記事の目的

  • LangGraphエージェントへのPLD統合方法
  • コードベースの最小実例
  • 実行ログ（JSONL）による振る舞い観測

PLDは制御ロジックを変更しません。
**「ただ横から見て、イベントを記録するだけ」**です。

📁 対象ディレクトリ構成

今回扱う例はリポジトリ内の:

examples/langgraph_assistants/
├── README.md
├── run.py
├── graph.py
├── agent_node.py
├── config.yaml
└── pld_runtime_integration.py

⚙️ 実行方法

export OPENAI_API_KEY="sk-..."  # 必須
python examples/langgraph_assistants/run.py

実行すると：

  • 最終状態（state）
  • PLDログ (JSONL)

が出力されます。

🔧 実装ポイント

① run.py：PLD初期化とLangGraph実行

from examples.langgraph_assistants.pld_runtime_integration import (
    init_pld_observer,
    emit_session_closed,
    emit_tool_error
)

cfg = load_config()
init_pld_observer(jsonl_path=jsonl_path, validation_mode=pld_mode)

app = build_graph(model=model)

state = {...}

try:
    state = app.invoke(state)
except Exception as exc:
    emit_tool_error(state, reason=str(exc))
  • init_pld_observer() が観測開始ポイント
  • LangGraph呼び出し自体を変更していません

② pld_runtime_integration.py：Observer Modeの実装

公開API:

関数 意味
init_pld_observer() 初期化（ロガー/バリデーション）
emit_continue_event() 正常ターン
emit_tool_error() 実行異常
emit_session_closed() 会話終了

内部では RuntimeSignalBridge がLangGraphのstateをPLDイベント形式へ変換します。

③ JSONLログ例

実行後、次のようなログが蓄積されます👇

{
  "event_type": "continue",
  "turn": 2,
  "session_id": "demo-session-1",
  "phase": "continue",
  "timestamp": "2025-11-28T09:42:12.381Z"
}

これにより、以下の分析が可能になります：

  • drift発生タイミング
  • 自動復帰の頻度
  • 失敗モードのクラスタリング

👍 この例が役立つケース

  • 長期対話のエージェントを運用している
  • 「動くけど安定しない」挙動が多い
  • 監視・検証・再現性を担保したい
  • エージェントのObservabilityレイヤーを探している

特に：

「ログは成功なのに動作が壊れる」

という状況に強いです。

🚧 現状のステータス

項目 状態
Observer mode ✔ Stable
Automatic recovery 🚧 Experimental
Failover routing 🚧 Under design
OpenTelemetry export 🧪 プランニング中

PLDはまだワーキングドラフト段階です。
実装や指摘、失敗例フィードバック歓迎です。

📎 リンク

💬 おわりに

LangGraphエージェントの挙動を「観察可能にする」取り組みとして、PLDはまだ始まったばかりの概念ですが、実運用では既に価値が見え始めています。

もしこの記事が役立った場合、ぜひ：

  • fork
  • issue報告
  • ログ例共有
  • 実験成果の連携

お待ちしています 🙌

Discussion