Как создать ИИ-агента с Microsoft Agent framework и MCP-сервером ClickHouse - ClickHouse Documentation

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

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

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

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

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

1

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

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

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

2

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

Далее вам потребуется указать свой API-ключ OpenAI:

import os, getpass
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key:")

Response

Enter OpenAI API Key: ········

Затем укажите учетные данные, необходимые для подключения к песочнице ClickHouse SQL:

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

3

Инициализируйте MCP-сервер и агент фреймворка Microsoft Agent

Теперь настройте MCP-сервер ClickHouse так, чтобы он указывал на Песочницу ClickHouse SQL, а затем инициализируйте наш агент и задайте ему вопрос:

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="You are a helpful assistant that can help query a ClickHouse database",
    tools=clickhouse_mcp_server,
) as agent:
    query = "Tell me about UK property prices over the last five years"
    print(f"User: {query}")
    async for chunk in agent.run_stream(query):
        print(chunk.text, end="", flush=True)
    print("\n\n")

Ниже приведён вывод этого скрипта:

Response

User: Tell me about UK property prices over the last five years
Я проанализировал ежемесячные записи о продажах недвижимости в Великобритании из таблицы 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 лет.

Что вас интересует?

Последнее изменение 12 июня 2026 г.