2025年6月にGoogleから公開されたgemini-fullstack-langgraph-quickstartを題材に、LangGraph × Traceloop SDK を導入し、Instana UI でAI Agentのトレースを可視化する構成を検証してみました。
本記事ではLangGraphの基本、実装例、Instanaでの可視化内容まで含め、再現手順を詳しく紹介します。
🧠 LangGraphとは？＋簡単な使い方
LangGraphはLangChainベースのエージェントフローを「状態遷移グラフ（Stateful Graph）」として構築できるライブラリです。
LangGraphでは以下のようなノードを定義し、複数の思考プロセス（例：検索→内省→回答生成）をフロー化することができます。
🧪 簡単な実装例
以下はユーザーの質問に対して、Google Search→ Reflection→ Answerの流れを行うLangGraph定義例です：
from langgraph.graph import StateGraph
from my_nodes import generate_query, web_research, reflection, finalize_answer
graph = StateGraph()
graph.add_node("generate_query", generate_query)
graph.add_node("web_research", web_research)
graph.add_node("reflection", reflection)
graph.add_node("finalize_answer", finalize_answer)
graph.set_entry_point("generate_query")
graph.set_finish_point("finalize_answer")
graph.add_edge("generate_query", "web_research")
graph.add_edge("web_research", "reflection")
graph.add_edge("reflection", "finalize_answer")
runnable = graph.compile()
LangGraph Studio（http://127.0.0.1:2024/）で可視化すると以下のように表示されます：
🖼️ フロービジュアル（例）：
- generate_query → web_research → reflection → finalize_answer
⚙️ 今回検証に使うGemini-fullstack-langgraph-quickstart構成と使用OSS
- Frontend: React + Vite
- Backend: FastAPI + LangGraph + Gemini API
- Observability: Traceloop SDK + OTLP + Instana Agent
- 可視化: Instana UI によるトレース
参考リポジトリ：https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart
使用パッケージ：
langgraph>=0.2.6
langchain>=0.3.19
langchain-google-genai
fastapi
google-genai
traceloop-sdk
🛠️ セットアップ＆起動手順（抜粋）
- Git clone & venv作成:
git clone https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart.git
cd gemini-fullstack-langgraph-quickstart
python3.11 -m venv venv3.11
source venv3.11/bin/activate
2.1 gemini-fullstack-langgraph-quickstartフォルダの直下に.env ファイルを作成する。関連APIキー、Instana Agentキーを設定する
GEMINI_API_KEY=xxx
LANGSMITH_API_KEY=xxx
TRACELOOP_BASE_URL=http://localhost:4318
TRACELOOP_HEADERS=x-instana-key=xxxxx
OTEL_EXPORTER_OTLP_INSECURE=false
2.2 pyproject.tomlにdependenciesのところでtraceloop-sdkを追加する
dependencies = [
"langgraph>=0.2.6",
"langchain>=0.3.19",
"langchain-google-genai",
"python-dotenv>=1.0.1",
"langgraph-sdk>=0.1.57",
"langgraph-cli",
"langgraph-api",
"fastapi",
"google-genai",
"traceloop-sdk>=0.40.7,<0.41.0",
]
2.3. Traceloop SDK 初期化（backend/src/agent/graph.py）及び@Taskの計装
from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import task
Traceloop.init(app_name="gemini_fullstack_langgraph_service", disable_batch=True)
# Nodes
@task(name="tk_generate_query")
def generate_query(state: OverallState, config: RunnableConfig) -> QueryGenerationState:
.....
@task(name="tk_continue_to_web_research")
def continue_to_web_research(state: QueryGenerationState):
.....
@task(name="tk_web_research")
def web_research(state: WebSearchState, config: RunnableConfig) -> OverallState:
.....
@task(name="tk_reflection")
def reflection(state: OverallState, config: RunnableConfig) -> ReflectionState:
.....
@task(name="tk_evaluate_research")
def evaluate_research(
state: ReflectionState,
config: RunnableConfig,
) -> OverallState:
.....
@task(name="tk_finalize_answer")
def finalize_answer(state: OverallState, config: RunnableConfig):
.....
3.パッケージインストール
Backend
cd gemini-fullstack-langgraph-quickstart/backend
pip install .
Frontend
cd gemini-fullstack-langgraph-quickstart/frontend
npm install
4.Instanaドキュメントに沿ってInstana Agentインストールいただければと思います。
Instana の OpenTelemetry 設定
configuration.yaml に以下を追加：
com.instana.plugin.opentelemetry:
enabled: true
エージェントを再起動：
sudo systemctl restart instana-agent.service
netstat -ano | grep 4318
✅ 0.0.0.0:4318 が表示されれば成功！
5.Gemini-fullstack-langgraph-quickstart起動
cd gemini-fullstack-langgraph-quickstart
make dev
Langsmith及びFrontend UIでの確認
1.make devを実行した後で自動的にLangGraph Studio画面を開きます:
https://smith.langchain.com/studio/thread?baseUrl=http%3A%2F%2F127.0.0.1%3A2024&mode=graph
2.次にhttp://localhost:5173/app/URLを入力し、Frontendを開いて、適当にPrompt入力し、Searchボタンを押します。
実行結果：Instana UIでの可視化
🖥️ Instanaで可視化される内容
- Instana UI にログイン
- 「アプリケーション」 > 「サービス」 >
gemini_fullstack_langgraph_serviceを選択 -
「呼び出しの分析」でトレースの詳細を確認
図１
図２
図３
まとめ
LangGraph × Traceloop × Instanaの連携により、AIエージェントの実行フローを「リアルタイムでトレース & 可視化」できます。とくにLangGraphのような分岐・ステート型AIシステムでは、トレースベースの監視が非常に有効です。
Reference Links
- CrewAI + Gemini + Traceloop + OTEL + Instana を使ったAI Agentの可観測性検証ガイド:https://qiita.com/jackyxu/items/adb29dda1ca8226146d1
- LangGraph公式: https://github.com/langchain-ai/langgraph
- Traceloop OSS: https://traceloop.dev
- Instana langgraph monitoring Docs: https://www.ibm.com/docs/en/instana-observability/current?topic=frameworks-langgraph