00 Setup

Pendamping fasilitator untuk pelajaran learner 00 Setup.

Sebelum sesi — siapkan satu key learner bersama (pemakaian yang adil)

Untuk sesi publik yang dipandu instruktur, jangan serahkan key OpenRouter pribadimu atau key tanpa batas ke satu ruangan berisi orang asing. OpenRouter punya Management (provisioning) API yang mencetak key khusus dengan batas kredit keras, secara programatis — sehingga belanja workshop terbatas dan adil.

1. Buat Management key (sekali saja). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. Key ini bisa membuat, memeriksa, dan menghapus key lain serta membelanjakan akunmu — perlakukan sebagai kredensial admin.

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

2. Siapkan key learner bersama dengan batas keras. Repo menyertakan sebuah helper (scripts/provision_workshop_keys.py) yang memanggil 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

Respons pembuatan mencetak string key-nya satu kali — salin dan berikan ke learner sebagai OPENROUTER_API_KEY mereka. Setelah itu hanya hash-nya yang bisa diambil (untuk memeriksa atau menghapus). Lebih suka curl mentah? Panggilan yang sama:

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. Pantau dan bersihkan. Periksa belanjanya di tengah sesi dan hapus key-nya setelah selesai:

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

Ukurannya: roster-nya adalah tier flash-lite yang murah dan grid-nya cuma 6 × 3 = 18 config, jadi batas bersama $20 nyaman mencakup satu ruangan penuh yang menjalankan Arena beberapa kali — batas itu adalah pagar pengaman terhadap loop yang lepas kendali, bukan anggaran yang ketat.

Timing

Total ~25–30 menit kalau akunnya sudah ada; sisakan lebih lama untuk pembuatan akun.

• 5 min — buat tiga akun (OpenRouter, Langfuse Cloud, ClickHouse Cloud) kalau learner belum melakukannya sehari sebelumnya.
• 5 min — clone repo, buat virtualenv, pasang dependensi.
• 5 min — isi .env.
• 5 min — source .env && scripts/arena.sh up, pastikan dashboard terbuka di http://localhost:5174.

Sebelum sesi, buka OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention dan matikan Non-frontier (abu-abu/off), lalu tes Qwen dengan key learner. Qwen mengarah ke endpoint non-ZDR Alibaba, jadi mengaktifkan ZDR non-frontier menghasilkan No endpoints available matching your guardrail restrictions and data policy bahkan ketika Alibaba diizinkan dan guardrail per-key/workspace-nya permisif. Ini pengaturan di level akun dan tidak bisa dilonggarkan lewat Management API atau parameter request. Pakai pengaturan ini hanya untuk beban kerja workshop yang sintetis; tetap ingat persyaratan penanganan data organisasimu untuk data nyata.

Talk track

• Buka dengan menyebut ketiga akun di muka — OpenRouter, ClickHouse Cloud, Langfuse Cloud — dan katakan secara eksplisit bahwa Langfuse salah satunya, di modul pertama, sebelum satu model pun dipilih. Itulah intinya: Langfuse bukan tambahan produksi yang ditempelkan di Modul 04, ia adalah alat yang menjalankan kontes di modul berikutnya.
• Tunjuk diagram arsitekturnya dan sebutkan satu jalur kode bersama: agents/ dipakai oleh eval/harness.py (benchmark) sekaligus serving/api.py (produksi) — jadi tidak ada yang diukur hari ini yang menyimpang dari yang dirilis di Modul 04.
• Narasikan apa yang sebenarnya dilakukan scripts/arena.sh up saat ia berjalan: membuat database arena, membuat user read-only arena_ro, menghasilkan data e-commerce sintetis langsung ke ClickHouse, membangun view v_*, dan menjalankan API dashboard + web UI.
• Bangun ekspektasi bahwa tab Leaderboard akan kosong di akhir modul ini — itu benar, bukan bug, dan itu cliffhanger menuju Modul 01.

Kegagalan yang umum terjadi

• OPENROUTER_API_KEY masih placeholder sk-or-... — harness akan gagal dengan 401 pertama kali ia memanggil model di Modul 01, bukan saat setup itu sendiri. Minta learner memeriksa dua kali bahwa .env sudah punya key sungguhan sekarang, sebelum mahal untuk didebug nanti.
• ARENA_RO_PASSWORD dibiarkan kosong — scripts/arena.sh up tetap akan membuat user arena_ro, tetapi dengan password kosong, yang bisa ditolak client read-only agent tergantung kebijakan password service ClickHouse Cloud. Minta learner menyetel nilai apa pun yang tidak kosong.
• Service ClickHouse Cloud masih provisioning — service yang baru dibuat bisa butuh satu-dua menit untuk menerima koneksi; scripts/arena.sh up akan gagal cepat dengan error koneksi kalau dijalankan terlalu dini. Tunggu saja lalu jalankan ulang.
• .env belum di-source sebelum menjalankan script — source .env && scripts/arena.sh up jadi satu baris karena ada alasannya; menjalankan scripts/arena.sh up sendirian di shell baru gagal karena env var CLICKHOUSE_CLOUD_* tidak ada.
• Port 5174 (atau 8000) sudah dipakai — proses sisa dari run sebelumnya. scripts/arena.sh stop membersihkan server lokal sebelum menjalankan up lagi.

Langkah reset

• Seed ulang dari nol: source .env && scripts/arena.sh up — ia idempoten dan tidak memakai Aurora, ClickPipes, atau ClickStack; ia membuat ulang database arena, user arena_ro, data sintetisnya, dan view v_*, lalu menjalankan ulang API dashboard dan web UI. Hasil benchmark tetap ada di Langfuse.
• Kalau cuma server lokalnya yang macet (bukan ClickHouse), scripts/arena.sh stop diikuti scripts/arena.sh serve lebih cepat daripada up penuh.
• Verifikasi kondisinya kapan saja dengan scripts/arena.sh status — ia melaporkan apakah API dashboard dan web UI hidup, serta mencetak jumlah baris tiap view v_*.
• Kalau .env seorang learner masih berisi nilai placeholder, tidak ada jalan pintas — dapatkan key/kredensial sungguhannya dan jalankan ulang scripts/arena.sh up.