クライアントからサーバーへのイベント

クライアントからサーバーへのイベントは、会話中に追加のコンテキストを提供するために、アプリケーションからサーバーへプロアクティブに送信するメッセージです。これらのイベントにより、会話の流れを中断せずに関連情報を追加できます。

概要

会話中の任意のタイミングで、会話の品質と関連性を高めるコンテキスト情報をサーバーに送信できます。これは、サーバーから受信したクライアントイベントへの応答である必要はありません。音声では直接伝えられないUIの状態、ユーザー操作、その他の環境データを共有する際に特に便利です。

イベントタイプ

コンテキスト更新

コンテキスト更新では、会話を中断しないバックグラウンド情報を送信できます。

主な特徴：

• 更新内容は会話のバックグラウンド情報として取り込まれます。
• 現在の会話フローを中断しません。
• UIの状態、ユーザー操作、環境データの送信に役立ちます。

// Contextual update event structure
{
  "type": "contextual_update",
  "text": "User appears to be looking at pricing page"
}

// Example sending contextual updates
function sendContextUpdate(information) {
  websocket.send(
    JSON.stringify({
      type: "contextual_update",
      text: information,
    })
  );
}
// Usage examples
sendContextUpdate("Customer status: Premium tier");
sendContextUpdate("User navigated to Help section");
sendContextUpdate("Shopping cart contains 3 items");

ユーザーメッセージ

ユーザーメッセージでは、ユーザーが話したかのようにテキストを直接会話に送信できます。テキストベースのやり取りや、特定のテキストを会話フローに挿入したい場合に便利です。

主な特徴：

• テキストは会話へのユーザー入力として処理されます。
• 音声によるユーザー入力と同じ応答フローをトリガーします。
• テキストベースのインターフェースや、プログラムによるユーザー入力に役立ちます。

// User message event structure
{
  "type": "user_message",
  "text": "I would like to upgrade my account"
}

// Example sending user messages
function sendUserMessage(text) {
  websocket.send(
    JSON.stringify({
      type: "user_message",
      text: text,
    })
  );
}
// Usage examples
sendUserMessage("I need help with billing");
sendUserMessage("What are your pricing options?");
sendUserMessage("Cancel my subscription");

ユーザーアクティビティ

ユーザーアクティビティイベントは、エージェントによる割り込みを防ぐための指標として機能します。

主な特徴：

• ターンタイムアウトタイマーをリセットします。
• 会話の内容やフローには影響しません。
• 無音状態が続く間も長時間の会話を維持するのに役立ちます。

// User activity event structure
{
  "type": "user_activity"
}

// Example sending user activity
function sendUserActivity() {
  websocket.send(
    JSON.stringify({
      type: "user_activity",
    })
  );
}
// Usage example - send activity ping every 30 seconds
setInterval(sendUserActivity, 30000);

ベストプラクティス

1. コンテキスト更新

   • 関連性があり、簡潔なコンテキスト情報を送信する。
   • 更新を送りすぎてLLMに過度な負荷をかけないようにする。
   • 会話フローに影響する情報、または音声エージェントがアクセスできないUI内のアクティビティから得られる重要なコンテキストに焦点を当てる。

2. ユーザーメッセージ

   • オーディオが利用できない、または適切でない場合のテキストベースのユーザー入力に使用する。
   • テキストの内容が明確で適切に整形されていることを確認する。
   • プログラムによるメッセージを挿入する際は、会話のコンテキストを考慮する。

3. ユーザーアクティビティ

   • セッションを維持するため、ユーザー操作中にアクティビティpingを送信する。
   • 不要なネットワークトラフィックを避けるため、適切な間隔（例：30～60秒）を使用する。
   • 実際のユーザーエンゲージメント（マウス操作、入力など）に基づいてアクティビティ検出を実装する。

4. タイミングに関する考慮事項

   • 適切なタイミングで更新を送信する。
   • 複数のコンテキスト更新を1つの更新にまとめることを検討する（小さな変更ごとに個別に送信するのではなく）。
   • セッションの維持と過剰なメッセージ送信の回避のバランスを取る。