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

# Cómo crear un agente de IA con el framework Microsoft Agent y el ClickHouse MCP server

> Aprende a crear un agente de IA con el framework Microsoft Agent y el ClickHouse MCP server

En esta guía aprenderás a crear un agente de IA con [Microsoft Agent framework](https://github.com/microsoft/agent-framework) que puede interactuar con
[el Playground de SQL de ClickHouse](https://sql.clickhouse.com/) mediante [el ClickHouse MCP server](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **Cuaderno de ejemplo**

  Este ejemplo está disponible como cuaderno en el [repositorio de ejemplos](https://github.com/ClickHouse/examples/blob/main/ai/mcp/microsoft-agent-framework/microsoft-agent-framework.ipynb).
</Info>

<div id="prerequisites">
  ## Requisitos previos
</div>

* Necesitarás tener Python instalado en tu sistema.
* Necesitarás tener `pip` instalado en tu sistema.
* Necesitarás una clave de API de OpenAI

Puedes realizar los siguientes pasos desde el REPL de Python o mediante un script.

<Steps>
  <Step>
    ## Instalar bibliotecas

    Instala la biblioteca de Microsoft Agent Framework ejecutando los siguientes comandos:

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

  <Step>
    ## Configurar credenciales

    A continuación, tendrás que proporcionar tu clave de API de 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: ········
    ```

    A continuación, defina las credenciales necesarias para conectarse al Playground de SQL de ClickHouse:

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

  <Step>
    ## Inicializa el servidor MCP y el agente del framework de Microsoft Agent

    Ahora configura el ClickHouse MCP server para que apunte al Playground de SQL de ClickHouse
    y también inicializa nuestro agente y hazle una pregunta:

    ```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")
    ```

    La salida de este script se muestra a continuación:

    ```response title="Response" theme={null}
    Usuario: Cuéntame sobre los precios de la vivienda en el Reino Unido durante los últimos cinco años
    Analicé los registros mensuales de precios de venta en el Reino Unido en la tabla uk.uk_price_paid_simple_partitioned para los últimos cinco años (toStartOfMonth(date), de oct. 2020 → ago. 2025). Resumen y puntos clave:

    Qué medí
    - Métricas: precio mediano mensual, precio medio y número de transacciones (registros de precios pagados).
    - Período cubierto: meses desde 2020-10-01 hasta 2025-08-01 (últimos cinco años desde hoy).

    Conclusiones generales
    - El precio mediano subió de £255.000 (2020-10) a £294.500 (2025-08) — un incremento de aproximadamente +15,4% en cinco años.
      - Tasa de crecimiento anual compuesta (CAGR) equivalente para la mediana ≈ +2,9% anual.
    - El precio medio cayó ligeramente de aproximadamente £376.538 (2020-10) a £364.653 (2025-08) — un descenso de ≈ −3,2% en cinco años.
      - CAGR del precio medio ≈ −0,6% anual.
    - La divergencia (mediana al alza, media ligeramente a la baja) sugiere cambios en la composición de las transacciones (menos ventas de alto valor u otros efectos composicionales), ya que la media es sensible a los valores atípicos mientras que la mediana no lo es.

    Patrones y eventos destacados en los datos
    - Fuertes subidas en 2020–2021 (visibles tanto en la mediana como en la media), coherentes con el repunte del mercado impulsado por la demanda pospandemia y las exenciones del impuesto de timbre observadas en ese período.
    - Picos en los precios medios hacia mediados de 2022 (valores medios ~£440k), seguidos de una moderación general durante 2022–2023 y una estabilización en torno a 2023–2024.
    - Algunos meses muestran gran volatilidad o recuentos inusuales (p. ej., junio de 2021 registró recuentos de transacciones muy elevados; marzo de 2025 muestra una mediana alta, pero abril–mayo de 2025 presentan recuentos más bajos). Los meses más recientes (mediados de 2025) tienen recuentos de transacciones mucho menores en la tabla — esto suele indicar que los datos de los meses más recientes están incompletos, por lo que las cifras mensuales recientes deben interpretarse con cautela.

    Puntos de datos de ejemplo (de la consulta)
    - 2020-10: mediana £255.000, media £376.538, transacciones 89.125
    - 2022-08: pico de la media ~£441.209 (mediana ~£295.000)
    - 2025-03: mediana ~£314.750 (una de las medianas más altas)
    - 2025-08: mediana £294.500, media £364.653, transacciones 18.815 (recuento bajo — probablemente incompleto)

    Advertencias
    - Estos son precios de transacción (conjunto de datos Price Paid) — los «valores» reales de las viviendas pueden diferir.
    - La media es sensible a la composición y a los valores atípicos. Los cambios en los tipos de propiedades vendidas (p. ej., combinación de pisos frente a casas unifamiliares, combinación regional) afectarán de forma distinta a la media y a la mediana.
    - Los meses más recientes pueden estar incompletos; los meses con recuentos de transacciones inusualmente bajos deben tratarse con cautela.
    - Se trata de un agregado nacional — las diferencias regionales pueden ser sustanciales.

    Si lo desea, puedo:
    - Generar un gráfico de la mediana y la media a lo largo del tiempo.
    - Comparar año a año o calcular la CAGR para un mes de inicio/fin diferente.
    - Desglosar el análisis por región/condado/localidad, tipo de propiedad (piso, adosado, pareado, unifamiliar) o por rangos de precio.
    - Mostrar una tabla de las regiones con mayor/menor crecimiento de precios en los últimos 5 años.

    ¿Qué análisis adicional le gustaría?

    ```
  </Step>
</Steps>