開発者ガイド - LlamaIndex と CData Connect AI で AI エージェントを構築

LlamaIndex の ReAct エージェントフレームワークと CData Connect AI を組み合わせて、データへの会話型アクセスを実現するインテリジェントなデータエージェントを構築します。 このガイドでは、LlamaIndex の強力なエージェント機能と 350 以上のデータソースからのライブデータを組み合わせた Python アプリケーションの作成方法を説明します。

注意: このガイドでは Google スプレッドシートをデータソースとして使用していますが、CData Connect AI がサポートする 350 以上のデータソースのいずれにも同じ原則が適用されます。

このガイドを完了すると、以下の機能を持つ Python アプリケーションが完成します：

  • CData Connect AI を通じて 350 以上のデータソースに接続
  • LlamaIndex の ReAct エージェントによるインテリジェントなツールオーケストレーション
  • 自然言語を使用した SQL クエリの実行
  • コンテキストを持つマルチターン会話の維持
  • OpenAI と Anthropic の両方の LLM プロバイダーをサポート
  • リアルタイムでのレスポンスストリーミング

LlamaIndex を選ぶ理由

LlamaIndex は、AI エージェント構築においていくつかの重要なメリットを提供します：

  • ReAct エージェントフレームワーク: 複雑なマルチステップタスクに対応するインテリジェントな推論・実行ループ
  • 複数 LLM のサポート: OpenAI（GPT-4）と Anthropic（Claude）にすぐに対応
  • ストリーミングサポート: インタラクティブなアプリケーション向けのリアルタイムトークンストリーミング
  • コンテキスト管理: マルチターンのやりとりに対応する組み込みの会話コンテキスト
  • 拡張可能なツール: 外部ツールやデータソースとの容易な連携
  • 本番環境対応: 本番アプリケーションで実績のあるフレームワーク

アーキテクチャの概要

このアプリケーションは、Model Context Protocol（MCP）を使用して LlamaIndex エージェントとデータソースを橋渡しします：

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                 │     │                  │     │                 │
│  Your Python    │---->│  CData Connect   │---->│  Data Sources   │
│  Application    │     │  AI MCP Server   │     │  (350+ types)   │
│                 │<----│                  │<----│                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        |                        |
        |    Tool Discovery      |
        |    & Execution         |
        v                        |
┌─────────────────┐              |
│                 │              |
│  LlamaIndex     │--------------┘
│  ReAct Agent    │   Natural Language
│  (OpenAI/Claude)│   to SQL Translation
└─────────────────┘

仕組み：

  1. Python アプリケーションが MCP ツールを使用して LlamaIndex エージェントを初期化
  2. エージェントが HTTP 経由で CData Connect AI の MCP サーバーに接続
  3. MCP ツールが ReAct エージェント用の LlamaIndex 関数としてラップされる
  4. ReAct エージェントがどのツールを使うべきかを推論し、実行
  5. 結果が返され、LLM によって解釈されます

前提条件

このガイドには以下が必要です：


はじめに

概要

手順の概要は以下のとおりです：

  1. Google スプレッドシートでサンプルデータをセットアップ
  2. CData Connect AI を設定し、パーソナルアクセストークンを作成
  3. Python プロジェクトをセットアップし、依存関係をインストール
  4. エージェントチャットボットを構築して実行

ステップ 1: Google スプレッドシートでサンプルデータをセットアップ

機能をデモンストレーションするために、顧客データを含むサンプル Google スプレッドシートを使用します。 このデータセットには、アカウント、販売機会、サポートチケット、使用状況メトリクスが含まれています。

  1. サンプル顧客ヘルススプレッドシートに移動します
  2. ファイル > コピーを作成をクリックして、Google ドライブに保存します
  3. わかりやすい名前を付けます（例：「demo_organization」）- これは後で必要になります

スプレッドシートには 4 つのシートが含まれています：

  • account: 会社情報（名前、業界、収益、従業員数）
  • opportunity: 販売パイプラインデータ（ステージ、金額、確率）
  • tickets: サポートチケット（優先度、ステータス、説明）
  • usage: 製品使用状況メトリクス（ジョブ実行回数、処理レコード数）

ステップ 2: CData Connect AI の設定

2.1 サインアップまたはログイン

  1. https://jp.cdata.com/ai/signup/ で新規アカウントを作成するか、 https://cloud.cdata.com/ でログインします
  2. 新規アカウントを作成する場合は、登録プロセスを完了します

2.2 Google スプレッドシート接続を追加

  1. ログイン後、左側のナビゲーションメニューでSourcesをクリックし、Add Connectionをクリックします
  2. Add Connection パネルからGoogle Sheetsを選択します
  3. 接続を設定します：
    • Spreadsheetプロパティに、コピーしたシートの名前を設定します（例：「demo_organization」）
    • Sign inをクリックして Google OAuth で認証します
  4. 認証後、Permissionsタブに移動し、ユーザーがアクセス権を持っていることを確認します

2.3 パーソナルアクセストークンの作成

Python アプリケーションは、パーソナルアクセストークン（PAT）を使用して Connect AI と認証します。

  1. 右上の歯車アイコンをクリックして設定を開きます
  2. Access Tokensセクションに移動します
  3. Create PATをクリックします
  4. トークンに名前を付け（例：「LlamaIndex Agent」）、Createをクリックします
  5. 重要: トークンはすぐにコピーしてください - 一度しか表示されません！

ステップ 3: Python プロジェクトのセットアップ

3.1 pip でインストール（推奨）

PyPI からパッケージを直接インストールします：

pip install connectai-llamaindex-agent

3.2 代替方法: GitHub からクローン

すべてのサンプルを含む完全なプロジェクトをクローンします：

git clone https://github.com/CDataSoftware/connectai-llamaindex-agent.git cd connectai-llamaindex-agent pip install -e .

3.3 代替方法: ゼロから作成

新しいプロジェクトディレクトリを作成し、依存関係をインストールします：

mkdir connectai-llamaindex-app cd connectai-llamaindex-app pip install connectai-llamaindex-agent python-dotenv

3.4 環境変数の設定

プロジェクトルートに .env ファイルを作成します：

# CData Connect AI 設定（必須） [email protected] CDATA_PAT=your-personal-access-token-here # OpenAI 設定（デフォルト） OPENAI_API_KEY=sk-your-openai-api-key-here # または Anthropic を使用する場合 # LLM_PROVIDER=anthropic # ANTHROPIC_API_KEY=your-anthropic-api-key-here

プレースホルダーの値を実際の認証情報に置き換えてください。


ステップ 4: コードアーキテクチャの理解

パッケージは 3 つの主要コンポーネントで構成されています：

4.1 Config クラス

複数の LLM プロバイダーに対応した設定と認証情報の管理を処理します：

from dataclasses import dataclass import os import base64 from typing import Optional @dataclass class Config: """Configuration for the Connect AI LlamaIndex Agent.""" cdata_email: str cdata_pat: str mcp_server_url: str = "https://mcp.cloud.cdata.com/mcp" llm_provider: str = "openai" openai_api_key: Optional[str] = None openai_model: str = "gpt-4o" anthropic_api_key: Optional[str] = None anthropic_model: str = "claude-sonnet-4-20250514" @classmethod def from_env(cls) -> "Config": """Create configuration from environment variables.""" return cls( cdata_email=os.getenv("CDATA_EMAIL"), cdata_pat=os.getenv("CDATA_PAT"), llm_provider=os.getenv("LLM_PROVIDER", "openai").lower(), openai_api_key=os.getenv("OPENAI_API_KEY"), openai_model=os.getenv("OPENAI_MODEL", "gpt-4o"), anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"), anthropic_model=os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-20250514"), ) def get_auth_header(self) -> str: """Generate Base64 authentication header.""" credentials = f"{self.cdata_email}:{self.cdata_pat}" return base64.b64encode(credentials.encode()).decode()

4.2 MCPClient クラス

CData Connect AI MCP サーバーとの低レベル HTTP 通信を処理するクライアントです：

import json import httpx class MCPClient: """HTTP client for CData Connect AI MCP server.""" def __init__(self, config: Config): self.config = config self._client = httpx.Client( headers={ "Authorization": f"Basic {config.get_auth_header()}", "Content-Type": "application/json", "Accept": "application/json, text/event-stream", "User-Agent": "connectai-llamaindex-agent/1.0.0", }, timeout=60.0, ) def _parse_sse_response(self, response: httpx.Response) -> dict: """Parse Server-Sent Events response.""" for line in response.text.split(" "): if line.startswith("data: "): return json.loads(line[6:]) return {} def list_tools(self) -> list: """Discover available tools from the MCP server.""" response = self._client.post( self.config.mcp_server_url, json={"jsonrpc": "2.0", "method": "tools/list", "id": 1}, ) result = self._parse_sse_response(response) return result.get("result", {}).get("tools", []) def call_tool(self, name: str, arguments: dict = None) -> str: """Execute a tool on the MCP server.""" response = self._client.post( self.config.mcp_server_url, json={ "jsonrpc": "2.0", "method": "tools/call", "params": {"name": name, "arguments": arguments or {}}, "id": 1, }, ) result = self._parse_sse_response(response) content = result.get("result", {}).get("content", []) if content: texts = [item.get("text", "") for item in content if item.get("type") == "text"] return " ".join(texts) return json.dumps(result)

4.3 MCPAgent クラス

LLM の推論と MCP ツールを組み合わせた LlamaIndex ReAct エージェントです：

from llama_index.core.agent.workflow import ReActAgent from llama_index.core.workflow import Context class MCPAgent: """LlamaIndex-based agent for conversational data access.""" def __init__(self, config: Config, system_prompt: str = None, verbose: bool = False): self.config = config self._mcp_client = MCPClient(config) # Initialize LLM based on provider self._llm = self._create_llm() # Create tool functions from MCP self._tool_functions = self._create_tool_functions() # Create the ReAct agent self._agent = ReActAgent( tools=self._tool_functions, llm=self._llm, system_prompt=system_prompt or DEFAULT_SYSTEM_PROMPT, ) # Persistent context for multi-turn conversations self._context = Context(self._agent) def _create_llm(self): """Create the LLM instance based on configuration.""" if self.config.llm_provider == "anthropic": from llama_index.llms.anthropic import Anthropic return Anthropic( api_key=self.config.anthropic_api_key, model=self.config.anthropic_model, ) else: from llama_index.llms.openai import OpenAI return OpenAI( api_key=self.config.openai_api_key, model=self.config.openai_model, ) def chat(self, message: str) -> str: """Send a message and get a response with multi-turn context.""" import asyncio return asyncio.run(self._achat(message)) async def _achat(self, message: str) -> str: """Async implementation of chat.""" handler = self._agent.run(message, ctx=self._context) response = await handler return str(response)

ステップ 5: エージェントチャットボットの構築

対話型のエージェントチャットボットを作成します：

#!/usr/bin/env python3 """Interactive chat application for querying data with AI.""" from dotenv import load_dotenv from connectai_llamaindex import MCPAgent, Config load_dotenv() def main(): print("=" * 60) print("CData Connect AI - LlamaIndex Chat Assistant") print("=" * 60) # Initialize configuration and agent config = Config.from_env() with MCPAgent(config, verbose=False) as agent: print(" Connected! Available tools:", ", ".join(agent.get_available_tools())) print(" Chat with your data! Type 'quit' to exit. ") while True: user_input = input("You: ").strip() if user_input.lower() in ("quit", "exit"): print("Goodbye!") break if user_input.lower() == "clear": agent.clear_history() print("Conversation history cleared. ") continue response = agent.chat(user_input) print(f" Assistant: {response} ") if __name__ == "__main__": main()

ステップ 6: アプリケーションの実行

すべての設定が完了したら、エージェントチャットボットを実行します：

python basic_chat.py

以下のような出力が表示されます：

============================================================
CData Connect AI - LlamaIndex Chat Assistant
============================================================

Connected! Available tools: getCatalogs, getSchemas, getTables, getColumns, queryData, getProcedures, getProcedureParameters, executeProcedure, getInstructions

Chat with your data! Type 'quit' to exit.

You: What data sources do I have?

ステップ 7: クエリの例

エージェントチャットボットで試せるプロンプトの例をいくつか紹介します：

データの検出

  • 「接続されているデータソースは何ですか？」
  • 「demo_organization のすべてのテーブルを見せてください」
  • 「account テーブルにはどんなカラムがありますか？」

基本的なクエリ

  • 「annual_revenue でソートした上位 5 件のアカウントをクエリしてください」
  • 「優先度別のサポートチケット数を教えてください」
  • 「オープン中のすべての商談を表示してください」

マルチターン会話

ReAct エージェントはターンをまたいでコンテキストを保持するため、自然なフォローアップ質問が可能です：

  • あなた：「account テーブルを見せてください」
  • あなた：「どのアカウントの収益が一番高いですか？」
  • あなた：「その会社についてもっと詳しく教えてください」

分析

  • 「最も多くの重要なサポートチケットを持つアカウントはどれですか？」
  • 「Aurora Healthcare Systems のヘルス状態を要約してください」
  • 「収益は高いが製品使用率が低いアカウントを見つけてください」

ステップ 8: 利用可能な MCP ツール

AI エージェントは、以下の CData Connect AI ツールにアクセスできます：

ツール説明
getCatalogs利用可能なデータソース接続を一覧表示
getSchemas特定のカタログのスキーマを取得
getTablesスキーマ内のテーブルを取得
getColumnsテーブルのカラムメタデータを取得
queryDataSQL クエリを実行
getProceduresストアドプロシージャを一覧表示
getProcedureParametersプロシージャのパラメータ詳細を取得
executeProcedureストアドプロシージャを実行
getInstructionsデータソース固有のドライバーガイダンスを取得

ステップ 9: 高度な機能

レスポンスのストリーミング

インタラクティブなアプリケーション向けに、リアルタイムのトークンストリーミングを利用できます：

with MCPAgent(config) as agent: tokens = agent.stream_chat("Analyze my sales data") for token in tokens: print(token, end="", flush=True)

低レベル MCP クライアント

AI を介さず、プログラムから直接 MCPClient を使用してデータにアクセスすることもできます：

from connectai_llamaindex import MCPClient, Config config = Config.from_env() with MCPClient(config) as client: # List available tools tools = client.list_tools() # Get catalogs catalogs = client.get_catalogs() print(catalogs) # Execute a query results = client.query_data( "SELECT * FROM [demo_organization].[GoogleSheets].[account] LIMIT 10" ) print(results)

カスタムシステムプロンプト

ドメイン固有のシステムプロンプトを使用して、エージェントの動作をカスタマイズできます：

custom_prompt = """You are a financial analyst assistant. When analyzing data: 1. Always calculate key financial metrics 2. Identify trends and anomalies 3. Provide actionable insights """ agent = MCPAgent(config, system_prompt=custom_prompt)

Anthropic Claude の使用

環境変数を更新して、Anthropic の Claude モデルに切り替えることもできます：

# .env ファイル内 LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=your-anthropic-api-key ANTHROPIC_MODEL=claude-sonnet-4-20250514

ステップ 10: SQL クエリの形式

AI が SQL クエリを生成する際、完全修飾テーブル名を使用します：

SELECT [column1], [column2] FROM [CatalogName].[SchemaName].[TableName] WHERE [column1] = 'value' ORDER BY [column2] LIMIT 100

例えば、Google スプレッドシートの account テーブルをクエリするには：

SELECT [name], [annual_revenue], [industry] FROM [demo_organization].[GoogleSheets].[account] ORDER BY [annual_revenue] DESC LIMIT 10

トラブルシューティング

認証エラー

  • .env の CData メールアドレスと PAT が正しいことを確認してください
  • PAT が期限切れになっていないことを確認してください
  • Connect AI アカウントがアクティブであることを確認してください

ツールが利用できない

  • Connect AI に少なくとも 1 つのデータソースが接続されていることを確認してください
  • ユーザーが接続にアクセスする権限を持っていることを確認してください

LLM プロバイダーのエラー

  • OpenAI または Anthropic の API キーが正しく設定されていることを確認してください
  • LLM_PROVIDER の値が、設定済みの API キーと一致していることを確認してください
  • 選択したプロバイダーに対して有効なモデル名が指定されていることを確認してください

クエリエラー

  • 完全修飾テーブル名を使用してください: [Catalog].[Schema].[Table]
  • getColumns ツールを使用してカラム名が存在することを確認してください
  • SQL 構文を確認してください（Connect AI は SQL-92 標準を使用）

次のステップ

動作する LlamaIndex AI エージェントができたので、以下のことを試してみてください：

  • より多くのデータソースを接続: Salesforce、Snowflake、またはサポートされている 350 以上のソースを追加して、データアクセスを拡張できます。
  • エージェントをカスタマイズ: 特定のユースケースやドメインに合わせてシステムプロンプトを変更できます。
  • 本番アプリケーションを構築: エージェントを Web アプリ、Slack ボット、またはその他のインターフェースに統合できます。
  • ストリーミングを追加: リアルタイムのレスポンスストリーミングのために stream_chat() を使用できます。
  • サンプルを探索: GitHub リポジトリの追加サンプルで、データ分析ワークフロー、マルチソースクエリなどを確認してみてください。

リソース


CData Connect AI を始めよう

AI 搭載のデータアプリケーションを構築する準備はできましたか？CData Connect AI は、AI アプリケーションから 350 以上の SaaS、ビッグデータ、NoSQL ソースへのライブデータアクセスを提供します。

無料トライアルにサインアップして、今日からインテリジェントなデータアシスタントの構築を始めましょう！