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

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

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

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

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

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

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

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

Установите библиотеку Microsoft Agent Framework, выполнив следующие команды:

pip install -q --upgrade pip
pip install -q agent-framework --pre
pip install -q ipywidgets

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

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

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

Введите ключ API OpenAI: ········

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

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

Инициализация MCP Server и агента Microsoft Agent Framework

Теперь настройте ClickHouse MCP Server для подключения к ClickHouse SQL playground, инициализируйте агента и задайте ему вопрос:

from agent_framework import ChatAgent, MCPStdioTool
from agent_framework.openai import OpenAIResponsesClient

clickhouse_mcp_server = MCPStdioTool(
    name="clickhouse",
    command="uv",
    args=[
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
    ],
    env=env
)


async with ChatAgent(
    chat_client=OpenAIResponsesClient(model_id="gpt-5-mini-2025-08-07"),
    name="HousePricesAgent",
    instructions="Вы — помощник, который помогает выполнять запросы к базе данных ClickHouse",
    tools=clickhouse_mcp_server,
) as agent:
    query = "Расскажите о ценах на недвижимость в Великобритании за последние пять лет"
    print(f"Пользователь: {query}")
    async for chunk in agent.run_stream(query):
        print(chunk.text, end="", flush=True)
    print("\n\n")

Результат выполнения этого скрипта показан ниже:

Пользователь: Расскажите о ценах на недвижимость в Великобритании за последние пять лет
Я проанализировал ежемесячные записи о ценах продаж в Великобритании в таблице uk.uk_price_paid_simple_partitioned за последние пять лет (toStartOfMonth(date), с октября 2020 → август 2025). Краткая сводка и ключевые моменты:

Измеренные показатели
- Метрики: ежемесячная медианная цена, средняя цена и количество транзакций (записи об уплаченных ценах).
- Охваченный период: месяцы с 2020-10-01 по 2025-08-01 (последние пять лет от текущей даты).

Основные результаты
- Медианная цена выросла с £255 000 (2020-10) до £294 500 (2025-08) — увеличение примерно на +15,4% за пять лет.
  - Эквивалентный среднегодовой темп роста (CAGR) для медианы ≈ +2,9% в год.
- Средняя цена незначительно снизилась с примерно £376 538 (2020-10) до £364 653 (2025-08) — снижение ≈ −3,2% за пять лет.
  - CAGR средней цены ≈ −0,6% в год.
- Расхождение (медиана растет, среднее значение немного снижается) указывает на изменения в структуре транзакций (меньше продаж с очень высокой стоимостью или другие структурные эффекты), поскольку среднее значение чувствительно к выбросам, в то время как медиана — нет.

Заметные закономерности и события в данных
- Значительный рост в 2020–2021 годах (виден как в медиане, так и в среднем значении), что соответствует постпандемическому всплеску рынка, связанному с гербовым сбором и повышенным спросом, наблюдавшемуся в этот период.
- Пики средних цен около середины 2022 года (средние значения ~£440 тыс.), затем общее снижение в течение 2022–2023 годов и стабилизация около 2023–2024 годов.
- Некоторые месяцы демонстрируют высокую волатильность или необычное количество транзакций (например, июнь 2021 года имел очень высокое количество транзакций; март 2025 года показывает высокую медиану, но апрель–май 2025 года показывают более низкие значения). Последние месяцы (середина 2025 года) имеют значительно меньшее количество транзакций в таблице — это часто указывает на неполную отчетность за последние месяцы и означает, что к последним ежемесячным показателям следует относиться с осторожностью.

Примеры точек данных (из запроса)
- 2020-10: медиана £255 000, среднее £376 538, транзакций 89 125
- 2022-08: пик среднего значения ~£441 209 (медиана ~£295 000)
- 2025-03: медиана ~£314 750 (одна из самых высоких медиан)
- 2025-08: медиана £294 500, среднее £364 653, транзакций 18 815 (низкое количество — вероятно, неполные данные)

Оговорки
- Это цены транзакций (набор данных Price Paid) — фактическая «стоимость» домов может отличаться.
- Среднее значение чувствительно к составу и выбросам. Изменения в типах продаваемой недвижимости (например, соотношение квартир и отдельно стоящих домов, региональное распределение) будут по-разному влиять на среднее значение и медиану.
- Последние месяцы могут быть неполными; к месяцам с необычно низким количеством транзакций следует относиться с осторожностью.
- Это национальные агрегированные данные — региональные различия могут быть существенными.

При необходимости я могу:
- Построить график медианы и среднего значения во времени.
- Сравнить данные год к году или вычислить CAGR для другого начального/конечного месяца.
- Разбить анализ по регионам/округам/городам, типу недвижимости (квартира, таунхаус, двухквартирный дом, отдельно стоящий дом) или по ценовым диапазонам.
- Показать таблицу лучших/худших регионов по росту цен за последние 5 лет.

Какой вариант продолжения вы предпочитаете?