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 que puede interactuar con el Playground de SQL de ClickHouse mediante el ClickHouse MCP server.

Cuaderno de ejemplo

Este ejemplo está disponible como cuaderno en el repositorio de ejemplos.

​

Requisitos previos

• 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.

1. ​

   Instalar bibliotecas

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

   pip install -q --upgrade pip
   pip install -q agent-framework --pre
   pip install -q ipywidgets
   
2. ​

   Configurar credenciales

   A continuación, tendrás que proporcionar tu clave de API de OpenAI:

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

   Response

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

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

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

   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:

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

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

   Response

   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?