会話型コマース エージェント デベロッパー ガイド

このガイドでは、Conversational API と統合して、顧客に動的な AI 搭載のチャット エクスペリエンスを提供する方法について詳しく説明します。さまざまなクエリタイプを理解し、API のレスポンスを活用することで、関連性の高い商品検索を提供したり、お客様の問い合わせに回答したり、エンドユーザーのショッピング ジャーニーをガイドしたりできます。

Conversational API の conversationalFilteringMode により、会話型コマース エージェントと会話型の商品フィルタリングの違いが明確になります。

設定

Conversational API は、会話型コマース エージェント機能をサポートしています。

Conversational API を使用すると、ユーザーがクエリを送信し、システムがテキスト レスポンス、分類されたクエリタイプ、絞り込み検索の候補を返すチャット エクスペリエンスを実現できます。

この API はストリーミング サービスとして動作し、クエリの意図を早期に検出できます。会話のその後のやり取りでは、conversation_id を添付する必要があります。

検索結果を返すには、従来の Retail API を Conversational API と並行して呼び出す必要があります。

エンドユーザーからクエリを送信する

このセクションでは、会話型コマース エージェント エクスペリエンスを開始する方法について説明します。たとえば、ユーザーが検索フィールドに「パーティーの計画を手伝って」と入力します。

Vertex AI Search for Commerce にリクエストを送信する

API エンドポイントは 2 つあります。

  1. 会話機能を取得するには、会話 API を使用する必要があります。
  2. 検索結果を取得するには、コアの Search API を使用する必要があります。

エンドポイント 1: Conversational API リクエスト

  • ユーザーの入力を query として設定して、会話型コマース エージェント リクエストを作成する必要があります。
  • リクエストは、projects/*/locations/*/catalogs/*/placements/*:conversationalSearch エンドポイントへの HTTP POST リクエストとして送信する必要があります。

HTTP メソッドとエンドポイント

  POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

会話型 API リクエスト:

最初のクエリ

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}
  • placement: プレースメントのリソース名（projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch など）。これはパス パラメータであり、必須です。
  • query: ユーザーが入力した未加工の検索語句。これは必須です。
  • branch: ブランチ リソース名（projects/P/locations/L/catalogs/C/branches/B など）。設定されていない場合は、default_branch が使用されます。これは必須です。
  • visitorId: 訪問者をトラッキングするための固有識別子。これは必須です。
  • conversationId: 会話セッションをトラッキングするための固有 ID。新しい会話の最初のリクエストの場合、このフィールドは空にする必要があります。同じ会話内の後続のリクエストでは、前の ConversationalSearchResponse で受け取った conversation_id に設定する必要があります。
  • searchParams:（省略可）標準のコア検索パラメータ（例: filter、canonicalFilter、sortBy、boostSpec）。これらのパラメータは、コア検索 API 呼び出しで使用される構成を反映することが重要です。これにより、LLM の回答と表示される商品検索結果との一貫性が確保されます。
  • userInfo:（省略可）パーソナライズの強化に使用するユーザー情報。userId、user_agent、direct_user_request（ブール値）を含めることができます。
  • conversationalFilteringSpec:（省略可）会話フィルタリング モードを指定します。設定しない場合、デフォルトは DISABLED になります。

    mode: 次の 3 つのモードのいずれかを使用して Conversational API を統合し、会話型の商品フィルタリングを制御します。

    • DISABLED: このモードでは、クライアントは会話コマース エージェント検索のみを実装します。これは、会話型コマース エージェント検索に関するこの実装ガイドで推奨されるモードです。

      • API リクエストのサンプル

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }

      API レスポンスのサンプル

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED: このモードでは、クライアントはすべての会話機能を実装します。これには、会話型コマース エージェントの検索や会話型の商品フィルタリングが含まれます。

      • API リクエストのサンプル

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }

      API レスポンスのサンプル

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
    • CONVERSATIONAL_FILTER_ONLY: 選択した場合、クライアントは会話型の商品フィルタリングのみを実装します。このモードを選択すると、ユーザーは LLM の回答、クエリ分類、検索候補の生成なしで、会話型の商品フィルタリングのみを利用できます。

      • 詳しくは、会話型プロダクト フィルタのデベロッパー ガイドをご覧ください。会話型プロダクトを統合する方法については、追加のガイドを参照してください。

エンドポイント 2: Core Search API リクエスト

UI に検索結果を表示するには、主に次の 2 つの方法があります。

  • オプション 1: 検索結果を常に表示する

    ユーザー エクスペリエンスの設計で、会話の出力に関係なく検索結果を常に表示する必要がある（チャットの横の専用検索結果エリアなど）と規定されている場合は、会話 API の呼び出しとともに、ユーザーの元のクエリをコア Product Search API に送信します。これにより、商品リスティングをすぐに利用できるようになります。

  • 方法 2: 会話の出力に基づいて検索結果を表示する

ユーザー エクスペリエンスのデザインがより動的で、Conversational API のレスポンスに応じて検索結果のみを表示したい場合（SIMPLE_PRODUCT_SEARCH クエリの場合のみ、または refined_search の候補が提供された場合など）は、コアの Product Search API にクエリを送信する前に、Conversational API のレスポンスを待ちます。レスポンスがある場合は、提供された refined_search クエリを使用して商品結果を取得します。

選択したユーザー インターフェース オプションに関係なく、実際の商品の結果を取得する必要がある場合は、Retail API を呼び出すことができます。詳細については、ステップ 2c. クエリタイプと販売者のアクションを理解する。

HTTP メソッドとエンドポイント

    POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search

コアプロダクトの検索 API リクエスト:

最初のクエリ

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
  • placement（必須）: Retail Search サービング構成または以前のプレースメントのリソース名。例: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search
  • query: 必須。検索クエリ。これは、ユーザーの生入力（「パーティーの計画を手伝って」など）の場合もあれば、Conversational Commerce API レスポンスから取得した最適化された refinedSearch.query（「パーティーの計画用品、飾り付け」など）の場合もあります。
  • visitorId: 必須。訪問者をトラッキングするための一意の識別子。これは、同じエンドユーザーに対して Conversational Commerce API に送信される visitorId と一致している必要があります。
  • branch（必須）: ブランチのリソース名（projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch など）。
  • pageSize（省略可）: 返される商品の最大数。
  • filter（省略可）: 検索結果のフィルタリングに使用されます。ここでは、一貫性を保つために、`searchParams` で Conversational Commerce API に送信する内容を反映したフィルタを適用します。
  • orderBy（省略可）: 商品が返される順序（関連性や価格など）を指定します。
  • userInfo（省略可）: パーソナライズ用のユーザー情報。Conversational Commerce API 呼び出しと一致している必要があります。
  • searchMode（省略可）: 検索動作を定義します。PRODUCT_SEARCH は、一般的なプロダクト クエリでよく使用されます。

レスポンスの内容

このコードサンプルは、Conversational Commerce API からのレスポンスを示しています。

API レスポンス（ConversationalSearchResponse）には、query_types、conversational_text_response（該当する場合）、refined_search オプション、場合によっては followup_question または conversational_filtering_result が含まれます。セッションを続行するには conversation_id が不可欠です。

Vertex AI Search for Commerce からのレスポンス

このコードサンプルは、Conversational API レスポンスを示しています。

初期対応

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }

小売業者が行うレスポンスの処理（全般）

レスポンスから次のフィールドをレンダリングします。

  • user_query_types: このフィールドは、ユーザーの意図の分類を提供します。これらのタイプに基づく詳細なアクションについては、[クエリタイプと小売業者のアクションを理解する](#step-2c) を参照してください。
  • conversation_id: この一意の ID をブラウザ セッション ストレージや同様のクライアントサイド ストレージに保存して、サーバーとの会話セッションを維持できます。これは、1 人の買い物客に対して複数の進行中の会話を区別するために不可欠です。モデルは、特定の conversation_id のコンテキストを保持します。新しい conversation_id を送信すると、新しいセッションが開始されます。セッションの期間（30 分間操作がないなど）を定義することをおすすめします。
  • refined_search: 関連する検索結果を取得するために使用される、提案された絞り込み検索クエリのリスト。SIMPLE_PRODUCT_SEARCH の場合、常に単一のクエリになります。他の LLM 回答を求めるクエリの場合は、1 つ以上になります。refined_search クエリは、コア検索 API（SearchService.Search）の呼び出しに使用することも、ユーザーに候補として表示することもできます。
  • conversational_text_response: このテキストをユーザーのクエリに対する主な AI 生成レスポンスとして表示します。
  • followup_question: 省略可。followup_question が表示されます。
  • state: このフィールドは、レスポンス生成の状態（STREAMING または SUCCEEDED）を示します。これは、SUCCEEDED まで読み込みインジケーターを表示するなど、UI フィードバックに使用できます。詳しくは、ステップ 2b をご覧ください。Streaming API について

ストリーミング API について

Conversational commerce API は、ストリーミング API として動作します。つまり、ユーザーは単一の完全なペイロードではなく、レスポンスの一部を複数のチャンクで受け取ります。

レスポンスの最初のチャンクには query_types クエリと refined_search クエリが含まれ、その state は STREAMING として示されます。意図を早期に検出し、検索の絞り込みをすぐに利用できるようにすることで、モデルはユーザーのクエリを処理する方法と、LLM レスポンスのレイテンシに関するユーザー エクスペリエンスを管理する方法を迅速に決定できます。

  • 会話テキスト レスポンスを想定していないクエリタイプ（SIMPLE_PRODUCT_SEARCH、RETAIL_IRRELEVANT、BLOCKLISTED、QUERY_TYPE_UNSPECIFIED、ORDER_SUPPORT、DEALS_AND_COUPONS、STORE_RELEVANT など）の場合: query_types が最初のチャンクにあるため、LLM の回答が返されないことをシステムがすぐに認識します。このようなタイプについては、静的メッセージの表示やサポートへの転送など、事前定義された処理を会話の出力の追加を待たずに続行できます。
    • 特に SIMPLE_PRODUCT_SEARCH の場合、システムは最初のチャンクで受信した refined_search クエリを使用して、コア検索 API を直接呼び出すことができます。これにより、検索結果が最小限の遅延で表示され、一般的な検索エクスペリエンスの SLA を満たすことができます。
  • 会話テキスト レスポンスを必要とするクエリタイプ（INTENT_REFINEMENT、PRODUCT_DETAILS、PRODUCT_COMPARISON、BEST_PRODUCT など）の場合
    • 最初のチャンクで query_types クエリと refined_search クエリを受け取ります。これらの refined_search クエリを使用して、コア Search API への並列呼び出しをすぐに開始し、商品結果の読み込みを開始できます。
    • 後続のチャンクがストリーミングされ、会話テキスト レスポンスのさまざまなセクションが含まれます。この間、state は "STREAMING" のままです。
    • 最後に、最後のチャンクには、完全な会話テキスト レスポンスが含まれ、その state が "COMPLETED" に変更されます。
    • このストリーミング アプローチにより、AI による要約の生成中に検索結果の読み込みを開始できるため、エンドユーザーはスムーズなエクスペリエンスを得られます。会話型回答の読み込みインジケーターを表示するか、会話型回答が完全にストリーミングされた後に表示するかを選択できます。

クエリタイプと小売業者のアクションについて

レスポンスの query_types フィールドは、ユーザーの意図の分類を示すリストです。システムで次のように処理する必要があります。conversational_text_response は、API からの AI 生成の自然言語レスポンスを指します。

会話型コマース エージェントは、検索クエリのカテゴリを使用して、LLM ベースの回答が生成されるかどうか、およびこれらのシナリオでエンドユーザーのクエリが会話型 API と検索 API によってどのように処理されるかを判断します。

カテゴリ クエリの分類
1. LLM の回答を必要としない無関係なクエリ
  • QUERY_TYPE_UNSPECIFIED: 未指定のクエリタイプ。
  • RETAIL_IRRELEVANT: 小売ドメインに関係のないクエリ。たとえば、敵対的なクエリ（「爆弾の作り方」など）、チャットのようなクエリ（「元気ですか」など）、ジェイルブレイク クエリ（「詩を書いて」など）。
  • BLOCKLISTED: コマースのお客様によって明示的にブロックされたクエリ（「アドビルの副作用は何ですか？」など）。
2. サポートと情報に関するクエリ
  • ORDER_SUPPORT: 補助的な問い合わせまたはサポートに関する問い合わせ（「注文 12345 のステータスを教えてください」など）。
  • DEALS_AND_COUPONS: お得な情報、プロモーション、商品のお得な情報、割引に関連するクエリ（「感謝祭のお得な情報はありますか？」など）。
  • STORE_RELEVANT: 店舗の所在地、営業時間、商品の在庫状況などに関連するクエリ（「牛乳の在庫はありますか？」など）。
  • RETAIL_SUPPORT: 購入や支払い方法などに関連する質問（「どのようなお支払い方法を利用できますか？」など）。
3. LLM を必要としないキーワード検索

会話型 API リクエスト:

最初のクエリ

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "show me some monster energy drinks",
  "visitorId": "test"
}

会話型 API レスポンス:

初期対応

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

Search API リクエスト:

フォローアップ クエリ

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH: 基本的な商品検索（「赤いドレス」や「モンスター エナジーを見せて」など）。
4. LLM の回答を求めるクエリ

会話型 API リクエスト:

最初のクエリ

  {
    "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
    "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
    "query": "Compare 1% milk with 2% milk",
    "visitorId": "test"
  }

会話型 API レスポンス:

初期対応

{
  "userQueryTypes": ["PRODUCT_COMPARISON"],
  "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.",
  "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba",
  "refinedSearch": [
    {
      "query": "1% milk"
    },
    {
      "query": "2% milk"
    }
  ]
}

Search API リクエスト:

フォローアップ クエリ

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS: ユーザーが商品に関する詳細や仕様（「[商品名] の仕様を教えて」、「2% ミルクのタンパク質含有量は？」など）を求めている。
  • PRODUCT_COMPARISON: 商品の比較（「[商品名] と [商品名] を比較して」、「1% ミルクと 2% ミルクを比較して」など）。
  • BEST_PRODUCT: 最も一致するパターンを含むクエリ（「最も健康的なクッキーは？」など）どの牛乳ブランドが一番良いですか？）。
#5. インテントの絞り込み

会話型 API リクエスト:

最初のクエリ

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "Help me plan a party",
  "visitorId": "test"
}

会話型 API レスポンス:

初期対応

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}
  • INTENT_REFINEMENT: タイプが不明確で、タイプを明確にするためにフォローアップの会話や絞り込みが必要になる可能性がある場合（例: 「パーティーの計画を手伝って」）。これは、会話で最も一般的なインテントです。

カテゴリ 1。LLM の回答を必要としない無関係なクエリ

  • QUERY_TYPE_UNSPECIFIED:
    • conversational_text_response は提供されません。
    • 対応: デフォルトまたはエラーのケースとして処理します。ユーザーに説明を求めたり、一般的なサポートを受けられる場所を案内したりすることがあります。
  • RETAIL_IRRELEVANT:
    • conversational_text_response は提供されません。
    • アクション: アプリケーションの設計で定義されているとおりに、「その質問にはお答えできません」や「私はショッピング アシスタントです。何かお手伝いできることはありますか？」などの適切なメッセージを表示して、この問題を処理します。
  • BLOCKLISTED:
    • conversational_text_response は提供されません。
    • アクション: ブロックリスト ポリシーに従って処理します。通常は、汎用的な「このリクエストを処理できません」というメッセージを表示します。

カテゴリ 2。サポートと情報に関するクエリ

これらのタイプの場合、API はデフォルトで直接 conversational_text_response を提供しませんが、適切なリンクまたはリソースに誘導するオプションがあります。

  • ORDER_SUPPORT:
    • デフォルトのアクション: conversational_text_response は提供されません。UI に標準メッセージや関連リンクを表示するか、クエリを専用のサポート API またはカスタマー サービス チャネルに転送する必要があります。
  • DEALS_AND_COUPONS:
    • デフォルトのアクション: conversational_text_response は提供されません。UI に標準のメッセージや関連リンクを表示するか、クエリをセールやプロモーション システムに転送する必要があります。
  • STORE_RELEVANT:
    • デフォルトのアクション: conversational_text_response は提供されません。UI に標準のメッセージや関連リンクを表示するか、独自の店舗検索システムや情報システムにクエリを転送する必要があります。
  • RETAIL_SUPPORT:
    • デフォルトのアクション: conversational_text_response は提供されません。UI に標準のメッセージや関連リンクを表示するか、独自のよくある質問や情報システムにクエリを転送する必要があります。

カテゴリ 3。LLM の回答を必要としないキーワード検索

  • SIMPLE_PRODUCT_SEARCH:
    • 会話型テキスト レスポンスは生成されません。
    • アクション: API レスポンスは常に 1 つの refined_search クエリを返します。この絞り込まれたクエリは、検索候補の検索語句として機能します。コア検索 API（SearchService.Search）を直接呼び出し、元のクエリまたは refined_search クエリのいずれかを使用して、関連する商品結果を取得します。refined_search.query は、現在のエンドユーザーの入力から直接取得されるものではなく、チャット履歴のコンテキストから導出されることもあります。たとえば、エンドユーザーが以前に「パーティードレス」を「赤いもの」に絞り込んだ場合、絞り込んだクエリは「赤いパーティードレス」になる可能性があります。
      • 会話インターフェース（チャットボットなど）の場合: API で提供される refined_search.query を使用することを強く推奨します。会話フローでは、「バナナを探してくれますか？」などの自然言語のクエリが API によって正確な商品検索語句（「バナナ」）に自動的に最適化され、関連性の高い商品検索結果が表示されます。
      • コア検索エクスペリエンス（検索結果ページなど）の場合: 元のクエリがすでに正確な商品検索語句である可能性が高いため、API の refined_search.query またはエンドユーザーが提供した元のクエリのいずれかを柔軟に使用できます。UI と検索結果の表示戦略に最適なオプションを選択します。
    • ユーザー エクスペリエンスのオプション: SIMPLE_PRODUCT_SEARCH クエリの場合、会話を終了する必要はありません。ユーザーは、後続のリクエストで conversation_id を渡すことで、会話を続けることができます。
      • オプション A: 会話型 UI を終了する: 多くの小売業者は、SIMPLE_PRODUCT_SEARCH が検出されると、ユーザーを標準の検索結果ページに移行し、チャット ウィンドウを閉じます。このシナリオでは、エンドユーザーが以前の conversation_id を含まない新しいクエリを標準の検索ボックスに入力すると、新しい別の会話として扱われ、新しい conversation_id が発行されます。
      • オプション B: 会話型 UI を継続する: 小売業者はチャット ウィンドウを開いたままにできます。これにより、ユーザーは会話モードに戻ることができます。オプション A または B を実装するかどうかは、小売業者が希望するユーザー エクスペリエンスによって決まります。

    検索クエリを会話型インタラクションに正確に帰属させ、Vertex AI Search for Commerce 内で完全な分析機能を使用するには、適切なイベント タグ付けが不可欠です。

    1. conversation_id を取得する: conversationalSearch API 呼び出しを行うと、ConversationalSearchResponse.conversation_id が返されます。
    2. ユーザー イベントにタグ付けする: 会話型レスポンスが検索クエリにつながる場合（SIMPLE_PRODUCT_SEARCH の絞り込み済みクエリに基づいてシステムが自動的に検索を実行する場合など）、後続の検索ユーザー イベント（UserEvent）に、ConversationalSearchResponse で受け取った同じ conversation_id をタグ付けする必要があります。

UserEvent.conversation_id を正しくタグ付けすると、検索クエリを前の会話型インタラクションに正確に帰属させることができ、ユーザーの行動やコンバージョン経路に関する貴重な分析情報を得ることができます。

カテゴリ 4。LLM の回答を求めるクエリ

これらのクエリタイプの場合、API は conversational_text_response（LLM の回答）を生成し、1 つ以上の refined_search クエリを提供する場合があります。会話は終了せず、エンドユーザーは会話を続行できます。

  • PRODUCT_DETAILS:
    • 対応: conversational_text_response がリクエストされた製品の詳細を提供します。システムでは、この情報をユーザーにわかりやすく表示する必要があります。
    • レスポンスには、コア検索 API を使用して検索結果を取得するために使用する必要がある refined_search（1 つ以上の検索候補クエリ、順序付けとランキング）も含まれます。
  • PRODUCT_COMPARISON:
    • Action: conversational_text_response は、指定された商品の比較を提供します。システムでは、この情報をユーザーにわかりやすく表示する必要があります。
    • レスポンスには、コア検索 API を使用して検索結果を取得するために使用すべき refined_search（1 つ以上の検索候補クエリ、順序付けとランキング）が含まれます。
  • BEST_PRODUCT:
    • アクション: conversational_text_response は、クエリに基づいて「最適な」商品に関する推奨事項や情報を提供します。システムにこの情報が表示されます。
    • レスポンスには、コア検索 API を使用して検索結果を取得するために使用する必要がある refined_search（1 つ以上の検索候補クエリ、順序付けとランキング）が含まれます。

カテゴリ 5。インテントのブラッシュアップ

  • INTENT_REFINEMENT:
    • アクション: レスポンスには、conversational_text_response、followup_question、refined_search（1 つ以上の検索候補）が含まれます。推奨される表示順序は次のとおりです。
      1. conversational_text_response
      2. refined_search の候補: 順序付けとランキングが行われているため、レスポンスと同じ順序で表示することが重要です。
      3. Followup_question
    • レスポンスには、コア検索 API を使用して検索結果を取得するために使用すべき refined_search（1 つ以上の検索候補クエリ、順序付けとランキング）が含まれます。
    • 以降のやり取りでは、ユーザーの回答を conversation_id とともに送信します。

商品の推奨クエリを表示する

会話型コマース エージェントに質問と商品候補を表示するように Google 検索を設定する方法は次のとおりです。

Conversational API が refinedSearch クエリを返した場合、これらのクエリは、エンドユーザーを関連性の高い商品に誘導する絶好の機会となります。これは、カテゴリ 4（LLM の回答を求めるクエリ）とカテゴリ 5（INTENT_REFINEMENT）で特に有用です。

推奨事項

  • 表示: 上位 N 個（1 ～ 3 個。UI に最適な数についてはテスト中）の refinedSearch クエリをユーザーに提示します。
  • メカニズム: これらの候補クエリは、バックグラウンドまたはユーザー操作時にコア検索 API（SearchService.Search）を通じて実行される必要があります。
  • プレゼンテーション: 検索結果をインタラクティブなカルーセルやクリック可能なカードとして表示し、ユーザーが関連する商品カテゴリや特定のアイテムを閲覧できるようにします。これにより、すぐに価値が提供され、会話型インタラクションと商品検索のギャップを埋めることができます。

Search API リクエスト:

フォローアップ クエリ

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}

Vertex AI Search for Commerce に送信するイベント

検索クエリを会話型インタラクションに正確に帰属させ、適切なイベント タグ付けを使用して Vertex AI Search for Commerce 内で完全な分析機能を使用することが重要です。

  1. conversation_id を取得する: conversationalSearch API 呼び出しを行うと、ConversationalSearchResponse.conversation_id が返されます。
  2. ユーザー イベントにタグ付けする: 会話型レスポンスが検索クエリにつながる場合（エンドユーザーがクリックする refined_search 候補を表示するなど）、またはシステムが絞り込まれたクエリに基づいて検索を自動的に実行する場合は、後続の検索ユーザー イベント（UserEvent）に ConversationalSearchResponse で受け取った同じ conversation_id をタグ付けする必要があります。

UserEvent.conversation_id を正しくタグ付けすることで、分析で検索クエリを前の会話型インタラクションに正確に帰属させ、ユーザーの行動とコンバージョン経路に関する貴重な分析情報を得ることができます。

会話を継続

このセクションでは、Conversational API によって Conversational Commerce エージェント セッションが維持され、この最終ステップで継続される仕組みについて説明します。

Conversational API は、進行中の会話を管理するために conversation_id を使用します。LLM の回答と検索結果の整合性を確保するため、後続の Conversational API リクエストには、コア検索 API 呼び出しの構成を反映した SearchParams を含める必要があります。

セッション処理

  • 新しい会話を開始する:
    • 説明: 新しい会話を開始するには、クライアントは API リクエストから conversationId を省略します。
    • 新しい会話を開始するタイミング: クライアントは、次のような一般的なユーザー エクスペリエンスのシナリオで、新しい会話を開始して API レスポンスから新しい conversationId を取得します。
      • 新しいタブまたはセッション: ユーザーが新しいブラウザタブでサイトを開いた場合、または完全に新しいセッションを開始した場合。
      • 新しい元のクエリ: 一部の UX デザインでは、お客様が新しい無関係なクエリを入力した場合、最も関連性の高いコンテキストを確保するために、会話フローを再開することを選択できます。
      • 会話を再開するボタン: UI に [新しいチャットを開始] ボタンまたは [会話をリセット] ボタンが明示的に用意されている場合、このボタンをクリックすると新しい会話セッションがトリガーされます。
    • 会話 API の統合: API レスポンスには、後続のリクエストで使用される新しい conversationId が含まれます。
  • 会話を続ける:
    • 説明: Conversational API は、API レスポンスの一部として conversation_id を返します。同じ会話を続けるには、この ID をフォローアップ リクエストで送信する必要があります。これにより、会話コマース エージェントがセッション内の会話履歴に基づいてユーザーのクエリに応答し、エンドユーザーの query、conversational_text_response、followup_question をカバーできるようになります。
    • 会話型 API 統合: クライアントは、前のレスポンスの conversation_id を ConversationalSearchRequest で渡します。
  • 検索結果の一貫性を確保する:
    • 説明: LLM の回答がユーザーに表示される検索結果と一致するようにするには、クライアントは Conversational API リクエストで searchParams を使用する必要があります。これらの検索パラメータは、商品結果を取得するために行われた Search API 呼び出しと同じ構成（フィルタ、並べ替え順序など）にする必要があります。
    • Conversational API の統合: ConversationalSearchRequest 内の searchParams オブジェクトは、コアの商品検索に使用される SearchRequest と同じように入力する必要があります。

Vertex AI Search for Commerce にリクエストを送信する

conversation_id はセッション ストレージから取得できます。リクエストには、新しいお客様の query を含める必要があります。これは、前のレスポンスの質問に対する回答である可能性があります。エンドユーザーが絞り込んだクエリに基づいて操作している場合は、リクエストに前のレスポンスの最新の refined_search.query も含める必要があります。それ以外の場合は、まったく新しい無関係のクエリと conversationId を含める必要があります。常に一貫した searchParams を含めるようにしてください。

  • シナリオ 1: 単一の検索バーと永続的な会話: 検索インターフェースにメインの検索バーが 1 つしかない場合や、永続的な会話ウィンドウがある場合は、エンドユーザーが新しい、一見無関係なクエリを入力しても、conversationId はリセットされません。システムは、既存の会話履歴（conversationId に関連付けられている）を使用して、コンテキストに関連する回答を提供します。
  • シナリオ 2: 会話ウィンドウとクエリ ウィンドウが別になっている場合: 検索インターフェースに、会話用のチャット ウィンドウと、標準の検索クエリバー（サイト全体の検索ボックスなど）が別々に用意されている場合、標準の検索バーに新しいクエリを入力すると、新しい無関係の検索を開始する意図が暗黙的に示される可能性があります。そのため、その特定の検索アクションに対して conversationId がリセットされる可能性があります。ただし、専用の会話ウィンドウ内では、継続性を維持するために常に conversationId を維持する必要があります。

最終的に、conversationId を再利用するかリセットするかは、顧客の会話エクスペリエンスを最適化するための設計上の選択となります。

HTTP メソッドとエンドポイント（最初のクエリと同じ）

POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

会話型 API リクエスト:

フォローアップ クエリ

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}

会話型 API レスポンス:

フォローアップの回答

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

エンドユーザーに質問が届き続ける例:

  • ユーザーの質問: パーティーの計画を手伝って
  • システム回答: どのようなパーティーを計画していますか？
  • ユーザーの返信: 誕生日パーティー

小売業者が行うレスポンスの処理

フィールドのレンダリング方法は最初のレスポンスと同様ですが、会話の継続を反映した変更点に注意してください。

  • refined_search: このフィールドには、エンドユーザーの最新の入力を組み込んだ更新されたクエリが含まれます。現在のクエリに対応するクライアント コンソールを更新する必要があります（ユーザー向けのクエリが「飾り付け」から「誕生日パーティーの飾り付け」または「誕生日パーティー用品」に変更されたことを表示するなど）。refined_search クエリは、コア検索 API（SearchService.Search）の呼び出しに使用することも、候補としてエンドユーザーに表示することもできます。
  • conversational_text_response: 最新のターンに関連する新しい AI 生成テキスト レスポンスを表示します。
  • followup_question: 会話を継続してさらに絞り込む必要がある場合は、新しい followup_question が提供されます。

Vertex AI Search for Commerce に送信するイベント

イベント タグ付けは、検索クエリを会話型インタラクションに正確に帰属させ、Vertex AI Search for Commerce の分析機能を使用するために重要です。

イベント タグ付けのプロセスには次の 2 つのステップがあります。

  1. conversation_id を取得する: conversationalSearch API 呼び出しを行うと、ConversationalSearchResponse.conversation_id が返されます。
  2. ユーザー イベントにタグ付けする: 会話型レスポンスが検索クエリにつながる場合（refined_search の候補を表示するなど）、またはシステムが絞り込まれたクエリに基づいて検索を自動的に実行する場合は、後続の検索ユーザー イベント（UserEvent）に、ConversationalSearchResponse で受け取った同じ conversation_id をタグ付けする必要があります。

UserEvent.conversation_id に正しくタグ付けすることで、分析で検索クエリを前の会話型インタラクションに正確に帰属させ、エンドユーザーの行動とコンバージョン経路に関する貴重な分析情報を得ることができます。

その他の考慮事項とベスト プラクティス

会話型コマース エージェント インターフェースを実装する際は、次の追加の考慮事項とベスト プラクティスを考慮する必要があります。

  • 訪問者 ID の一貫性: 特定のエンドユーザーに対する各リクエストで、一意の visitor_id が一貫して送信されるようにします。これは、正確なパーソナライズとモデル トレーニングに不可欠です。この ID は、セッションやログイン / ログアウトの状態にかかわらず、エンドユーザーに対して一貫性を保つことが理想的です。
  • ブランチ管理: default_branch は一般的ですが、商品カタログが複数のブランチで構成されている場合は、正しいブランチ ID を使用していることを確認してください。
  • Search API のインタラクション: SIMPLE_PRODUCT_SEARCH の場合や refined_search が指定されている場合は、refined_search フィールドの query または元のクエリを使用して、コア Search API（SearchService.Search）に個別の呼び出しを行い、実際の商品のリスティングを取得してください。Conversational API は、主に会話型のエクスペリエンスとユーザーの意図の理解に重点を置いており、商品結果を直接返すことはありません。
  • ユーザー インターフェースのデザイン: conversational_text_response、followup_question、refined_search のオプションを直感的に提示し、ユーザーをガイドする UI を設計します。

次のステップ

その他のサポート リソースについては、会話機能に関するよくある質問をご覧ください。