00 Configuração

Guia do facilitador para a lição 00 Configuração.

Antes da sessão — provisione uma chave compartilhada para os participantes (uso justo)

Em uma sessão pública com instrutor, não entregue sua chave pessoal do OpenRouter — nem uma chave sem limite — a desconhecidos. A API de gerenciamento (provisionamento) do OpenRouter cria programaticamente chaves específicas com um limite rígido de créditos, mantendo o custo do workshop limitado e justo.

1. Crie uma chave de gerenciamento (uma vez). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. Ela pode criar, inspecionar e excluir outras chaves e gastar na sua conta; trate-a como credencial administrativa.

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

2. Provisione a chave compartilhada com limite rígido. O repositório inclui o auxiliar (scripts/provision_workshop_keys.py), que chama 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

A resposta de criação exibe a string da chave uma única vez; copie-a e entregue-a como OPENROUTER_API_KEY. Depois, somente o hash pode ser recuperado para inspeção ou exclusão. Prefere curl puro? Use a mesma chamada:

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. Monitore e limpe. Inspecione os gastos durante a sessão e exclua as chaves ao terminar:

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

Dimensionamento: os modelos são da categoria econômica flash-lite e a grade tem apenas 6 × 3 = 18 configurações. Um limite compartilhado de US$ 20 cobre com folga uma turma inteira executando a Arena algumas vezes; é uma proteção contra loops fora de controle, não um orçamento apertado.

Tempo

~25 a 30 minutos quando as contas já existem; reserve mais tempo para criá-las.

• 5 min — criar as três contas (OpenRouter, Langfuse Cloud e ClickHouse Cloud) se isso não foi feito no dia anterior.
• 5 min — clonar o repositório, criar o ambiente virtual e instalar dependências.
• 5 min — preencher .env.
• 5 min — executar source .env && scripts/arena.sh up e confirmar o dashboard em http://localhost:5174.

Antes da sessão, abra OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention, desative Non-frontier (cinza/desligado) e teste o Qwen com a chave do participante. O Qwen usa o endpoint sem ZDR da Alibaba; ativar ZDR para modelos non-frontier gera No endpoints available matching your guardrail restrictions and data policy mesmo com a Alibaba permitida e guardrails flexíveis. Essa configuração é da conta e não pode ser relaxada pela API de gerenciamento nem por parâmetro. Use-a somente para a carga sintética do workshop e respeite as exigências da sua organização para dados reais.

Roteiro

• Comece nomeando as três contas — OpenRouter, ClickHouse Cloud e Langfuse Cloud — e deixe claro que o Langfuse entra no primeiro módulo, antes da escolha de qualquer modelo. Ele não é um complemento de produção adicionado no Módulo 03: executará a competição e preservará as evidências ao longo do lançamento, investigação e melhoria.
• Aponte o caminho de código compartilhado no diagrama: agents/ é usado por eval/harness.py (benchmark) e serving/api.py (produção), portanto o que é medido hoje é exatamente o que será lançado no Módulo 03.
• Narre o que scripts/arena.sh up faz: cria o banco arena, o usuário somente leitura arena_ro, gera dados sintéticos de e-commerce no ClickHouse, cria as views v_* e inicia a API e a interface web do dashboard.
• Avise que a aba Leaderboard estará vazia ao fim do módulo. Isso é correto e prepara o Módulo 01.

Falhas comuns

• Placeholder OPENROUTER_API_KEY mantido como sk-or-... — o harness falhará com 401 ao chamar um modelo no Módulo 01. Peça que confirmem agora uma chave real em .env.
• ARENA_RO_PASSWORD vazio — scripts/arena.sh up ainda cria arena_ro, mas a política de senhas do serviço pode rejeitar o cliente. Defina qualquer valor não vazio.
• Serviço ClickHouse Cloud ainda provisionando — um serviço novo pode levar alguns minutos para aceitar conexões; espere e execute scripts/arena.sh up novamente.
• .env não carregado — execute source .env && scripts/arena.sh up na mesma linha; scripts/arena.sh up sozinho em um shell novo falha por ausência de CLICKHOUSE_CLOUD_*.
• Porta 5174 (ou 8000) em uso — há um processo antigo. scripts/arena.sh stop limpa os servidores antes de repetir up.

Etapas de recuperação

• Recrie tudo com source .env && scripts/arena.sh up. É idempotente, não usa Aurora, ClickPipes ou ClickStack e recria o banco arena, o usuário arena_ro, os dados sintéticos e as views v_*, depois reinicia a API e a interface. Os resultados do benchmark permanecem no Langfuse.
• Se apenas os servidores locais travaram, scripts/arena.sh stop seguido de scripts/arena.sh serve é mais rápido que um up completo.
• Verifique o estado com scripts/arena.sh status; ele mostra a API, a interface e a contagem de linhas de cada view v_*.
• Se o .env ainda contém placeholders, obtenha a credencial real e execute scripts/arena.sh up novamente.