00 Configuración

Guía del facilitador para la lección 00 Configuración.

Antes de la sesión — aprovisiona una clave compartida para participantes (uso justo)

En una sesión pública dirigida por un instructor, no entregues tu clave personal de OpenRouter —ni una sin límite— a desconocidos. La API de administración (aprovisionamiento) de OpenRouter crea mediante código claves específicas con un límite estricto de créditos, por lo que el gasto del taller queda acotado y es justo.

1. Crea una clave de administración (una vez). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. Puede crear, inspeccionar y eliminar otras claves y gastar en tu cuenta; trátala como una credencial administrativa.

export OPENROUTER_PROVISIONING_KEY=sk-or-v1-<management-key>   # instructor only — never share

2. Aprovisiona la clave compartida con límite estricto. El repositorio incluye el auxiliar (scripts/provision_workshop_keys.py), que llama a POST https://openrouter.ai/api/v1/keys:

# one shared key the whole room uses, capped at $20 total (reset daily at 00:00 UTC):
python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 20 --daily

La respuesta de creación muestra la cadena de la clave una sola vez; cópiala y entrégala como OPENROUTER_API_KEY. Después solo se puede recuperar su hash para inspeccionarla o eliminarla. ¿Prefieres curl? Es la misma llamada:

curl -s https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $OPENROUTER_PROVISIONING_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Agent Arena workshop","limit":20}'

python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 2 --count 30

3. Supervisa y limpia. Revisa el gasto durante la sesión y elimina las claves al terminar:

python -m scripts.provision_workshop_keys --list
python -m scripts.provision_workshop_keys --delete <keyHash>

Dimensionamiento: los modelos pertenecen al nivel económico flash-lite y la cuadrícula solo tiene 6 × 3 = 18 configuraciones. Un límite compartido de 20 USD cubre holgadamente una sala completa ejecutando la Arena varias veces; protege frente a bucles descontrolados, no es un presupuesto ajustado.

Tiempo

~25–30 minutos si las cuentas ya existen; reserva más para crearlas.

• 5 min — crear las tres cuentas (OpenRouter, Langfuse Cloud y ClickHouse Cloud) si no se hizo el día anterior.
• 5 min — clonar el repositorio, crear el entorno virtual e instalar dependencias.
• 5 min — completar .env.
• 5 min — ejecutar source .env && scripts/arena.sh up y confirmar el dashboard en http://localhost:5174.

Antes de la sesión, abre OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention, desactiva Non-frontier (gris/desactivado) y prueba Qwen con la clave del participante. Qwen se dirige al endpoint sin ZDR de Alibaba; activar ZDR para non-frontier produce No endpoints available matching your guardrail restrictions and data policy incluso con Alibaba permitida y guardrails flexibles. Es una opción de cuenta que no puede relajarse por la API de administración ni por un parámetro. Úsala solo para la carga sintética del taller y respeta los requisitos de tu organización para datos reales.

Guion

• Empieza nombrando las tres cuentas —OpenRouter, ClickHouse Cloud y Langfuse Cloud— y deja claro que Langfuse entra en el primer módulo, antes de elegir ningún modelo. No es un añadido de producción del Módulo 03: ejecutará la competición y conservará las pruebas durante la publicación, investigación y mejora.
• Señala la ruta de código compartida: agents/ se usa tanto en eval/harness.py (benchmark) como en serving/api.py (producción), así que lo medido hoy coincide con lo publicado en el Módulo 03.
• Narra qué hace scripts/arena.sh up: crea la base arena, el usuario de solo lectura arena_ro, genera datos sintéticos de comercio electrónico en ClickHouse, crea las vistas v_* e inicia la API y la interfaz web del dashboard.
• Advierte que la pestaña Leaderboard estará vacía al terminar. Es correcto y prepara el Módulo 01.

Fallos habituales

• Placeholder OPENROUTER_API_KEY conservado como sk-or-... — el harness fallará con 401 cuando llame a un modelo en el Módulo 01. Pide que confirmen ahora una clave real en .env.
• ARENA_RO_PASSWORD vacío — scripts/arena.sh up aún crea arena_ro, pero la política de contraseñas del servicio puede rechazar al cliente. Define cualquier valor no vacío.
• Servicio ClickHouse Cloud aún aprovisionándose — un servicio nuevo puede tardar unos minutos en aceptar conexiones; espera y vuelve a ejecutar scripts/arena.sh up.
• .env no cargado — ejecuta source .env && scripts/arena.sh up en la misma línea; scripts/arena.sh up solo, en otro shell, falla porque faltan variables CLICKHOUSE_CLOUD_*.
• Puerto 5174 (u 8000) en uso — queda un proceso anterior. scripts/arena.sh stop limpia los servidores antes de repetir up.

Pasos de recuperación

• Recrea todo con source .env && scripts/arena.sh up. Es idempotente, no usa Aurora, ClickPipes ni ClickStack y recrea la base arena, el usuario arena_ro, los datos sintéticos y las vistas v_*, y reinicia la API y la interfaz. Los resultados del benchmark permanecen en Langfuse.
• Si solo se bloquearon los servidores locales, scripts/arena.sh stop seguido de scripts/arena.sh serve es más rápido que un up completo.
• Comprueba el estado con scripts/arena.sh status: muestra la API, la interfaz y el recuento de filas de cada vista v_*.
• Si .env aún contiene placeholders, consigue la credencial real y ejecuta de nuevo scripts/arena.sh up.