CrewAI + Gemini + Traceloop + OTEL + Instana を使ったAI Agentの可観測性検証ガイド

## はじめに

この記事では、Google Gemini を使って日本語の書籍を自動生成するワークフローを、**CrewAI**というAI Agentフレームワークをベースに構築し、**Traceloop + OpenTelemetry (OTEL)** を通じて **Instana** に統合して可観測性を実現する方法を紹介します。

* ✅ LLMで生成ワークフローを構築
* ✅ OTELトレースで実行内容を可視化
* ✅ Instanaでエンタープライズ向けに監視

📂 GitHubリポジトリ:
👉 [https://github.com/GSSJacky/write\_a\_book\_with\_flows\_otel](https://github.com/GSSJacky/write_a_book_with_flows_otel)

---

## ✅ 利用技術とバージョン情報

| ツール / ライブラリ            | 用途                  | バージョン   |
| ---------------------- | ------------------- | ------- |
| Python                 | 実行環境                | 3.11.12 |
| CrewAI                 | LLM Agentフレームワーク    | 0.121.1 |
| crewai\[tools]         | toolセット付きCrewAI     | 0.114.0 |
| traceloop-sdk          | OpenTelemetryトレース送信 | 0.40.7  |
| langchain-google-genai | Gemini LLM SDK      | 2.1.5   |
| litellm                | provider統合          | 1.68.0  |

---

## 🧰 CrewAIとは？

CrewAI は、**複数のLLMエージェントを連携させて協調的にタスクを実行**するフレームワークです。

### 🚶‍♂️ 最小例

```python
from crewai import Agent, Task, Crew

agent = Agent(name="Writer", llm=OpenAI(...))
task = Task(description="Write a blog post about LLMs.", agent=agent)
crew = Crew(agents=[agent], tasks=[task])

crew.kickoff(inputs={"topic": "LLMs"})
```

CrewAIの特徴：

* 🔄 フロー型の処理構築
* 🧠 役割分担された複数エージェント
* 📜 YAML構成対応
* 📡 Traceloopでのトレース送信対応

📖 公式ドキュメント: [https://docs.crewai.io](https://docs.crewai.io)


## 🛠️ セットアップ手順

### 1. リポジトリのクローン

```bash
git clone https://github.com/GSSJacky/write_a_book_with_flows_otel.git
cd write_a_book_with_flows_otel
```


### 2. 仮想環境をセットアップ

```bash
python3.11 -m venv venv3.11
source venv3.11/bin/activate
```


### 3. 依存パッケージのインストール

```bash
pip install crewai
crewai install
```


### 4. `.env` の設定

```dotenv
#Optional
#SERPER_API_KEY="XXXXXX"
GEMINI_API_KEY="xxx_your_gemini_api_key_xxx"
PYTHONPATH=src
CREWAI_DISABLE_TELEMETRY=true

### Instana Agent OTLP Port (default: 4318)
TRACELOOP_BASE_URL=http://localhost:4318
TRACELOOP_HEADERS=x-instana-key=xxx_your_instana_agent_key_xxx
OTEL_EXPORTER_OTLP_INSECURE=false
```


## 🔧 Gemini LLMの初期化（main.py）

以下のコードで `gemini_llm` を初期化します。

```python
from crewai import LLM
import os

gemini_llm = None
try:
    gemini_api_key = os.getenv("GEMINI_API_KEY")
    if not gemini_api_key:
        raise ValueError("GEMINI_API_KEY not found in environment variables. Please set it in your .env file.")

    gemini_llm = LLM(
        model="gemini/gemini-2.0-flash",
        api_key=gemini_api_key,
        temperature=0.75,
        provider="google"
    )

    print("Gemini LLM Initialized Successfully.")
except Exception as e:
    print(f"Error initializing Gemini LLM: {e}")
    print("Please ensure your GEMINI_API_KEY is set correctly in .env and you have 'pip install langchain-google-genai'.")
    exit()
```

---

### **Instana エージェントのインストール**
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` が表示されれば成功！**


## 🚀 crewAI Book Agentを開始

```bash
crewai flow kickoff
```

📘 結果は `./output/book.md` に保存されます。
内容は日本語の章構成＋本文が含まれます。
例：
本のテーマ：[The Current State of AI in 2025](https://github.com/GSSJacky/write_a_book_with_flows_otel/blob/main/output/book.md)

---

## 🛰️ Traceloop + Instana の可視化連携

### Traceloop 初期化（main.py）

```python
from traceloop.sdk import Traceloop

Traceloop.init(
    app_name="crewai_writebook_with_flows",
    disable_batch=True
)
```

* app\_nameがInstana上のサービス名になります
* `TRACELOOP_HEADERS` に Instana Agent Key を指定することでデータ連携

---

## 🖥️ Instanaで可視化される内容
1. **Instana UI にログイン**
2. **「アプリケーション」 > 「サービス」 > `crewai_writebook_with_flows` を選択**
3. **「呼び出しの分析」でトレースの詳細を確認**
図１
![Screenshot 2025-06-02 at 22.06.52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/70cb7256-4b1f-4c47-8ba0-6e9e17ddeac1.png)

図２
![Screenshot 2025-06-02 at 22.07.36.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/86dcb51d-3ee3-4750-bfa1-f5998639ef95.png)

図３
![Screenshot 2025-06-02 at 22.08.29.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/a831af7f-2039-4481-8edc-6bf677d885fc.png)

![Screenshot 2025-06-02 at 22.08.57.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3629252/0dc98b5e-0b31-46ba-9fa7-7dc5c48ac4de.png)


---

## 🔍 関連資料

* 📘 [CrewAI公式](https://docs.crewai.io)
* 📘 [Instana公式 - CrewAI連携](https://www.ibm.com/docs/en/instana-observability/current?topic=frameworks-crewai)
* 📘 [Medium記事: Watsonx × CrewAI × Instana](https://gyliu513.medium.com/instana-observability-for-watsonx-ai-and-crewai-integration-5c0aa1020d5f)
* 📘 [このプロジェクトのGitHub](https://github.com/GSSJacky/write_a_book_with_flows_otel)