DSPy と ClickHouse MCP server を使って AI エージェントを構築する方法

このガイドでは、DSPy を使って AI エージェントを構築し、 ClickHouse の SQL playground を ClickHouse MCP server 経由で操作する方法を学びます。

前提条件

システムに Python がインストールされている必要があります。
システムに pip がインストールされている必要があります。
Anthropic の API キー、または別の LLM プロバイダーの API キーが必要です。

以下の手順は、Python の REPL またはスクリプトから実行できます。

サンプルノートブックこのサンプルは、examples リポジトリ内のノートブックとして提供されています。

ライブラリをインストールする

必要なライブラリをインストールするには、pip を使って次のコマンドを実行します。

pip install -q --upgrade pip
pip install -q dspy
pip install -q mcp

認証情報を設定する

次に、Anthropic APIキーを指定する必要があります。

import os
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")

別のLLMプロバイダーを使用する場合Anthropic APIキーをお持ちでなく、別のLLMプロバイダーを使用したい場合は、 DSPyドキュメントで認証情報の設定手順を確認できます

次に、ClickHouse SQL playground への接続に必要な認証情報を定義します。

env = {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true"
}

MCPサーバーを初期化する

次に、ClickHouse MCPサーバーの接続先としてClickHouse SQL playgroundを設定します。

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import dspy

server_params = StdioServerParameters(
    command="uv",
    args=[
        'run',
        '--with', 'mcp-clickhouse',
        '--python', '3.13',
        'mcp-clickhouse'
    ],
    env=env
)

LLM を初期化する

次に、以下の行で LLM を初期化します。

dspy.configure(lm=dspy.LM("anthropic/claude-sonnet-4-20250514"))

エージェントの実行

最後に、エージェントを初期化して起動します：

class DataAnalyst(dspy.Signature):
    """You are a data analyst. You'll be asked questions and you need to try to answer them using the tools you have access to. """

    user_request: str = dspy.InputField()
    process_result: str = dspy.OutputField(
        desc=(
            "Answer to the query"
        )
    )

from utils import print_dspy_result

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

        dspy_tools = []
        for tool in tools.tools:
            dspy_tools.append(dspy.Tool.from_mcp_tool(session, tool))

        react = dspy.ReAct(DataAnalyst, tools=dspy_tools)
        result = await react.acall(user_request="What's the most popular Amazon product category")
        print_dspy_result(result)

Response

================================================================================
🤖 DSPy ReAct 結果
================================================================================

📍 ステップ 1
----------------------------------------
🧠 思考中: Amazonの商品カテゴリに関する情報を調べ、最も人気のあるカテゴリを特定する必要があります。まず、Amazon関連のデータが存在するかどうかを確認するため、利用可能なデータベースを確認します。

🔧 ツール: list_databases

📊 結果:
   amazon
bluesky
country
covid
default
dns
environmental
food
forex
geo
git
github
hackernews
imdb
logs
metrica
mgbench
mta
noaa
nyc_taxi
nypd
ontime
opensky
otel
otel_v2
pypi
random
reddit
rubygems
sta...

📍 ステップ 2
----------------------------------------
🧠 思考中: 「amazon」データベースが利用可能であることを確認できました。Amazonの商品カテゴリ情報を調べるのに必要なものです。amazonデータベース内のテーブルを確認して、どのようなデータが利用できるかを調べます。

🔧 ツール: list_tables
   Args: {'database': 'amazon'}

📊 結果:
   {
  "database": "amazon",
  "name": "amazon_reviews",
  "comment": "",
  "columns": [
    {
      "name": "review_date",
      "type": "Date",
      "default_type": "",
      "default_expression": "",...

📍 ステップ 3
----------------------------------------
🧠 思考中: product_categoryカラムを含むamazon_reviewsテーブルが見つかりました。このテーブルには1億5000万行を超えるAmazonレビューデータが含まれており、商品の人気度を把握するには十分なデータ量です。最も人気のあるAmazon商品カテゴリを特定するには、カテゴリごとのレビュー数を集計し、降順に並べ替える必要があります。レビュー数が最も多いカテゴリが最も人気があると判断します。

🔧 ツール: run_select_query
   Args: {'query': 'SELECT product_category, COUNT(*) as review_count FROM amazon.amazon_reviews GROUP BY product_category ORDER BY review_count DESC LIMIT 10'}

📊 結果:
   1. Books: 19,530,930 件のレビュー
   2. Digital_Ebook_Purchase: 17,622,107 件のレビュー
   3. Wireless: 9,001,567 件のレビュー
   4. PC: 6,908,245 件のレビュー
   5. Home: 6,221,321 件のレビュー
   ... 他 5 件

📍 ステップ 4
----------------------------------------
🧠 思考中: ユーザーの質問に対する回答が得られました。Amazonレビューデータによると、「Books」が19,530,930件のレビューで最も人気のあるAmazon商品カテゴリであり、次いで「Digital_Ebook_Purchase」が17,622,107件で続いています。データは、各カテゴリのレビュー数に基づく明確な人気ランキングを示しています。ユーザーの質問に回答するために必要な情報がすべて揃いました。

🔧 ツール: finish

📊 結果:
   完了。

🎯 推論
----------------------------------------
最も人気のあるAmazon商品カテゴリに関する質問に回答するため、Amazonデータベースにアクセスし、1億5000万件を超えるレビューレコードを持つ「amazon_reviews」テーブルを見つけました。このテーブルには「product_category」カラムが含まれており、レビュー数をもとに商品の人気度を分析できます。商品カテゴリごとのレビュー数を集計するクエリを実行し、降順に並べ替えました。ここでの前提は、レビュー数が多いカテゴリほど人気が高いというものです。レビュー数の多さは、購入数や顧客エンゲージメントの高さと相関する傾向があるためです。

✅ 最終結果
----------------------------------------
1億5000万件を超えるレコードを含むAmazonレビューデータによると、最も人気のあるAmazon商品カテゴリは **Books** で、19,530,930件のレビューを獲得しています。

レビュー数による上位10のAmazon商品カテゴリは以下のとおりです：

1. **Books** - 19,530,930 件のレビュー
2. **Digital_Ebook_Purchase** - 17,622,107 件のレビュー
3. **Wireless** - 9,001,567 件のレビュー
4. **PC** - 6,908,245 件のレビュー
5. **Home** - 6,221,321 件のレビュー
6. **Apparel** - 5,906,085 件のレビュー
7. **Health & Personal Care** - 5,331,239 件のレビュー
8. **Beauty** - 5,115,462 件のレビュー
9. **Video DVD** - 5,069,014 件のレビュー
10. **Mobile_Apps** - 5,033,164 件のレビュー

注目すべき点として、BooksとDigital Ebook Purchase（いずれも関連カテゴリ）を合わせると3700万件を超えるレビューとなり、Amazonプラットフォームにおける読書関連コンテンツの根強い人気がうかがえます。
================================================================================

​前提条件

​ライブラリをインストールする

​認証情報を設定する

​MCPサーバーを初期化する

​LLM を初期化する

​エージェントの実行

前提条件

ライブラリをインストールする

認証情報を設定する

MCPサーバーを初期化する

LLM を初期化する

エージェントの実行