liveavatar-demo

LiveAvatar デモ

厳選した4つのデモです。それぞれ実際のオープンソースリポジトリです。このスキルでは、クローン、インストール、プロビジョニング、設定、起動まで、機械的な手順をすべて実行します。

このスキルではできないこと — 最初に伝えてください

アバターが話すことを確認することはできません。 どのデモも、マイクと人間の耳が必要なところで終わります。目で確認できない成功を主張したり、手が届かないものを待って進行を止めたりしないでください。次のタイミングになったら、その旨を伝えてください。

タイミング	人間にしかできない理由
API キーの入力	取得も推測もできません
デモ 1：npm run setup のプロンプト	対話型の readline です。参考資料を確認してください。誤った方法で実行すると、ユーザーのアカウントにコンテキストが残ります
デモ 1：名前と仕事用メールアドレスを入力し、Chat with Wayne をクリック	両方を入力するまで送信ボタンは無効です
デモ 2／3：ブラウザーのマイク使用を許可してから話す	マイクがなければ会話できません
デモ 4：Start をクリックし、マイクを許可して「ready」と答える	アバターは、何かを始める前に音声での「はい」を待ちます
アバターが話し、リップシンクすることの確認	人間のブラウザーでの音声と動画が必要です
Vercel へのログイン／デプロイ（デモ 1、Full レベルのみ）	対話型の認証が必要です

それ以外はすべてあなたが実行してください。コマンドを一つずつ説明せずに進めてください。

ステップ 1：LiveAvatar API キーを取得する — 何よりも先に

4つのデモすべてで必要です。早めに用意しておくと、分岐の大半を省けます。最初のメッセージで、カタログと一緒に今すぐ尋ねてください。

https://app.liveavatar.com/developers から API キーを取得して、ここに貼り付けてください。あとは私が進めます。

キーなしでステップ 3 を超えて進めないでください。 待っている間にクローンとインストールを済ませてもかまいません。そうすれば、ユーザーがキーを貼り付けるだけでデモを実行できます。その作業を進めることを伝えてください。

環境ファイルにプレースホルダーや偽の値を絶対に書き込まないでください。セットアップスクリプトとエントリーポイントは、ファイル内の値をすべて正規の値として扱います。偽のキーを使うと、アカウントの問題に見える 401 エラーが発生します。

ステップ 2：デモを選ぶ

ユーザーがすでにデモを指定している場合を除き、この表を表示してください。

#	デモ	内容	スタック	追加で必要なキー
1	AI Sales Agent	アバターが見込み客を選別し、通話終了時に Notion と Slack に要約を書き込みます	Next.js 15 / TypeScript、Node 22+	ローカル実行では不要。完全な営業機能には Anthropic と公開 URL が必要です
2	LiveKit Agent (LiveAvatar-hosted room)	独自の LiveKit STT→LLM→TTS パイプラインでアバターを動かします。ルームは LiveAvatar が管理します	Python 3.10+ / LiveKit Agents	LiveKit Cloud のキーとシークレット
3	BYO LiveKit Agent	同じパイプラインを使用し、アバターはあなたの LiveKit プロジェクトのルームに参加します。本番環境を想定した構成です	Python 3.10+ / LiveKit Agents	LiveKit Cloud のキー、シークレット、URL、livekit-cli
4	GPT-Live × Hyperframes × LiveAvatar	全二重の音声対音声 GPT-Live でアバターを動かし、ツール呼び出しをアニメーション付きの Hyperframes オーバーレイとして表示します。この構成を正確に実現する複数のブランチ（語学講師、サポートエージェント、ポーカーコーチ）がある1つのリポジトリです。エージェントが一度で作り、その後別の用途に転用できるように構築されています	Node 20.12+ / pnpm / TypeScript	GPT-Live にアクセスできる OpenAI キー

案内の目安：最速で話すデモを試したい場合 → 1。音声パイプラインを見たい場合、または LiveKit Cloud を利用している場合 → 2。本番環境で LiveKit ルームをすでに運用している場合 → 3。音声対音声、GPT-Live、アバターに同期した映像を試したい場合や、独自のデモに作り替える出発点が必要な場合 → 4。参考資料から最も近いブランチを選んでください。ユーザーが特定の GPT-Live モデルにアクセスできることの確認を条件に、デモ 4 の利用を制限しないでください。リポジトリの .env.example は現在のリリースに対応しています。「とにかく何でも見せて」→ 1。

デモ 2 と 3 は同じリポジトリで、エントリーポイントが2つあります。両方を希望する場合は、クローンは1回だけでかまいません。

コスト — 起動前に一度だけ伝えてください

• LiveAvatar のサンドボックスセッションは無料で、時間はおよそ1分に制限されています。デモ2と3はデフォルトでサンドボックスを使用し、デモ1は共有の公開デモアバターを使用します。
• デモ4にはサンドボックスがありません — セッション開始時点から LiveAvatar の本番利用料金が発生し、上限はアカウントのデフォルトのセッション制限のみです。リポジトリでは独自の上限を設定していません。また、ターンごとに OpenAI GPT-Live の音声トークン料金が発生します。
• デモ2と3では、デモ2のように LiveAvatar がルームを所有する場合も含め、ユーザーの LiveKit Cloud プロジェクトに STT／LLM／TTS の料金が発生します。 ルームの所有者と推論の課金は別々です。そうでないと思い込む人がいます。デモ3では RTC 分の料金も発生します。
• デモ1では、ブレインを接続した後に限り、ターンごとに Anthropic のトークン料金が発生します。

ステップ3：事前確認

選択したデモに必要なチェックだけを実行してください。不足しているものがあれば、インストールコマンドとともに伝えてください。許可を得ずにランタイムをインストールしないでください。

デモ1：

node --version                 # need >= 22 (engines.node enforces it)
git --version
lsof -ti tcp:3003              # MUST be empty — see below

ポート3003はdevとstartの両方で固定されています。ポートが使用中の場合は致命的な問題であり、警告ではありません。また、自動で別のポートに切り替わることもありません。lsofがPIDを返した場合は、そのプロセスを終了するか、npmを介さずにnpx next dev --port <free>で起動する計画を立ててください。その場合、引き継ぎ先のURLも変わることを忘れないでください。

デモ2と3：

git --version
uv --version                   # install: brew install uv

python3 --versionを条件にしないでください。 uv venvはpyproject.tomlのrequires-pythonを読み取り、互換性のあるインタープリターを自ら選択します。システムのPython 3.9は関係ありません。これを確認すると誤検知が発生し、本来は成功するセットアップを中断してしまいます。uvが本当に利用できない場合は、python3.13 -m venv .venv && .venv/bin/pip install -e .に切り替え、そうしたことを伝えてください。

デモ3ではlkも必要です。brew install livekit-cliを実行してください（解決できない場合は、先にtap livekit/livekitを追加します）。その後、lk cloud authを実行します。これは対話型なので、ユーザーに操作を引き継いでください。

デモ4：

node --version                 # need >= 20.12
pnpm --version                 # install: corepack enable, or brew install pnpm
git --version

ポート8787（サーバー）と5173（Vite）のうち、重要なのは8787だけです。Viteは自動でポートを移動しますが、サーバーは移動しません。リファレンスにポートの変更方法が記載されています。

ステップ4：残りの認証情報

デモを選んだ後、これらを1通のメッセージで尋ねてください。必要なものはデモによって異なるため、選択前には尋ねないでください。

デモ	追加で必要なもの	入手先
1、ローカル実行	なし	—
1、完全なセールスブレイン	ANTHROPIC_API_KEY	https://console.anthropic.com
2	LIVEKIT_API_KEY、LIVEKIT_API_SECRET	https://cloud.livekit.io → project → Settings → Keys
3	上記2つに加えてLIVEKIT_URL（wss://….livekit.cloud）	同じページ
4	GPT-LiveにアクセスできるOPENAI_API_KEY	https://platform.openai.com — GPT_LIVE_MODEL（および alpha ヘッダー）は.env.exampleに動作するデフォルト値が設定されています。そのままにし、モデルIDをユーザーに尋ねたり、確認を求めたりしないでください

デモ1では、尋ねる前にリファレンスの「ローカル版と完全版」のセクションを読み、どちらにするか決めてください。ローカル実行では使わない Anthropic キーを求めると、LiveAvatar キーしか持っていないユーザーの妨げになります。

アバターIDは尋ねないでください。 すべてのリポジトリで.env.exampleに動作するデフォルト値が設定されています。そのままにしてください。

任意で、デモ1のみの項目です。ユーザーから話題に出ない限り省略してください：NOTION_TOKEN + NOTION_DATABASE_ID、SLACK_WEBHOOK_URL。

クローン先

デフォルトでは、現在のディレクトリから見て../liveavatar-demos/<repo-name>を使います（デモ4では、すべてのブランチでリポジトリ名が共通のため<repo-name>-<branch>）。git cloneを実行する前にパスを確認してください。ユーザーのプロジェクトツリー内にはクローンしないでください。現在の作業ディレクトリがユーザーのプロジェクト内にある場合は、親ディレクトリへ移動してください。対象のディレクトリが存在し、空でない場合は中止してユーザーに確認してください。

ステップ 5：セットアップして実行する

まずクローンし、何かを実行する前にリポジトリ独自のエージェント向けドキュメントを読む：AGENTS.md、次に CLAUDE.md、続いて docs/ と README のトラブルシューティングセクションを読みます。存在するものはすべて対象です。リポジトリのドキュメントはこのスキルより新しく、コマンドやファイル構成についてはそちらを優先します。以下のリファレンスは、アカウントレベルの注意点、請求、ルーティングなど、リポジトリ側では把握できない情報を補います。内容が食い違う場合はリポジトリに従い、その差異を記録してください。

デモ	リファレンス	リポジトリ独自のエージェント向けドキュメント
1 — AI Sales Agent	references/sales-agent.md	README + docs/PROVISIONING.md（AGENTS.md はありません。セットアップの詳細はリファレンスに記載されています）
2 — LiveKit hosted room	references/livekit-agent.md	CLAUDE.md（コードマップ）+ docs/liveavatar-hosted-demo.md
3 — BYO LiveKit	references/livekit-agent.md（BYO セクション）	CLAUDE.md + docs/byo-livekit-demo.md
4 — GPT-Live × Hyperframes	references/gpt-live-demos.md（ブランチ一覧）	AGENTS.md、README.md、および docs/ 内のすべてのファイルを読みます。エージェント向けに書かれたもので、セットアップと反復作業に関する信頼できる情報源です

すべてのデモに適用されるルール：

シークレットはリポジトリで指定された環境ファイルに保存し、コミットされるファイルには絶対に保存しないでください。 デモ 1〜3 では .env.local、デモ 4 ではリポジトリルートの .env を使います（ここでは Git の追跡対象外です）。どちらの形式にも .env.example が用意されています。

キーの書き込みにはシェルコマンドではなく、エディターツールを使ってください。 シェルの履歴やログは残ります。例外は、環境変数からキーを読み取るセットアップスクリプトです。その場合についてはリファレンスに記載されています。

.env.example をコピーするだけでは不十分です。 これらのファイルには値が空のキーが含まれており、未設定の場合と同じではありません。該当するキーはリファレンスに記載されています。ここを誤ることが、これらのデモが動かなくなる最もよくある原因です。

venv を有効化しないでください。 source .venv/bin/activate はツール呼び出しの間で維持されません。毎回 uv run <command> を使ってください。

長時間実行するプロセスはバックグラウンドで起動し、フォアグラウンドで待ち続けずにログを読み取ってください。 対話型のセットアップスクリプトは例外です。リファレンスを参照してください。

実際に確認できた準備完了シグナルを報告したら、そこで止めてください。 各リファレンスにシグナルが記載されています。準備完了シグナルが示すのは、あくまで プロセス が起動したことだけで、アバターが動作することを示すものではありません。そこから先を推測しないでください。

ステップ 6：引き継ぐ

次の内容をそのまま伝え、そこで止めてください。

1. ユーザーが今すべきことを具体的に伝えます。デモ 1：http://localhost:3003 を開き、名前と勤務先のメールアドレスを入力して、Chat with Wayne をクリックします。デモ 2／3：ブラウザータブが自動で開いています。マイクを許可してから話します。デモ 4：http://localhost:5173 を開き、Start をクリックしてマイクを許可し、尋ねられたら「ready」と言います。
2. 確認できなかったことを伝えます。アバターの表示、発話、リップシンク（デモ 4 では、オーバーレイが適切な位置に表示されることも）は確認できていません。ユーザーに確認を求めます。
3. カスタマイズ方法を 1 つ案内します。 デモ 1：src/lib/ai-sales/brain/prompt-parts/ にあるプロンプトの構成要素。デモ 2／3：src/agent.py の instructions=。デモ 4：server/prompts/*.md にあるペルソナ。さらにカスタマイズを進める場合は申し出てください。リポジトリの docs/ では、ビジュアルの追加やドメイン全体の再利用について説明しており、その作業も対応できます。
4. 停止方法と請求について説明します。ローカル開発サーバーは無料です。課金対象はアバターセッションで、ブラウザータブを閉じるかプロセスが終了するとセッションも終了します。該当する終了条件を伝え、デモ 4 ではセッションがサンドボックス料金ではなく本番料金で請求されることも伝えてください。

コードベース全体の案内は不要です。必要になればユーザーから尋ねられます。

問題が発生した場合

各リファレンスには、具体的な失敗例をまとめた注意事項のセクションがあります。また、実際のエージェント用ドキュメントを含むデモリポジトリでは、トラブルシューティングが記載されています。両方を確認してください。一般的な切り分け方法は次のとおりです。

1. ネットワークへの接続前にクラッシュする → 空の値が設定されている環境変数です。まず LOG_LEVEL（デモ 2／3）を確認してください。最もよくある原因で、トレースバックにも関連する情報が出てきません。
2. アバターは接続するが、無音になる → 問題は映像側ではなく音声側です。デモ 1：コンテキスト（opening_text）がないか、到達不能な URL を指す LLM 設定になっています。エラーは表示されず、サイレントに失敗します。デモ 4：GPT-Live 側の認証に失敗しています。GPT_LIVE_DEBUG=1 で理由を確認できます。リファレンスには変更してはいけない項目が記載されています。
3. ユーザーの最初の発話でクラッシュする（デモ 2／3） → モデルの重みがダウンロードされていません。
4. セッション発行時に 401 が発生する → LIVEAVATAR_API_KEY が正しくないか、設定されていません。このエラーは明確で、リクエストボディも表示されるので、その内容を信頼してください。
5. セッション発行時にセッションが拒否される → max_session_duration がアカウントのプラン上限を超えているか、本番用アバター ID をサンドボックスモードで使用しています。
6. ブラウザーに何も表示されない → サーバーログより先に、ブラウザーのコンソールを確認してください。通常はマイクの権限が原因です。

リファレンスの表に症状が載っていない場合は、README ではなくログをもとにデバッグしてください。

ステップ 7：フィードバックを集める

デモの引き継ぎが完了した時点で実施します。または、ユーザーが同じ手順で 3 回以上失敗した後に中断した場合も実施してください。認証情報がなく何も動作していない場合は、省略してください。

liveavatar-feedback スキルが利用可能な場合は、それに従ってください。利用できない場合は、フィードバックを集める方法を独自に考えず、そのまま省略してください。一言だけ伝え、ユーザーが反応しなくても催促しないでください。

参照先

• references/sales-agent.md — AI Sales Agent：対話型セットアップスクリプト、ローカル環境とデプロイ環境の違い、Vercel、環境変数リファレンス
• references/livekit-agent.md — LiveKit の 2 つのデモ：共通セットアップ、ホスト型フロー、BYO フロー、ワーカーのデプロイ
• references/gpt-live-demos.md — GPT-Live × Hyperframes：存在するブランチ、確認すべきリポジトリのドキュメント、安全なエージェント用セットアップ、本番環境の課金、イテレーションの各ティア