> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# DSPy と ClickHouse MCP server を使って AI エージェントを構築する方法
> DSPy と ClickHouse MCP server を使って AI エージェントを構築する方法を学びます
このガイドでは、[DSPy](https://github.com/langchain-ai/langgraph) を使って AI エージェントを構築し、
[ClickHouse の SQL playground](https://sql.clickhouse.com/) を [ClickHouse MCP server](https://github.com/ClickHouse/mcp-clickhouse) 経由で操作する方法を学びます。
## 前提条件
* システムに Python がインストールされている必要があります。
* システムに `pip` がインストールされている必要があります。
* Anthropic の API キー、または別の LLM プロバイダーの API キーが必要です。
以下の手順は、Python の REPL またはスクリプトから実行できます。
**サンプルノートブック**
このサンプルは、[examples リポジトリ](https://github.com/ClickHouse/examples/blob/main/ai/mcp/dspy/dspy.ipynb) 内のノートブックとして提供されています。
## ライブラリをインストールする
必要なライブラリをインストールするには、`pip` を使って次のコマンドを実行します。
```shell theme={null}
pip install -q --upgrade pip
pip install -q dspy
pip install -q mcp
```
## 認証情報を設定する
次に、Anthropic APIキーを指定する必要があります。
```python theme={null}
import os
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")
```
**別のLLMプロバイダーを使用する場合**
Anthropic APIキーをお持ちでなく、別のLLMプロバイダーを使用したい場合は、
[DSPyドキュメント](https://dspy.ai/#__tabbed_1_1)で認証情報の設定手順を確認できます
次に、ClickHouse SQL playground への接続に必要な認証情報を定義します。
```python theme={null}
env = {
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true"
}
```
## MCPサーバーを初期化する
次に、ClickHouse MCPサーバーの接続先としてClickHouse SQL playgroundを設定します。
```python theme={null}
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 を初期化します。
```python theme={null}
dspy.configure(lm=dspy.LM("anthropic/claude-sonnet-4-20250514"))
```
## エージェントの実行
最後に、エージェントを初期化して起動します：
```python theme={null}
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 title="Response" theme={null}
================================================================================
🤖 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プラットフォームにおける読書関連コンテンツの根強い人気がうかがえます。
================================================================================
```