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

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

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

API の設定と呼び出しフロー

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

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

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

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

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

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

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

API エンドポイントは次の 2 つです。

  1. 会話エクスペリエンスを取得するには、会話 API を使用する必要があります。
  2. 検索結果を取得するには、コアの Search API を使用する必要があります。

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

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

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

  POST https://retail.googleapis.com/v2/{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 リクエスト

ウェブ インターフェースで検索結果を表示するには、主に次の 2 つの方法があります。

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

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

オプション 2: 会話の出力に基づいて検索結果を表示する

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

選択したユーザー インターフェース オプションに関係なく、実際の商品の結果を取得する必要がある場合は、Retail API を呼び出すことができます。詳しくは、ユーザーの意図の分類と販売者のアクションについてをご覧ください。

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

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

コアプロダクトの 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: このフィールドは、ユーザーの意図の分類を提供します。これらのタイプに基づく詳細なアクションについては、ユーザーの意図の分類と小売業者のアクションについてを参照してください。
  • 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" まで読み込みインジケーターを表示するなど、ユーザー エクスペリエンスのフィードバックに使用できます。この点について詳しくは、次のセクションをご覧ください。

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

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

  • ストリーミングのメリットLLM によるテキスト生成には時間がかかることがあります。ストリーミングにより、迅速な対応が可能になります。
  • 最初の応答チャンク（即時）:
  • userQueryTypes クエリと refinedSearch クエリが含まれます。
  • state: "STREAMING"
  • 後続のチャンク:
  • conversationalTextResponse の一部を生成中に含めます。
  • 最後のチャンク:
  • 完全な conversationalTextResponse が含まれます。
  • state: "SUCCEEDED"
  • 実用的な分析情報: 最初のチャンクからユーザーの意図をすぐに判断し、AI テキスト レスポンスの読み込み中に、商品結果の取得を並行して開始できます。

レスポンスの最初のチャンクには 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 クエリを使用して、コア 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 生成の自然言語レスポンスを指します。

userQueryTypes フィールド（最初のレスポンス チャンク内）は、アプリの次のアクションを決定するうえで最も重要なフィールドです。

  • SIMPLE_PRODUCT_SEARCH: 赤いドレス
    • API レスポンス: conversational_text_response はありません。単一の refinedSearch クエリを返します。
    • アクション: refinedSearch.query を使用して Search API をすぐに呼び出します。標準の検索結果ページに移行するか、結果を表示します。
  • INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT: パーティーを計画する
    • API レスポンス: conversationalTextResponse、refinedSearch クエリ、場合によっては followupQuestion を提供します。
    • アクション: AI テキスト レスポンスを表示します。refinedSearch クエリを使用して、商品カルーセルや候補を生成します。followupQuestion を表示します。
  • サポートクエリ: ORDER_SUPPORT と STORE_RELEVANT を含めます。
    • API レスポンス: conversational_text_response なし。
    • 対応: 注文の追跡、店舗検索などの適切なページにユーザーをリダイレクトするか、定型文を表示します。

会話型コマース エージェントは、検索クエリのカテゴリを使用して、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 は提供されません。ウェブ インターフェースには、標準のメッセージ、関連するリンクを表示するか、クエリを専用のサポート API またはカスタマー サービス チャンネルに転送する必要があります。
  • DEALS_AND_COUPONS:
    • デフォルトのアクション: conversational_text_response は提供されません。ウェブ インターフェースに、標準のメッセージ、関連するリンクを表示するか、クエリを取引またはプロモーション システムに転送する必要があります。
  • STORE_RELEVANT:
    • デフォルトのアクション: conversational_text_response は提供されません。ウェブ インターフェースに標準のメッセージや関連リンクを表示するか、クエリを独自の店舗検索システムや情報システムに転送する必要があります。
  • RETAIL_SUPPORT:
    • デフォルトのアクション: conversational_text_response は提供されません。ウェブ インターフェースには、標準のメッセージ、関連するリンクを表示するか、クエリを独自のよくある質問と情報システムに転送する必要があります。

カテゴリ 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 またはエンドユーザーが提供した元のクエリのいずれかを柔軟に使用できます。ウェブ インターフェースと検索結果の表示戦略に最適なオプションを選択します。
    • ユーザー エクスペリエンスのオプション: SIMPLE_PRODUCT_SEARCH クエリの場合、会話を終了する必要はありません。ユーザーは、後続のリクエストで conversation_id を渡すことで、会話を継続できます。
      • オプション A: 会話型ウェブ インターフェースを終了する: 多くの小売業者は、SIMPLE_PRODUCT_SEARCH が検出されると、ユーザーを標準の検索結果ページに移行し、チャット ウィンドウを閉じます。このシナリオでは、エンドユーザーが以前の conversation_id を含めずに標準の検索ボックスに新しいクエリを入力すると、新しい別の会話として扱われ、新しい conversation_id が発行されます。
      • オプション B: 会話型ウェブ インターフェースを継続する: 販売者はチャット ウィンドウを開いたままにできます。これにより、ユーザーは会話モードに戻ることができます。オプション 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:
    • アクション: 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 個。ウェブ インターフェースの理想的な数についてはテスト中）の 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 デザインでは、お客様が新しい無関係なクエリを入力した場合、最も関連性の高いコンテキストを確保するために、会話フローを再開することを選択できます。
      • 会話を再開するボタン: ウェブ インターフェースに [新しいチャットを開始] または [会話をリセット] ボタンが明示的に用意されている場合、このボタンをクリックすると新しい会話セッションがトリガーされます。
    • 会話 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 呼び出しと同じ構成（フィルタ、並べ替え順序など）である必要があります。
    • 会話 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/v2/{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 で受け取った同じ onversation_id をタグ付けする必要があります。

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

エージェントを会話型の商品フィルタリングと統合する

このガイドでは、会話型 API と会話型の商品フィルタリングの両方を統合して、AI を活用したショッピング エクスペリエンスを提供する方法について説明します。conversationalFilteringSpec.mode が ENABLED に設定されている場合、システムはオープンエンドの会話型インタラクションとガイド付きの商品フィルタリングの間を直接移行できるため、ユーザー ジャーニーを高度に洗練させることができます。

相互作用を理解する

会話型コマース エージェントと会話型商品フィルタリングの両方が有効になっている場合、システムはそれぞれの強みを活用します。会話型コマース エージェントは、幅広い問い合わせに対応し、AI 生成の回答を提供し、最初のインテントを絞り込みます。一方、会話型の商品フィルタリングは、簡素化されたチップベースまたはタイルベースのインタラクション モデルを使用して、特定の商品属性の選択をユーザーにガイドします。

この 2 つのモード間のインタラクションと移行の可能性は、会話型コマース API の分類が商品指向の検索（具体的には SIMPLE_PRODUCT_SEARCH）につながるときに発生します。この時点で、API は直接検索クエリを提供するか、ユーザーの意図をさらに絞り込むことができる場合は、会話型の商品フィルタリングを通じてガイド付きフィルタリング フローをトリガーします。

この統合の重要な原則は、自由形式の入力はすべて Conversational Commerce API で処理され、チップとして表示される回答の候補のクリックは会話型の商品フィルタリングで処理されることです。

ユーザークエリを送信する

ユーザー入力の例: パーティーの計画を手伝って

会話型コマース エージェントと会話型商品フィルタリングの両方を有効にするには、ConversationalSearchRequest に次の構成が含まれていることを確認します。

会話型コマース API リクエスト - 最初のクエリ

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

主な構成は次のとおりです。

  • Conversational_filtering_mode: ENABLED: conversationalFilteringSpec でこのフィールドを ENABLED に設定すると、システムが会話型の商品フィルタリングを処理できることが API に通知され、API は関連性の高いフィルタリング固有のレスポンスを提供できるようになります。

初回応答: インテントの絞り込み

userQueryTypes フィールドは、ユーザーの意図を理解するうえで引き続き重要な役割を果たします。「パーティーの計画を手伝って」のような広範なクエリの場合、より具体的な商品検索がすぐに明らかにならないと、API は INTENT_REFINEMENT として分類する可能性があります。

Google からの回答

会話型コマース 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"
}

アクション

  1. conversationalTextResponse を表示します。
  2. 飾り付け、おやつなどのクリック可能なチップとして refinedSearch の候補を表示します。または、refined_search クエリを使用して Commerce Search API を並行して呼び出し、会話のやり取りとともに、装飾品、スナックなどの関連する商品結果をカルーセルとして表示します。
  3. followupQuestion を表示します。どんなパーティーを計画していますか？
  4. 自由形式のユーザー入力を許可して、会話を進めます。

イベントタグと分析

最初の会話型インタラクションの正確な分析とアトリビューションを確保するには:

  • conversation_id を取得します。ConversationalSearchResponse から conversation_id をキャプチャします。この ID は、後続のすべてのアクションをこの特定の会話セッションにリンクするために不可欠です。
  • ユーザー イベントにタグを付ける。会話型レスポンスが検索クエリにつながる場合（システムが refined_search クエリに基づいて検索を自動的に実行する場合や、ユーザーが refined_search 候補をクリックする場合など）、その後の検索ユーザー イベント（UserEvent）に同じ conversation_id をタグ付けする必要があります。

フォローアップ クエリ

ユーザーが followupQuestion に応答すると、会話が絞り込まれます。

ユーザー入力の例: 誕生日パーティー

インテントの絞り込み | コード スニペット

会話型コマース 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": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

会話型コマース 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"
}

アクション

  1. 最初のレスポンスと同様に、新しい conversationalTextResponse、refinedSearch の候補、followupQuestion でウェブ インターフェースを更新します。
  2. 会話フローを続行し、詳細情報を求めます。

イベントタグと分析

ユーザーが会話を続行した場合:

  • conversation_id を取得します。前の ConversationalSearchResponse の conversation_id が現在の ConversationalSearchRequest で渡されていることを確認します。
  • ユーザー イベントにタグを付ける。会話型レスポンスが新しい検索クエリにつながる場合（ユーザーが refined_search 候補をクリックした場合や、システムが並列検索呼び出しを行った場合など）、後続の検索ユーザー イベント（UserEvent）に同じ conversation_id をタグ付けします。これにより、マルチターンの会話のジャーニーをトラッキングできます。

会話型商品フィルタリングへの移行

会話が具体的になるにつれて、システムはインテントを SIMPLE_PRODUCT_SEARCH として分類し、必要に応じて会話型の商品フィルタリングをトリガーする可能性があります。

ユーザー入力の例: プリンセスをテーマにした画像

会話型コマース API リクエスト - フォローアップ クエリ

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

クエリが SIMPLE_PRODUCT_SEARCH に分類された場合、会話型商品フィルタリングがトリガーされるかどうかに応じて、API レスポンスは次の 2 つのいずれかになります。主な違いは、conversationalFilteringResult フィールドの有無と内容です。

結果 1: フィルタリングがトリガーされる

これは、クエリが商品属性でさらに絞り込めるほどコアな場合に発生します。レスポンスには conversationalFilteringResult が含まれており、ウェブ インターフェースで優先する必要があります。

会話型コマース API レスポンス - 商品フィルタリングへの移行: 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

アクション

クエリは SIMPLE_PRODUCT_SEARCH に分類されました。この場合、会話型の商品フィルタリングがトリガーされます。ただし、会話型商品フィルタリングがトリガーされない場合もあります。

  • 会話型の商品フィルタリング ウェブ インターフェースを優先する:conversationalFilteringResult が入力されている場合、商品フィルタリング モードに入ったことを示します。ウェブ インターフェースでは、followupQuestion（ユーザー インターフェースでは「どんな種類のプリンセス デコレーションをお探しですか？」のような形で表示されます）と suggestedAnswers（「風船」、「ストリーマー」、「テーブルクロス」などのクリック可能なボタンとして表示されます）を強調する必要があります。
  • 商品結果を表示する: refined_search.query （プリンセスの誕生日飾り）を使用して Retail Search API をすぐに呼び出し、フィルタリング オプションとともに初期の商品結果を表示します。
  • 推奨されるユーザー エクスペリエンスのプラクティス: エクスペリエンス全体で、永続的な自由形式の入力バーを 1 つだけ用意する必要があります。このバーは、会話型の商品フィルタリング フロー中を含め、常にアクティブな状態を維持します。 conversationalFilteringResult が有効で、クリック可能なチップとして候補の回答を表示する場合、ユーザーには次の 2 つの明確な選択肢があります。
    • 候補の回答をクリックして、フィルタリング フローを続行します。
    • アクティブなテキストバーに新しいクエリを入力して、新しい会話のターンを開始します。この新しい入力は常に Conversational Commerce API への新しい呼び出しをトリガーし、現在のフィルタリング フローを効果的に終了させます。

結果 2: フィルタリングがトリガーされない

クエリがすでに十分に具体的であるか、それ以上のフィルタリングに適していない場合、レスポンスに conversationalFilteringResult フィールドは含まれません。この場合は、標準検索に進みます。

アクション

  • このやり取りを会話フローの終了として扱い、refined_search クエリを使用して Retail Search API を呼び出し、標準のプロダクト結果ページを表示します。

イベントタグと分析

会話が商品フィルタリングに移行した場合:

  • conversation_id を取得します。引き続き同じ conversation_id を使用します。
  • ユーザー イベントにタグを付ける。遷移が即座の検索につながる場合は、その UserEvent に conversation_id をタグ付けします。重要なのは、エンドユーザーが [バルーン] をクリックするなどして suggestedAnswers を操作したときに、同じ conversation_id でタグ付けされた filter イベントや新しい search イベントなどの UserEvent もトリガーされることです。これにより、会話フロー内のフィルタリング アクションのアトリビューションが可能になります。

会話型の商品フィルタリングを続行する

ユーザーが suggestedAnswer を選択したら、新しい ConversationalSearchRequest を送信します。

ユーザー入力の例（候補の回答をクリック）: 風船

シンプルな商品検索 | コード スニペット

会話型コマース API リクエスト - フィルタリングを続行

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

会話型コマース API レスポンス - フィルタリングを続行する

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

アクション

API は、SIMPLE_PRODUCT_SEARCH クエリを返しますが、conversationalFilteringResult フィールドは含まれていません。これは、ガイド付きフィルタリング フローが終了したことを示します。

  • 最終的な refinedSearch クエリ（プリンセスの誕生日バルーン）を使用して、Retail Search API を直接呼び出します。
  • 最終的なプロダクトの結果をユーザーに表示します。この時点で、会話を終了するか、ユーザーが新しいクエリを入力して新しいターンを開始できます。

イベントタグと分析

商品フィルタリング プロセスの各ステップについて、以下の手順を行います。

  • conversation_id を取得します。フィルタリング セッション内のすべてのリクエストで、常に同じ conversation_id を使用します。
  • ユーザー イベントにタグを付ける。クリックなどの suggestedAnswer に対するユーザー操作ごとに、関連する UserEvent（filter イベントなど）をトリガーする必要があります。新しいクエリが作成された場合は、新しい search イベントをトリガーする必要があります。この UserEvent には、フィルタリングのジャーニーとそのコンバージョンへの影響を正確にトラッキングするために、conversation_id のタグ付けが必要です。

リファレンス アーキテクチャ

これは、 Google Cloudの Vertex AI Search for Commerce のリファレンス アーキテクチャ設計です。このリファレンス アーキテクチャは、会話型コマース エージェントのデータとサービスのフローを示しています。この図は、ユーザー イベント、商品カタログ データ、運用ログが処理、変換され、生成 AI インデックスと Retail Adapter サービスに統合されて、検索オペレーションを処理し、ユーザーの意図を満たして検索結果を返す方法を示しています。このアーキテクチャは、さまざまなプロジェクトを接続して、AI を活用した包括的なコマース検索機能を有効にします。

コマース AI リファレンス アーキテクチャ

次のステップ

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