00 Configuração

Resultado

Um repositório clonado com um ambiente virtual Python instalado, um .env preenchido com credenciais do OpenRouter, ClickHouse Cloud e Langfuse Cloud, um banco de dados arena no ClickHouse Cloud populado com dados sintéticos de e-commerce e o dashboard local em execução em http://localhost:5174 — a aba Leaderboard estará vazia por enquanto, como esperado até o Módulo 01.

Por quê

O Agent Arena é um núcleo de agente NL→SQL (agents/) reutilizado por dois chamadores — o harness de benchmark (eval/harness.py) e a API de serving ao vivo (serving/api.py) — para que a demonstração e o benchmark compartilhem exatamente o mesmo caminho de código: os mesmos templates de prompt, o mesmo cliente de modelo e a mesma sandbox SQL somente leitura. Por isso, os números do benchmark são indicadores confiáveis do comportamento em produção, e não resultados de um “harness de avaliação” separado que diverge silenciosamente do que realmente é publicado.

Observe que o Langfuse é uma das três contas configuradas já neste primeiro módulo — antes de escolher um modelo ou executar uma única pergunta. Isso é intencional: o Langfuse não é algo acrescentado depois que o chatbot funciona; ele executa a competição do Módulo 01, mede o vencedor offline no Módulo 02, detecta uma lacuna de produção no Módulo 03, apoia a investigação humana no Módulo 04 e comprova e monitora a melhoria no Módulo 05 — um projeto, uma trilha contínua de evidências. Todos os módulos seguintes usam esse mesmo caminho de código e projeto do Langfuse; configurar corretamente as três contas e o banco populado faz o restante do workshop funcionar.

Conceitos — por baixo dos panos

Três pilares, três funções, conectados desde este primeiro módulo:

• OpenRouter — uma API compatível com OpenAI diante de todas as famílias de modelos deste workshop (Anthropic, OpenAI, Google, DeepSeek, Qwen, Z.ai). Em vez de lidar com seis SDKs de provedores e seis conjuntos de credenciais, o núcleo do agente (agents/) usa um cliente para alcançar todos os seis modelos em config.yaml. Isso viabiliza uma competição justa e equivalente no Módulo 01: cada modelo está a uma string model= de distância, atrás do mesmo endpoint e do mesmo formato de requisição.
• ClickHouse — o banco de dados da aplicação. Ele mantém os dados de negócio (as tabelas sintéticas de e-commerce que você vai popular) atrás das views v_*. O agente só pode executar SELECT nas views v_* — nunca nas tabelas brutas e nunca escrever — tanto porque esse é um contrato estável, documentado e somente leitura para o agente interpretar, quanto porque agents/sqlguard.py o impõe como sandbox exclusiva para SELECT: ele analisa o SQL gerado, rejeita qualquer coisa que não seja uma única instrução SELECT/WITH…SELECT e bloqueia uma lista de palavras-chave de escrita/DDL (INSERT, UPDATE, DELETE, DROP, ALTER, SYSTEM, …), mesmo dentro de uma instrução válida.
• Langfuse — o repositório de avaliações, leaderboard e observabilidade. Ele é conectado agora, antes de você escolher um modelo ou fazer uma pergunta, pois não é um complemento posterior: ele avalia a competição no Módulo 01, permite aprofundar a qualidade no Módulo 02, detecta falhas de produção no Módulo 03, conduz a revisão humana no Módulo 04 e valida o tráfego futuro no Módulo 05. Um projeto, uma trilha contínua de traces, feedback, pontuações, anotações e datasets.

Objetivo

Três conjuntos de credenciais no .env, um banco arena populado com as views v_* que o agente consultará e o dashboard local acessível no navegador.

Etapa 1 — Criar três contas

Você precisa das credenciais de API de três serviços antes de abrir o terminal:

Mantenha os três à mão — você os colará no .env em breve.

Configuração de privacidade do OpenRouter exigida para o Qwen

No OpenRouter, abra Settings → Privacy → Data Policies → Zero Data Retention e desative Non-frontier (o botão deve ficar cinza/desligado). O Qwen está no grupo de modelos non-frontier do OpenRouter, e seu endpoint Alibaba disponível não é elegível quando o Zero Data Retention para non-frontier é imposto. Se a opção continuar ativada, qwen/qwen3.7-flash falhará com No endpoints available matching your guardrail restrictions and data policy, mesmo com chave de API e slug do modelo válidos.

Este workshop envia perguntas e esquemas sintéticos de e-commerce. Para cargas reais, revise os requisitos de privacidade da sua organização antes de flexibilizar uma política de ZDR.

Etapa 2 — Clonar o repositório

O Agent Arena fica no monorepo ClickHouse_Demos, em workshops/agent_arena na branch build-workshop-v1. Clone o repositório inteiro e entre nesse subdiretório — todos os comandos daqui em diante pressupõem que você está nele:

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

Etapa 3 — Criar um ambiente virtual e instalar dependências

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

Etapa 4 — Configurar o .env

Copie o arquivo de exemplo:

cp .env.example .env

.env

Preencha os valores da Etapa 1 — todos os valores abaixo estão vazios ou são placeholders no .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-...

Finalidade de cada bloco:

• CLICKHOUSE_CLOUD_* — credenciais administrativas do serviço ClickHouse Cloud. A configuração usa o administrador uma vez para criar o banco arena e um usuário somente leitura dedicado (arena_ro), pelo qual o agente fará consultas durante todo o workshop.
• ARENA_RO_PASSWORD — escolha qualquer senha; ela será a senha de arena_ro quando o usuário somente leitura for criado.
• OPENROUTER_* — a chave do OpenRouter e a URL base. Cada modelo em config.yaml é acessado por esse único endpoint.
• LANGFUSE_* — host e chaves do projeto Langfuse Cloud. É onde ficam todos os traces, pontuações e datasets do workshop, desde a primeira execução da Arena no Módulo 01 até a melhoria monitorada no Módulo 05.

Etapa 5 — Popular o ClickHouse com dados sintéticos de e-commerce

Isso cria o banco arena e o usuário somente leitura arena_ro, gera dados sintéticos de e-commerce (clientes, produtos, pedidos, itens de pedido e eventos) diretamente no ClickHouse e cria as views v_* consultadas pelo agente:

source .env && scripts/arena.sh up

Todos os agentes, prompts e SQLs dourados deste workshop consultam as views v_customers, v_products, v_orders, v_order_items e v_events — nunca as tabelas brutas.

O scripts/arena.sh up também inicia a API do dashboard local e a interface web. Ao terminar, abra http://localhost:5174 — a aba Leaderboard permanecerá vazia até você executar a competição no Módulo 01.

Como é uma execução saudável. O scripts/arena.sh up imprime, nesta ordem:

1. ClickHouse: business database + read-only agent user — são criados o banco arena e o usuário dedicado arena_ro.
2. Seeding ClickHouse directly + views + schema context — uma linha clickhouse: inserted <N> into <table> por tabela (customers, products, orders, order_items, events), seguida de done; depois, são construídos as views v_* e o contexto de esquema lido pelo agente.
3. Starting dashboard API (:8000) + web UI (:5174) — duas linhas [ready]. Se alguma exibir [NOT up], provavelmente a porta já está ocupada; consulte o caminho do log exibido (.run/dashboard-api.log ou .run/web.log).

Você pode verificar tudo novamente com scripts/arena.sh status, que mostra se os servidores estão ativos e a contagem de linhas de cada view v_*.

Como verificar se terminou

• O .env contém valores reais (não placeholders) para CLICKHOUSE_CLOUD_*, OPENROUTER_* e LANGFUSE_*.
• scripts/arena.sh up terminou sem erros.
• http://localhost:5174 abre no navegador e exibe a aba Leaderboard (vazia está correto por enquanto).

Exercício — quebrar e diagnosticar uma conexão

Aprenda de propósito a reconhecer um valor incorreto no .env pela assinatura da falha, enquanto não há riscos:

1. Abra o .env e altere um caractere em ARENA_RO_PASSWORD (ou comente-o temporariamente).
2. Execute novamente source .env && scripts/arena.sh up. As etapas administrativas do ClickHouse ainda devem funcionar (elas usam as credenciais de administrador), mas observe onde o caminho somente leitura — tudo que se conecta como arena_ro — começa a reclamar.
3. Leia atentamente a mensagem de erro: é um erro de autenticação, um erro “user does not exist” ou silêncio seguido de timeout? Anote o que ocorreu.
4. Restaure o ARENA_RO_PASSWORD correto e execute scripts/arena.sh up de novo. Confirme que tudo termina corretamente.

Esse é o mesmo instinto de diagnóstico necessário quando a configuração de um colega “não funciona”: relacionar o texto do erro a qual dos três serviços está mal configurado, em vez de verificar tudo outra vez.

Recapitulação

Você tem um banco ClickHouse populado, credenciais dos três serviços — incluindo o Langfuse, conectado antes da escolha de qualquer modelo — e o dashboard local em execução. Tudo depois deste módulo reutiliza o mesmo ambiente e projeto do Langfuse; não há outras etapas de configuração.

Estado final

Ambiente pronto. Continue para 01 Selecionar o modelo base e execute a competição com estes dados.