00 セットアップ

受講者レッスン 00 セットアップ のファシリテーター向け手引きです。

セッション前 — 共有の受講者キーを発行する（公平な利用のために）

公開の講師主導セッションでは、初対面の参加者が集まる部屋に自分の個人 OpenRouter キーや上限のない キーを渡さないでください。OpenRouter には Management (provisioning) API があり、厳格なクレジット 上限を持つ用途専用のキーをプログラムから発行できます。ワークショップの支出が有界で公平になります。

1. Management キーを作る（1 回だけ）。 OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key。このキーは他のキーを作成・確認・削除でき、あなたのアカウントで支出できます。 管理者用の認証情報として扱ってください。

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

2. 厳格な上限付きで共有の受講者キーを発行する。 リポジトリにはヘルパー (scripts/provision_workshop_keys.py) が同梱されており、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

作成のレスポンスは キー文字列を 1 度だけ 出力します。コピーして、受講者の OPENROUTER_API_KEY として渡してください。それ以降は hash だけが取得可能です（確認や 削除のため）。生の curl がよいですか。同じ呼び出しです。

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. 監視して片付ける。 セッション途中で支出を確認し、終わったらキーを削除します。

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

規模の目安: ロースターは安価な flash-lite 帯で、グリッドはわずか 6 × 3 = 18 構成なので、 $20 の共有上限で満室の部屋が Arena を数回実行しても余裕で足ります。この上限は 暴走ループへのガードレールであって、きつい予算ではありません。

タイミング

アカウントがすでにある場合、合計で 25〜30 分ほど。アカウント作成が必要ならもっと余裕を見てください。

• 5 min — 受講者が前日に済ませていない場合、3 つのアカウント（OpenRouter、Langfuse Cloud、 ClickHouse Cloud）を作成する。
• 5 min — リポジトリをクローンし、virtualenv を作り、依存関係をインストールする。
• 5 min — .env を埋める。
• 5 min — source .env && scripts/arena.sh up を実行し、http://localhost:5174 で ダッシュボードが読み込まれることを確認する。

セッション前に OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention を開き、Non-frontier をオフ（グレー/オフ）にしてから、受講者キーで Qwen を テストしてください。Qwen は Alibaba の非 ZDR エンドポイントにルーティングされるため、non-frontier の ZDR を有効にすると、Alibaba が許可されキーごと/ワークスペースのガードレールが緩やかでも No endpoints available matching your guardrail restrictions and data policy が出ます。これは アカウントレベルの設定で、Management API やリクエストパラメーターでは緩められません。この設定は 合成のワークショップワークロードにのみ使い、実データについては組織のデータ取り扱い要件を 念頭に置いてください。

トークトラック

• 冒頭で 3 つのアカウントすべての名前を挙げてください — OpenRouter、ClickHouse Cloud、Langfuse Cloud — そして Langfuse がそのひとつであることを、モデルをひとつも選んでいない最初のモジュールで 明示的に述べてください。それが要点です。Langfuse は Module 04 で後付けする本番用のアドオンでは なく、次のモジュールでコンテストを走らせるツールです。
• アーキテクチャ図を指し、共有された 1 つのコードパスを名指ししてください。agents/ は eval/harness.py（ベンチマーク）と serving/api.py（本番）の両方から使われます。だから 今日測るものは Module 04 で出荷されるものから乖離しません。
• scripts/arena.sh up が実行中に実際に何をしているかを語ってください。arena データベースを作り、arena_ro 読み取り専用ユーザーを作り、合成の e-commerce データを ClickHouse に直接生成し、v_* views を構築し、ダッシュボード API と web UI を起動します。
• このモジュールの終わりに Leaderboard タブが空であることを期待値として伝えてください。 それは正しく、バグではなく、Module 01 への引きになります。

よくある失敗

• OPENROUTER_API_KEY がプレースホルダー sk-or-... のまま — ハーネスは Module 01 で 最初にモデルを呼ぶときに 401 で失敗し、セットアップ中には失敗しません。あとでデバッグが 高くつく前に、いま .env に本物のキーが入っているか再確認させてください。
• ARENA_RO_PASSWORD が空のまま — scripts/arena.sh up は arena_ro ユーザーを作りますが、パスワードが空になります。ClickHouse Cloud サービスのパスワードポリシー 次第で、エージェントの読み取り専用クライアントがそれを拒否することがあります。空でない値を 何か設定させてください。
• ClickHouse Cloud サービスがまだプロビジョニング中 — 作りたてのサービスは接続を受け付ける まで 1〜2 分かかることがあります。早すぎると scripts/arena.sh up は接続エラーで即座に 失敗します。待って再実行するだけです。
• スクリプト実行前に .env を source していない — source .env && scripts/arena.sh up が 1 行になっているのには理由があります。新しいシェルで scripts/arena.sh up だけを実行すると、 CLICKHOUSE_CLOUD_* の環境変数がなくて失敗します。
• ポート 5174（または 8000）が使用中 — 前回の実行のプロセスが残っています。 scripts/arena.sh stop でローカルサーバーを片付けてから up を再実行してください。

リセット手順

• ゼロからの再シード: source .env && scripts/arena.sh up — これは冪等で、 Aurora、ClickPipes、ClickStack は使いません。arena データベース、 arena_ro ユーザー、合成データ、v_* views を作り直し、そのあとダッシュボード API と web UI を再起動します。ベンチマーク結果は Langfuse に残ります。
• ローカルサーバーだけが詰まっている場合（ClickHouse ではなく）、scripts/arena.sh stop のあと scripts/arena.sh serve のほうが完全な up より速いです。
• 状態はいつでも scripts/arena.sh status で確認できます。ダッシュボード API と web UI が 起動しているかを報告し、各 v_* view の行数を出力します。
• 受講者の .env にまだプレースホルダーの値が残っている場合、近道はありません。本物の キー/認証情報を用意して scripts/arena.sh up を再実行してください。