Instana × Traceloop で LangGraph + Gemini OSS Agent を可視化してみた

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定義例です：

```python
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/）で可視化すると以下のように表示されます：](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](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart)

使用パッケージ：

```toml
langgraph>=0.2.6
langchain>=0.3.19
langchain-google-genai
fastapi
google-genai
traceloop-sdk
```


## 🛠️ セットアップ＆起動手順（抜粋）

1. Git clone & venv作成:

```bash
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キーを設定する

```env
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を追加する

```env
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の計装

```python
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
```bash
cd gemini-fullstack-langgraph-quickstart/backend
pip install .
```

Frontend
```bash
cd gemini-fullstack-langgraph-quickstart/frontend
npm install
```
----
4.Instanaドキュメントに沿ってInstana Agentインストールいただければと思います。

**Instana の OpenTelemetry 設定**
`configuration.yaml` に以下を追加：
```yaml
com.instana.plugin.opentelemetry:
  enabled: true
```
エージェントを再起動：
```bash
sudo systemctl restart instana-agent.service
netstat -ano | grep 4318
```
✅ **`0.0.0.0:4318` が表示されれば成功！**

----

5.**Gemini-fullstack-langgraph-quickstart起動**

```bash
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](https://smith.langchain.com/studio/thread?baseUrl=http%3A%2F%2F127.0.0.1%3A2024&mode=graph)
![Screenshot 2025-06-05 at 15.07.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/797d8673-ff57-412e-9921-73dbad6d84fc.png)


**2.次に[http://localhost:5173/app/](http://localhost:5173/app/)URLを入力し、Frontendを開いて、適当にPrompt入力し、Searchボタンを押します。**

![Screenshot 2025-06-05 at 15.12.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/263b7cd9-ca69-4d00-a98b-b099bf8521e1.png)
![Screenshot 2025-06-05 at 15.13.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/c702868b-d3ae-4427-b1d4-6a16798c761f.png)

---

##  実行結果：Instana UIでの可視化
## 🖥️ Instanaで可視化される内容
1. **Instana UI にログイン**
2. **「アプリケーション」 > 「サービス」 > `gemini_fullstack_langgraph_service` を選択**
3. **「呼び出しの分析」でトレースの詳細を確認**
図１
![Screenshot 2025-06-05 at 16.42.48.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/fc464995-7c93-4698-b2b4-982a86459989.png)

図２
![Screenshot 2025-06-05 at 16.43.29.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/dabba952-93e5-466b-ad3f-b90c8d43c058.png)

図３
![Screenshot 2025-06-05 at 16.43.51.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/52b90fb3-f5f4-4ba0-9f79-f1d9541a04f6.png)
![Screenshot 2025-06-05 at 18.12.41.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/e520fb22-b957-4d2e-a22f-e9cd89711e9f.png)


---

##  まとめ

LangGraph × Traceloop × Instanaの連携により、AIエージェントの実行フローを「リアルタイムでトレース & 可視化」できます。とくにLangGraphのような分岐・ステート型AIシステムでは、トレースベースの監視が非常に有効です。


## Reference Links

* CrewAI + Gemini + Traceloop + OTEL + Instana を使ったAI Agentの可観測性検証ガイド:[https://qiita.com/jackyxu/items/adb29dda1ca8226146d1](https://qiita.com/jackyxu/items/adb29dda1ca8226146d1)
* LangGraph公式: [https://github.com/langchain-ai/langgraph](https://github.com/langchain-ai/langgraph)
* Traceloop OSS: [https://traceloop.dev](https://traceloop.dev)
* Instana langgraph monitoring Docs: [https://www.ibm.com/docs/en/instana-observability/current?topic=frameworks-langgraph](https://www.ibm.com/docs/en/instana-observability/current?topic=frameworks-langgraph)