liveavatar-feedback

LiveAvatar フィードバックの収集

このスキルは、統合に関するフィードバックを収集し、LiveAvatar チームに送信します。次の 3 つの状況で実行されます。

1. 実装後 — ユーザーが統合（Embed、FULL、または LITE）を完了した直後
2. 不満の検知 — エラーの繰り返し、明確な苦情、または目に見えるつまずきがある
3. 明示的なリクエスト — ユーザーがフィードバックの送信や問題の報告を依頼する

起動するタイミング

次のいずれかに該当する場合、このスキルを起動します。

• ユーザーが作業の完了を伝える、または統合が動作していると言う
• ユーザーが不満を示す（「これは壊れている」「なぜ動かないの」「行き詰まった」など）
• ユーザーがフィードバックの送信、バグの報告、提案の共有を明示的に依頼する
• 統合中に同じ手順で 3 回以上失敗している
• ユーザーが諦める、または統合を中断すると言う

実装を進めている最中に、こちらから不意に起動してはいけません。 自然な区切りや完了のタイミングを待ちます。

ステップ 1：会話からコンテキストを収集する

ユーザーに尋ねる前に、会話履歴を確認し、次の情報を内部でまとめます。

• ユースケース — ユーザーが構築しているもの（例：「SaaS ダッシュボード向けのカスタマーサポートアバター」）。要件の確認段階、ユーザーが述べた目標、またはコードベースから把握します。
• 障害要因 — 統合中につまずきの原因となったもの。発生したエラー、再試行が必要だった手順、分かりにくい API の動作、表面化しない失敗、不足しているドキュメント、またはユーザーが明確に不満を述べた内容を確認します。

両方を、事実に基づく簡潔な要約にまとめます。これらはエージェントが下書きするテレメトリ情報であり、送信前にユーザーが確認します。

ステップ 2：ユーザーに許可と追加のフィードバックを求める

何かを送信する前に、明示的な許可を必ず得てください。 収集した内容を提示し、承認、編集、または辞退を求めます。

状況に合わせて口調を調整します。成功後は祝福し、不満がある場合は共感を示します。

実装に成功した後：

Your LiveAvatar integration is working! The LiveAvatar team collects anonymous integration feedback to improve the developer experience. Would you be okay with me sending a short summary?

Here's what I'd send:
- **Use case:** <your compacted summary>
- **Blockers:** <your compacted summary, or "None">

Want to add anything else in your own words? (Feature requests, suggestions, general thoughts — totally optional.)

**Nothing is sent until you say yes.** You can also edit or remove anything above.

不満を検知した場合：

It looks like this has been a rough integration. The LiveAvatar team actively collects developer feedback to fix exactly these kinds of pain points. Would you be okay with me sending them a summary of what happened?

Here's what I'd send:
- **Use case:** <your compacted summary>
- **Blockers:** <your compacted summary of what went wrong>

Want to add anything in your own words? (No pressure — but this goes directly to the team that can fix it.)

**Nothing is sent until you say yes.** You can edit or remove any of the above.

フィードバックを明示的に依頼された場合：

I can send feedback directly to the LiveAvatar team. Based on our conversation, here's what I've gathered:

- **Use case:** <your compacted summary>
- **Blockers:** <your compacted summary, or "None">

Want to add anything else in your own words?

**Nothing is sent until you give the go-ahead.** Feel free to edit any of the above.

ユーザーが明示的に承認するまで待ちます（例：「はい」「送信して」「問題ありません」「進めてください」）。ユーザーが拒否する、辞退する、またはプロンプトに応答しない場合は、リクエストを送信してはいけません。破棄してください。

ステップ 3：フィールドに割り当てる

フィールド	入力元	入力する内容
use_case	会話からエージェントがまとめた内容	ユーザーが構築しているものの簡潔な要約（例：「SaaS ダッシュボード向けのカスタマーサポートアバター」）
blockers	会話からエージェントがまとめた内容	つまずきの原因となったもの — エラー、再試行、混乱、表面化しない失敗（例：「context_id がないためアバターが無音に。エラーは発生せず、原因の特定に 30 分かかった」）
additional_feedback	ユーザー自身の言葉をそのまま使用	プロンプトに対してユーザーが入力した自由形式の内容 — 機能リクエスト、提案、一般的な意見。ユーザーの言葉をそのまま使用してください。言い換えたり要約したりしないでください。

3 つのフィールドはすべて任意です。該当しないものは省略するか、null を渡します。

• 統合中に不満や問題がなかった場合は、blockers を省略します。
• ユーザーが追加のフィードバックを入力しなかった場合は、additional_feedback を省略します。
• コンテキストからユースケースを特定できなかった場合は、use_case を省略します。

ステップ 4：フィードバックを送信する（明示的な同意を得た後のみ）

このステップは、ユーザーがステップ 2 で明示的に承認した場合にのみ実行します。 ユーザーが辞退した、内容を編集した、または応答しなかった場合は、ここで終了します。

この呼び出しは X-API-KEY を使用してバックエンドで実行されます。

curl -X POST https://api.liveavatar.com/v1/feedback/agents \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback_data": {
      "use_case": "Customer support avatar",
      "blockers": "Latency issues with long responses",
      "additional_feedback": "Would love multi-language support"
    }
  }'

リクエストの作成

• use_case と blockers：ステップ 2 でユーザーに提示した簡潔な要約を使用します（ユーザーから編集の依頼があった場合は、その内容を反映します）。
• additional_feedback：ユーザーが入力した自由形式のテキストをそのまま貼り付けます。言い換えないでください。
• 該当しないフィールドは省略するか、null を渡します。
• ステップ 2 でユーザーが要約を編集した場合は、編集後の内容を使用します。
• ユーザーの API キーが環境（例：HEYGEN_API_KEY または LIVEAVATAR_API_KEY）で利用できる場合は、それを使用します。そうでない場合は、フィードバックの送信に API キーが必要であることをユーザーに伝えます。

ペイロードの例

エージェントが要約したテレメトリのみ（ユーザーから追加のフィードバックなし）：

{
  "feedback_data": {
    "use_case": "Customer support avatar for e-commerce site",
    "blockers": "Silent avatar due to missing context_id — no error thrown, took 30 min to diagnose"
  }
}

ユーザー自身の言葉を含む全ペイロード：

{
  "feedback_data": {
    "use_case": "Real-time sales coach avatar for CRM",
    "blockers": "Custom LLM setup required 3 separate API calls (secret, config, session token) before first test",
    "additional_feedback": "The sandbox is great. Would be nice if sessions lasted longer than 1 min. Also would love multi-language support."
  }
}

Step 5: 送信を確認する

送信後、ユーザーに次のように確認します。

Feedback sent to the LiveAvatar team — thanks for sharing.

簡潔に伝えてください。リクエストに失敗した場合（無効な API キーなど）は、ユーザーに伝え、手動で送信できるよう curl コマンドを表示することを提案してください。

注意事項

1. 同意は必須です。 ユーザーから明示的な「はい」を得る前に、リクエストを送信しないでください。確信が持てない場合は、もう一度確認してください。ユーザーが確認を無視した場合は、送信しないでください。
2. additional_feedback を捏造しないでください。 このフィールドに入れるのは、ユーザー自身の言葉のみです。use_case と blockers はエージェントが要約して構いませんが、additional_feedback はユーザーの入力を一言一句そのまま使うか、完全に省略する必要があります。このフィールドを自分で生成、要約、事前入力してはいけません。ユーザーが何も書いていない場合は、ペイロードから省略してください。
3. 送信前に表示してください。 送信する予定の正確な内容を必ずユーザーに見せ、リクエストを実行する前に編集または削除できるようにしてください。
4. 作業の流れを妨げないでください。 ユーザーが実装の途中なら、フィードバック収集を突然始めないでください。自然な区切りまで待ってください。
5. API キーが必要です。 このエンドポイントでは X-API-KEY を使用します。アクセスできない場合は、何も伝えずに失敗するのではなく、curl コマンドをユーザーに表示してください。
6. すべてのフィールドは任意です。 フィールドが 1 つだけ設定され、残りが省略または null でも、有効なリクエストになります。