00 Configuración

Resultado

Un repositorio clonado con un entorno virtual de Python instalado, un archivo .env con credenciales de OpenRouter, ClickHouse Cloud y Langfuse Cloud, una base de datos arena de ClickHouse Cloud con datos sintéticos de comercio electrónico y el dashboard local en http://localhost:5174. Por ahora, la pestaña Leaderboard estará vacía; es lo esperado hasta el Módulo 01.

Por qué

Agent Arena tiene un único núcleo de agente NL→SQL (agents/) que reutilizan dos clientes: el harness del benchmark (eval/harness.py) y la API de servicio en vivo (serving/api.py). Así, la demostración y el benchmark comparten exactamente la misma ruta de código: las mismas plantillas de prompt, el mismo cliente de modelo y el mismo sandbox SQL de solo lectura. Por eso las cifras del benchmark predicen de forma fiable el comportamiento en producción, en vez de proceder de un «harness de evaluación» separado que se desvía silenciosamente de lo publicado.

Fíjate en que Langfuse es una de las tres cuentas que configuras en este primer módulo, antes de elegir un modelo o ejecutar una sola pregunta. Es intencionado: Langfuse no se añade cuando el chatbot ya funciona; es la herramienta que ejecuta la competición del Módulo 01, mide al ganador offline en el Módulo 02, detecta un punto ciego de producción en el Módulo 03, respalda la investigación humana del Módulo 04 y demuestra y monitoriza la mejora en el Módulo 05. Un proyecto y un rastro continuo de pruebas. Todos los módulos posteriores parten de esa ruta de código y ese proyecto de Langfuse, por lo que dejar bien configuradas aquí las tres cuentas y la base de datos hace que el resto del taller funcione sin fricciones.

Conceptos — bajo el capó

Tres pilares con tres funciones, conectados desde este primer módulo:

• OpenRouter — una API compatible con OpenAI delante de todas las familias de modelos del taller (Anthropic, OpenAI, Google, DeepSeek, Qwen y Z.ai). En vez de manejar seis SDK y seis conjuntos de credenciales, el núcleo (agents/) usa un solo cliente para acceder a los seis modelos de config.yaml. Esto permite una competición justa y comparable en el Módulo 01: cada modelo está a una cadena model= de distancia, detrás del mismo endpoint y con la misma forma de solicitud.
• ClickHouse — la base de datos de la aplicación. Aloja los datos de negocio (las tablas sintéticas de comercio electrónico que vas a preparar) detrás de las vistas v_*. El agente solo puede ejecutar SELECT sobre las vistas v_*: nunca sobre tablas sin procesar y nunca puede escribir. Además de ofrecerle un contrato estable, documentado y de solo lectura, agents/sqlguard.py lo impone como sandbox exclusivo para SELECT: analiza el SQL generado, rechaza todo lo que no sea una única sentencia SELECT/WITH…SELECT y bloquea una lista de palabras clave de escritura/DDL (INSERT, UPDATE, DELETE, DROP, ALTER, SYSTEM, …), incluso dentro de una sentencia que de otro modo sería válida.
• Langfuse — el almacén de evaluación, leaderboard y observabilidad. Se conecta ahora, antes de elegir un modelo o formular una sola pregunta, porque no es un complemento para más tarde: puntúa la competición del Módulo 01, permite analizar la calidad en el Módulo 02, detecta fallos de producción en el Módulo 03, conserva la revisión humana en el Módulo 04 y valida el tráfico futuro en el Módulo 05. Un proyecto y un rastro continuo de trazas, feedback, puntuaciones, anotaciones y datasets.

Objetivo

Tres conjuntos de credenciales en .env, una base arena con las vistas v_* que consultará el agente y el dashboard local accesible desde el navegador.

Paso 1 — Crear tres cuentas

Necesitas credenciales de API de tres servicios antes de abrir el terminal:

Ten a mano los tres conjuntos: enseguida los pegarás en .env.

Ajuste de privacidad de OpenRouter necesario para Qwen

En OpenRouter, abre Settings → Privacy → Data Policies → Zero Data Retention y desactiva Non-frontier (el interruptor debe quedar gris). Qwen pertenece al grupo de modelos non-frontier de OpenRouter y su endpoint disponible de Alibaba no se puede usar cuando se exige Zero Data Retention para ese grupo. Si lo dejas habilitado, qwen/qwen3.7-flash falla con No endpoints available matching your guardrail restrictions and data policy aunque la clave de API y el identificador del modelo sean válidos.

El taller envía preguntas y esquemas sintéticos de comercio electrónico. Para cargas reales, revisa los requisitos de privacidad de tu organización antes de relajar una política ZDR.

Paso 2 — Clonar el repositorio

Agent Arena se encuentra en el monorepo ClickHouse_Demos, dentro de workshops/agent_arena en la rama build-workshop-v1. Clona el repositorio completo y entra en ese subdirectorio; todos los comandos siguientes presuponen que te encuentras allí:

git clone --branch build-workshop-v1 --single-branch https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos/workshops/agent_arena

Paso 3 — Crear un entorno virtual e instalar dependencias

python3.11 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Paso 4 — Configurar .env

Copia el archivo de ejemplo:

cp .env.example .env

.env

Rellena los valores del paso 1; todos los valores siguientes están vacíos o son placeholders en .env.example:

# ClickHouse Cloud (business data queried by the agent)
export CLICKHOUSE_CLOUD_HOST=xxx.clickhouse.cloud
export CLICKHOUSE_CLOUD_USER=default
export CLICKHOUSE_CLOUD_PASSWORD=
export CLICKHOUSE_CLOUD_DATABASE=arena
export ARENA_RO_PASSWORD=
# OpenRouter (LLM provider)
export OPENROUTER_API_KEY=sk-or-...
export OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
# Langfuse Cloud (eval store + tracing)
export LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...

Finalidad de cada bloque:

• CLICKHOUSE_CLOUD_* — credenciales de administrador del servicio de ClickHouse Cloud. La configuración usa una vez ese usuario para crear la base arena y un usuario de solo lectura dedicado (arena_ro) que utiliza el agente durante el resto del taller.
• ARENA_RO_PASSWORD — elige una contraseña; se convertirá en la contraseña de arena_ro al crear el usuario de solo lectura.
• OPENROUTER_* — la clave de OpenRouter y su URL base. Todos los modelos de config.yaml se invocan mediante este endpoint.
• LANGFUSE_* — el host y las claves del proyecto de Langfuse Cloud. Aquí viven todas las trazas, puntuaciones y datasets del taller, desde la primera ejecución de la Arena en el Módulo 01 hasta la mejora monitorizada del Módulo 05.

Paso 5 — Preparar ClickHouse con datos sintéticos de comercio electrónico

Esto crea la base arena, el usuario de solo lectura arena_ro, genera directamente en ClickHouse datos sintéticos de comercio electrónico (clientes, productos, pedidos, líneas de pedido y eventos) y construye las vistas v_* que consulta el agente:

source .env && scripts/arena.sh up

Todos los agentes, prompts y fragmentos de SQL dorado del taller consultan las vistas v_customers, v_products, v_orders, v_order_items y v_events, nunca las tablas sin procesar.

scripts/arena.sh up también inicia la API y la interfaz web del dashboard local. Cuando termine, abre http://localhost:5174. La pestaña Leaderboard estará vacía hasta que ejecutes la competición del Módulo 01.

Aspecto de una ejecución correcta. scripts/arena.sh up muestra, en orden:

1. ClickHouse: business database + read-only agent user — se crean la base arena y el usuario dedicado arena_ro.
2. Seeding ClickHouse directly + views + schema context — una línea clickhouse: inserted <N> into <table> por tabla (customers, products, orders, order_items, events), seguida de done; después se crean las vistas v_* y el contexto de esquema que lee el agente.
3. Starting dashboard API (:8000) + web UI (:5174) — dos líneas [ready]. Si alguna indica [NOT up], probablemente el puerto esté ocupado; consulta la ruta del registro que muestra (.run/dashboard-api.log o .run/web.log).

Puedes volver a comprobarlo más adelante con scripts/arena.sh status, que indica si los servidores están activos y el número de filas de cada vista v_*.

Cómo verificar que has terminado

• .env contiene valores reales, no placeholders, para CLICKHOUSE_CLOUD_*, OPENROUTER_* y LANGFUSE_*.
• scripts/arena.sh up terminó sin errores.
• http://localhost:5174 se abre en un navegador y muestra la pestaña Leaderboard; por ahora es correcto que esté vacía.

Ejercicio — interrumpir y diagnosticar una conexión

Aprende a reconocer la firma de error de un valor incorrecto de .env provocándolo a propósito, cuando no hay nada en juego:

1. Abre .env y cambia un carácter de ARENA_RO_PASSWORD (o coméntalo temporalmente).
2. Vuelve a ejecutar source .env && scripts/arena.sh up. Debería completar los pasos de administración de ClickHouse, que usan las credenciales de administrador, pero observa cuándo empieza a fallar la ruta de solo lectura, es decir, cualquier conexión como arena_ro.
3. Lee detenidamente el mensaje: ¿es un error de autenticación, un error que indica que el usuario no existe o un silencio seguido de timeout? Anota cuál aparece.
4. Restaura el valor correcto de ARENA_RO_PASSWORD, vuelve a ejecutar scripts/arena.sh up y confirma que termina correctamente.

Este es el mismo instinto de diagnóstico que necesitarás cuando la configuración de otra persona «no funcione»: relacionar el texto del error con cuál de los tres servicios está mal configurado, en vez de revisarlo todo.

Resumen

Ya tienes una base de ClickHouse preparada, credenciales de los tres servicios —incluido Langfuse, conectado antes de elegir ningún modelo— y el dashboard local en funcionamiento. Todos los módulos siguientes reutilizan el mismo entorno y el mismo proyecto de Langfuse; no hay más pasos de configuración.

Estado final

Entorno listo. Continúa con 01 Seleccionar el modelo base para ejecutar la competición con estos datos.