Как создать AI-агента с помощью DSPy и ClickHouse MCP Server

В этом руководстве вы узнаете, как создать AI-агента с помощью DSPy, который способен взаимодействовать с SQL-песочницей ClickHouse, используя ClickHouse MCP Server.

Предварительные требования

На вашей системе должен быть установлен Python.
На вашей системе должен быть установлен pip.
Вам понадобится ключ API Anthropic или ключ API другого провайдера LLM.

Вы можете выполнить следующие шаги либо в интерактивной оболочке Python (REPL), либо с помощью скрипта.

Пример ноутбука

Этот пример представлен в виде ноутбука в репозитории с примерами.

Установка библиотек

Выполните следующие команды с помощью pip для установки необходимых библиотек:

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

Настройка учетных данных

Далее необходимо указать ваш API-ключ Anthropic:

import os
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Введите API-ключ Anthropic:")

Использование другого провайдера LLM

Если у вас нет API-ключа Anthropic и вы хотите использовать другого провайдера LLM, инструкции по настройке учётных данных можно найти в документации DSPy

Далее укажите учетные данные для подключения к SQL-песочнице ClickHouse:

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

Инициализация MCP-сервера

Теперь настройте ClickHouse MCP Server для подключения к песочнице ClickHouse SQL.

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):
    """Вы — аналитик данных. Вам будут задаваться вопросы, и вам необходимо отвечать на них, используя доступные вам инструменты."""

    user_request: str = dspy.InputField()
    process_result: str = dspy.OutputField(
        desc=(
            "Ответ на запрос"
        )
    )

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="Какая категория товаров на Amazon самая популярная")
        print_dspy_result(result)

================================================================================
🤖 Результат 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
   Аргументы: {'database': 'amazon'}

📊 РЕЗУЛЬТАТ:
   {
  "database": "amazon",
  "name": "amazon_reviews",
  "comment": "",
  "columns": [
    {
      "name": "review_date",
      "type": "Date",
      "default_type": "",
      "default_expression": "",...

📍 ШАГ 3
----------------------------------------
🧠 РАЗМЫШЛЕНИЕ: Превосходно! Обнаружена таблица amazon_reviews, содержащая столбец product_category. Эта таблица содержит более 150 миллионов строк данных об отзывах Amazon, что обеспечивает достоверное представление о популярности товаров. Для определения наиболее популярной категории товаров Amazon необходимо подсчитать количество отзывов по каждой категории и упорядочить их по убыванию. Категория с наибольшим количеством отзывов будет считаться наиболее популярной.

🔧 ИНСТРУМЕНТ: run_select_query
   Аргументы: {'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" является наиболее популярной категорией товаров Amazon с 19 530 930 отзывами, за которой следует "Digital_Ebook_Purchase" с 17 622 107 отзывами. Данные демонстрируют четкое ранжирование категорий товаров по популярности на основе количества полученных отзывов. Теперь имеется вся необходимая информация для ответа на вопрос пользователя.

🔧 ИНСТРУМЕНТ: finish

📊 РЕЗУЛЬТАТ:
   Завершено.

🎯 ОБОСНОВАНИЕ
----------------------------------------
Для ответа на вопрос о наиболее популярной категории товаров Amazon был выполнен доступ к базе данных Amazon и обнаружена таблица "amazon_reviews", содержащая более 150 миллионов записей отзывов. Эта таблица содержит столбец "product_category", позволяющий анализировать популярность товаров на основе объема отзывов. Был выполнен запрос для подсчета количества отзывов по каждой категории товаров с упорядочиванием по убыванию. Предположение заключается в том, что категории с большим количеством отзывов указывают на более высокую популярность, поскольку большее количество отзывов обычно коррелирует с большим количеством покупок и вовлеченностью клиентов.

✅ ИТОГОВЫЙ РЕЗУЛЬТАТ
----------------------------------------
На основе данных об отзывах Amazon, содержащих более 150 миллионов записей, наиболее популярной категорией товаров 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 (связанные категории) в совокупности составляют более 37 миллионов отзывов, что демонстрирует высокую популярность материалов для чтения на платформе Amazon.
================================================================================

Предварительные требования​

Установка библиотек​

Настройка учетных данных​

Инициализация MCP-сервера​

Инициализация LLM​

Запуск агента​