> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Узнайте, как создать ИИ-агента с Microsoft Agent framework и MCP-сервером ClickHouse

В этом руководстве вы узнаете, как создать ИИ-агента на базе [Microsoft Agent framework](https://github.com/microsoft/agent-framework), который может взаимодействовать с
[SQL-песочницей ClickHouse](https://sql.clickhouse.com/) с помощью [MCP-сервера ClickHouse](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **Пример ноутбука**

  Этот пример доступен в виде ноутбука в [репозитории examples](https://github.com/ClickHouse/examples/blob/main/ai/mcp/microsoft-agent-framework/microsoft-agent-framework.ipynb).
</Info>

<div id="prerequisites">
  ## Предварительные требования
</div>

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

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

<Steps>
  <Step>
    ## Установка библиотек

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

    ```python theme={null}
    pip install -q --upgrade pip
    pip install -q agent-framework --pre
    pip install -q ipywidgets
    ```
  </Step>

  <Step>
    ## Настройка учетных данных

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

    ```python theme={null}
    import os, getpass
    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key:")
    ```

    ```response title="Response" theme={null}
    Enter OpenAI API Key: ········
    ```

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

    ```python theme={null}
    env = {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true"
    }
    ```
  </Step>

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

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

    ```python theme={null}
    from agent_framework import ChatAgent, MCPStdioTool
    from agent_framework.openai import OpenAIResponsesClient
    ```

    ```python theme={null}
    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 title="Response" theme={null}
    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 лет.

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

    ```
  </Step>
</Steps>