00 Setup

Hasil

Repo hasil clone dengan virtualenv Python terpasang, .env yang sudah diisi kredensial OpenRouter, ClickHouse Cloud, dan Langfuse Cloud, database arena di ClickHouse Cloud yang ter-seed dengan data e-commerce sintetis, serta dashboard lokal berjalan di http://localhost:5174 — tab Leaderboard masih kosong untuk sekarang, itu memang normal sampai Modul 01.

Mengapa

Agent Arena adalah satu agent core NL→SQL (agents/) yang dipakai ulang oleh dua pemanggil — harness benchmark (eval/harness.py) dan API serving live (serving/api.py) — sehingga demo dan benchmark berbagi jalur kode yang sama persis: template prompt yang sama, model client yang sama, sandbox SQL read-only yang sama. Itulah yang membuat angka benchmark menjadi prediktor perilaku produksi yang bisa dipercaya, bukan sebuah "eval harness" terpisah yang diam-diam menyimpang dari apa yang benar-benar dirilis.

Perhatikan bahwa Langfuse adalah salah satu dari tiga akun yang kamu siapkan di modul pertama ini — sebelum kamu memilih model, sebelum kamu menjalankan satu pertanyaan pun. Itu disengaja: Langfuse bukan sesuatu yang kamu tempelkan setelah chatbot-nya jalan, Langfuse adalah alat yang menjalankan kontes di Modul 01, mengukur kualitas pemenang di Modul 02, menggerakkan loop peningkatan di Modul 03, dan mengawasi produksi di Modul 04 — satu project, satu kumpulan traces dan datasets, dari awal sampai akhir. Setiap modul setelah ini dibangun di atas satu jalur kode itu dan satu project Langfuse itu, jadi membuat tiga akun dan database yang ter-seed benar di sini adalah yang membuat sisa workshop berjalan mulus.

Konsep — di balik layar

Tiga pilar, tiga tugas, dirangkai bersama sejak modul pertama ini:

• OpenRouter — satu API yang OpenAI-compatible di depan setiap keluarga model di workshop ini (Anthropic, OpenAI, Google, DeepSeek, Qwen, Z.ai). Ketimbang menjuggle enam SDK provider dan enam set kredensial, agent core (agents/) memakai satu client untuk menjangkau keenam model di config.yaml. Itulah yang membuat kontes yang adil dan apple-to-apple di Modul 01 mungkin: setiap model hanya berjarak satu string model=, di belakang endpoint yang sama, bentuk request yang sama.
• ClickHouse — database aplikasi. Di sinilah data bisnis tersimpan (tabel e-commerce sintetis yang akan kamu seed) di belakang view v_*. Agent hanya pernah diizinkan melakukan SELECT dari view v_* — tidak pernah tabel mentah, tidak pernah menulis — baik karena itu adalah kontrak read-only yang stabil dan terdokumentasi untuk dipikirkan agent, maupun karena agents/sqlguard.py memaksakannya sebagai sandbox SELECT-only: ia mem-parse SQL yang dihasilkan dan menolak apa pun yang bukan satu statement SELECT/WITH…SELECT, serta memblokir denylist keyword write/DDL (INSERT, UPDATE, DELETE, DROP, ALTER, SYSTEM, …) bahkan di dalam statement yang selain itu valid.
• Langfuse — penyimpanan eval, leaderboard, dan observability. Ia terhubung sekarang, sebelum kamu memilih model atau mengajukan satu pertanyaan pun, karena ia bukan tempelan untuk nanti — ia adalah alat yang menilai kontes di Modul 01, memungkinkan kamu menelusuri kualitas di Modul 02, dan mengawasi produksi di Modul 04. Satu project, satu jejak traces dan datasets yang berkelanjutan, sejak pemilihan model pertama dan seterusnya.

Tujuan

Tiga set kredensial di .env, database arena yang ter-seed dengan view v_* yang akan di-query agent, dan dashboard lokal yang bisa dibuka di browser.

Langkah 1 — Buat tiga akun

Kamu butuh kredensial API dari tiga layanan sebelum menyentuh terminal:

Simpan ketiganya dalam jangkauan — sebentar lagi kamu tempel ke .env.

Pengaturan privasi OpenRouter yang wajib untuk Qwen

Di OpenRouter, buka Settings → Privacy → Data Policies → Zero Data Retention lalu matikan Non-frontier (toggle-nya harus abu-abu/off). Qwen ada di grup model non-frontier OpenRouter, dan endpoint Alibaba yang tersedia untuknya tidak memenuhi syarat ketika Zero Data Retention non-frontier dipaksakan. Kalau ini tetap aktif, qwen/qwen3.7-flash gagal dengan No endpoints available matching your guardrail restrictions and data policy bahkan ketika API key dan slug model-nya valid.

Workshop ini mengirim pertanyaan dan skema e-commerce sintetis. Untuk beban kerja nyata, tinjau persyaratan privasi organisasimu sebelum melonggarkan kebijakan ZDR.

Langkah 2 — Clone repo

Agent Arena berada di dalam monorepo ClickHouse_Demos, di bawah workshops/agent_arena pada branch build-workshop-v1. Clone seluruh repo, lalu masuk ke subdirektori itu — setiap perintah mulai dari sini mengasumsikan kamu sedang berada di dalamnya:

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

Langkah 3 — Buat virtualenv dan pasang dependensi

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

Langkah 4 — Konfigurasi .env

Salin file contohnya:

cp .env.example .env

.env

Isi nilainya dari Langkah 1 — setiap nilai di bawah ini kosong atau berupa placeholder di .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-...

Kegunaan tiap blok:

• CLICKHOUSE_CLOUD_* — kredensial admin service ClickHouse Cloud kamu. Setup memakai admin user sekali saja, untuk membuat database arena dan satu user read-only khusus (arena_ro) yang dipakai agent untuk query selama sisa workshop.
• ARENA_RO_PASSWORD — pilih password apa saja; nilainya menjadi password arena_ro saat user read-only itu dibuat.
• OPENROUTER_* — key OpenRouter kamu dan base URL-nya. Setiap model di config.yaml dialamatkan lewat satu endpoint ini.
• LANGFUSE_* — host dan key project Langfuse Cloud kamu. Di sinilah setiap trace, score, dan dataset di workshop ini tersimpan, dari run Arena pertama di Modul 01 hingga produksi di Modul 04.

Langkah 5 — Seed ClickHouse dengan data e-commerce sintetis

Ini membuat database arena, user read-only arena_ro, menghasilkan data e-commerce sintetis (customers, products, orders, order items, events) langsung ke dalam ClickHouse, dan membangun view v_* yang di-query agent:

source .env && scripts/arena.sh up

Setiap agent, prompt, dan potongan golden SQL di workshop ini melakukan query ke view v_customers, v_products, v_orders, v_order_items, dan v_events — tidak pernah ke tabel mentah.

scripts/arena.sh up juga menjalankan API dashboard dan web UI lokal. Setelah selesai, buka http://localhost:5174 — tab Leaderboard akan kosong sampai kamu menjalankan kontesnya di Modul 01.

Seperti apa run yang sehat. scripts/arena.sh up mencetak, berurutan:

1. ClickHouse: business database + read-only agent user — database arena dan user khusus arena_ro dibuat.
2. Seeding ClickHouse directly + views + schema context — satu baris clickhouse: inserted <N> into <table> per tabel (customers, products, orders, order_items, events), lalu done, lalu view v_* dan schema context yang dibaca agent dibangun.
3. Starting dashboard API (:8000) + web UI (:5174) — dua baris [ready]. Kalau salah satu berkata [NOT up], port-nya kemungkinan sudah dipakai; cek path log yang dicetak (.run/dashboard-api.log atau .run/web.log).

Kamu bisa memeriksa ulang semua ini nanti dengan scripts/arena.sh status, yang mencetak apakah server hidup dan jumlah baris tiap view v_*.

Cara memastikan kamu sudah selesai

• .env berisi nilai sungguhan (bukan placeholder) untuk CLICKHOUSE_CLOUD_*, OPENROUTER_*, dan LANGFUSE_*.
• scripts/arena.sh up selesai tanpa error.
• http://localhost:5174 terbuka di browser, memperlihatkan tab Leaderboard (kosong itu benar untuk sekarang).

Latihan — rusakkan lalu diagnosa sebuah koneksi

Belajar mengenali nilai .env yang rusak dari tanda kegagalannya, dengan sengaja, saat risikonya nol:

1. Buka .env dan ubah satu karakter di ARENA_RO_PASSWORD (atau jadikan komentar sementara).
2. Jalankan ulang source .env && scripts/arena.sh up. Seharusnya ia masih melewati langkah admin ClickHouse (itu memakai kredensial admin), tetapi perhatikan di mana jalur read-only — apa pun yang terhubung sebagai arena_ro — mulai mengeluh.
3. Baca pesan error-nya dengan teliti: apakah itu error otentikasi, error "user does not exist", atau sunyi lalu timeout? Catat mana yang kamu dapat.
4. Kembalikan ARENA_RO_PASSWORD yang benar dan jalankan ulang scripts/arena.sh up. Pastikan ia selesai bersih lagi.

Ini insting diagnostik yang sama yang akan kamu butuhkan nanti ketika setup rekan tim "tidak jalan" — mencocokkan teks error dengan layanan mana di antara ketiganya yang salah konfigurasi, ketimbang memeriksa ulang semuanya.

Penutup

Kamu punya database ClickHouse yang ter-seed, kredensial untuk ketiga layanan — termasuk Langfuse, terhubung sebelum model apa pun dipilih — dan dashboard lokal berjalan. Semua hal setelah modul ini memakai ulang environment yang sama dan project Langfuse yang sama; tidak ada langkah setup lagi.

Kondisi akhir

Environment siap. Lanjut ke 01 Pilih model dasar untuk menjalankan kontes terhadap data ini.