Get recommendations

This page shows how to preview recommendations using the Google Cloud console and get recommendations results using the API. See the REST tab for examples of API calls that can help you integrate recommendations into your app.

The procedure that you use depends on the type of recommendations you want and the type of data store that your recommendation app is connected to:

• Get media recommendations
• Get generic recommendations for an app with structured data
• Get generic recommendations for an app with unstructured data
• Get generic recommendations for an app with website data

Note: Depending on the amount of data, it can take hours after data ingestion until the preview feature works.

Get media recommendations

Console

To use the Google Cloud console to preview media recommendations, follow these steps:

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app for which you want to preview recommendations.

3. Click Configurations > Training. If Ready to query is OK, then the app is ready for preview.

4. Click Preview.

5. Click the Document ID field. A list of document IDs appears.

6. Click the document ID for the document that you want recommendations for. Alternatively, enter a document ID into the Document ID field.

7. Click Select serving config and select the serving config to preview.

8. Optional: Enter the visitor ID (also called the pseudo user ID) of a user for whom you have collected user events. If you leave this field blank or enter a non-existent visitor ID, you'll preview recommendations as a new user.

9. Click Get recommendations. A list of recommended documents appears.

10. Click a document to get document details.

REST

To use the API to get media recommendations, use the servingConfigs.recommend method:

1. Find your engine ID and serving config ID. If you already have your engine ID and serving config IDs, skip to step 2.

   1. In the Google Cloud console, go to the Agent Builder page.

      Agent Builder

   2. Click the name of the app.

   3. In the navigation pane, click Configurations.

   4. If you have only the serving config that was automatically created when you created your app, then your serving config ID and engine ID are the same. Skip to the next step.

      If you have multiple serving configs listed in the Serving configs tab, find the serving config that you want to get recommendations from. Your serving config ID is the value in the ID column.

      If you deleted the serving config that was automatically created when you created your app, and currently have only one serving config that you manually created, then go to the Preview page and click Select serving config to view the serving config ID.

   5. Click the Training tab. Your engine ID is the value in the App ID row.

2. Make sure the app is ready for previewing:

   1. In the Google Cloud console, go to the Agent Builder page.

      Agent Builder

   2. Click the name of the app.

   3. Click Configurations > Training. If Ready to query is OK, then the app is ready for preview.

3. Get recommendations.

   Note: If your recommendation is not yet active or you want to test your method call, you can call this method with the validateOnly flag set to true. This call returns a placeholder result, and does not incur charges.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   -d  '{
           "validateOnly": false,
           "userEvent": {
               "eventType": "view-item",
               "userPseudoId": "USER_PSEUDO_ID",
               "documents": [{
                 "id": "DOCUMENT_ID"
               }],
           "filter": "FILTER_STRING"            }
       }' \
     "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"

   • PROJECT_ID: The ID of your project.
   • DATA_STORE_ID: The ID of your data store.
   • DOCUMENT_ID: The ID of document that you want to preview recommendations for. Use the ID that you used for this document at the time you ingested your data.
   • USER_PSEUDO_ID: A pseudonymized identifier of the user. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. Don't set this field to the same identifier for multiple users—this would combine their event histories and degrade model quality. Don't include personally identifiable information (PII) in this field.
   • SERVING_CONFIG_ID: The ID of your serving config.
   • FILTER: Optional. A text field that lets you to filter on a specified set of fields, using filter expression syntax. The default value is an empty string, which means no filter is applied. For more information, see Filter recommendations.

You should see results similar to the following:

{
  "results": [{"id": "sample-id-1"}, {"id": "sample-id-2"}],
  "attributionToken": "abc123"
}

Google recommends associating attribution tokens, which we include with each search response and recommendation, with actions that a user takes in response to those search responses and recommendations. This can improve the quality of your search responses and recommendations over time. To do this, append attributionToken values to the URLs for each of the links that you display on your website for search responses or recommendations—for example, https://www.example.com/54321/?rtoken=abc123. When a user clicks one of these links, include the attributionToken value in the user event that you record.

Get generic recommendations for an app with structured data

Preview — Recommendations (generic)

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Console

To use the Google Cloud console to preview generic recommendations for your structured app, follow these steps:

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app for which you want to preview recommendations.

3. Click Preview.

4. Click the Document ID field. A list of document IDs appears.

5. Click the document ID for the document that you want recommendations for. Alternatively, enter a document ID into the Document ID field.

6. Click Get recommendations. A list of recommended documents appears.

7. Click a document to get document details.

REST

To use the API to get generic recommendations for an app with structured data, use the servingConfigs.recommend method:

1. Find your engine ID. If you already have your engine ID, skip to step 2.

   1. In the Google Cloud console, go to the Agent Builder page.

      Agent Builder

   2. Click the name of the app.

   3. Get the engine ID from the URL of the Google Cloud console. It is the text between engines/ and /data. For example, if the URL contains

      gen-app-builder/engines/demo_1234567890123/data/records
      

      then the engine ID is demo_1234567890123.

2. Find your data store ID. If you already have your data store ID, skip to the next step.

   1. In the Google Cloud console, go to the Agent Builder page and in the navigation menu, click Data Stores.

      Go to the Data Stores page

   2. Click the name of your data store.

   3. On the Data page for your data store, get the data store ID.

3. Make sure your engine is ready to previewing by polling the GetEngine method until it returns "servingState":"ACTIVE". At that point the engine is ready for previewing.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/ENGINE_ID
   

   • PROJECT_ID: The ID of your project.
   • ENGINE_ID: The ID of your engine.

4. Get recommendations.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{
     "userEvent": { "eventType":"view-item", "userPseudoId":"USER_PSEUDO_ID", "documents":[{"id":"DOCUMENT_ID"}]}}' \
     "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
   

   • PROJECT_ID: The ID of your project.
   • DATA_STORE_ID: The ID of your data store.
   • DOCUMENT_ID: The ID of document that you want to preview recommendations for. Use the ID that you used for this document at the time you ingested your data.
   • USER_PSEUDO_ID: A pseudonymized identifier of the user. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. Don't set this field to the same identifier for multiple users—this would combine their event histories and degrade model quality. Don't include personally identifiable information (PII) in this field.
   • SERVING_CONFIG_ID: The ID of your serving config. Your serving config ID is the same as your engine ID, so use your engine ID here.

Note: Although Vertex AI Agent Builder currently does not leverage the pseudonymized ID for personalization functionality, Google strongly recommends including this value now for future implementations of Vertex AI Agent Builder.

C#

For more information, see the Vertex AI Agent Builder C# API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedRecommendationServiceClientSnippets
{
    /// <summary>Snippet for Recommend</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void RecommendRequestObject()
    {
        // Create client
        RecommendationServiceClient recommendationServiceClient = RecommendationServiceClient.Create();
        // Initialize request argument(s)
        RecommendRequest request = new RecommendRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            UserEvent = new UserEvent(),
            PageSize = 0,
            Filter = "",
            ValidateOnly = false,
            Params = { { "", new Value() }, },
            UserLabels = { { "", "" }, },
        };
        // Make the request
        RecommendResponse response = recommendationServiceClient.Recommend(request);
    }
}

Go

For more information, see the Vertex AI Agent Builder Go API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1beta"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewRecommendationClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.RecommendRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb#RecommendRequest.
	}
	resp, err := c.Recommend(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

For more information, see the Vertex AI Agent Builder Java API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.discoveryengine.v1beta.RecommendRequest;
import com.google.cloud.discoveryengine.v1beta.RecommendResponse;
import com.google.cloud.discoveryengine.v1beta.RecommendationServiceClient;
import com.google.cloud.discoveryengine.v1beta.ServingConfigName;
import com.google.cloud.discoveryengine.v1beta.UserEvent;
import com.google.protobuf.Value;
import java.util.HashMap;

public class SyncRecommend {

  public static void main(String[] args) throws Exception {
    syncRecommend();
  }

  public static void syncRecommend() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (RecommendationServiceClient recommendationServiceClient =
        RecommendationServiceClient.create()) {
      RecommendRequest request =
          RecommendRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.ofProjectLocationDataStoreServingConfigName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setPageSize(883849137)
              .setFilter("filter-1274492040")
              .setValidateOnly(true)
              .putAllParams(new HashMap<String, Value>())
              .putAllUserLabels(new HashMap<String, String>())
              .build();
      RecommendResponse response = recommendationServiceClient.recommend(request);
    }
  }
}

Node.js

For more information, see the Vertex AI Agent Builder Node.js API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Full resource name of a
 *  ServingConfig google.cloud.discoveryengine.v1beta.ServingConfig:
 *  `projects/* /locations/global/collections/* /engines/* /servingConfigs/*`, or
 *  `projects/* /locations/global/collections/* /dataStores/* /servingConfigs/*`
 *  One default serving config is created along with your recommendation engine
 *  creation. The engine ID is used as the ID of the default serving
 *  config. For example, for Engine
 *  `projects/* /locations/global/collections/* /engines/my-engine`, you can use
 *  `projects/* /locations/global/collections/* /engines/my-engine/servingConfigs/my-engine`
 *  for your
 *  RecommendationService.Recommend google.cloud.discoveryengine.v1beta.RecommendationService.Recommend 
 *  requests.
 */
// const servingConfig = 'abc123'
/**
 *  Required. Context about the user, what they are looking at and what action
 *  they took to trigger the Recommend request. Note that this user event
 *  detail won't be ingested to userEvent logs. Thus, a separate userEvent
 *  write request is required for event logging.
 *  Don't set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  or
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  to the same fixed ID for different users. If you are trying to receive
 *  non-personalized recommendations (not recommended; this can negatively
 *  impact model performance), instead set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  to a random unique ID and leave
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  unset.
 */
// const userEvent = {}
/**
 *  Maximum number of results to return. Set this property
 *  to the number of recommendation results needed. If zero, the service
 *  chooses a reasonable default. The maximum allowed value is 100. Values
 *  above 100 are set to 100.
 */
// const pageSize = 1234
/**
 *  Filter for restricting recommendation results with a length limit of 5,000
 *  characters. Currently, only filter expressions on the `filter_tags`
 *  attribute is supported.
 *  Examples:
 *   * `(filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))`
 *   * `(filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))`
 *  If `attributeFilteringSyntax` is set to true under the `params` field, then
 *  attribute-based expressions are expected instead of the above described
 *  tag-based syntax. Examples:
 *   * (launguage: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
 *   * (available: true) AND
 *     (launguage: ANY("en", "es")) OR (categories: ANY("Movie"))
 *  If your filter blocks all results, the API returns generic
 *  (unfiltered) popular Documents. If you only want results strictly matching
 *  the filters, set `strictFiltering` to `true` in
 *  RecommendRequest.params google.cloud.discoveryengine.v1beta.RecommendRequest.params 
 *  to receive empty results instead.
 *  Note that the API never returns
 *  Document google.cloud.discoveryengine.v1beta.Document s with
 *  `storageStatus` as `EXPIRED` or `DELETED` regardless of filter choices.
 */
// const filter = 'abc123'
/**
 *  Use validate only mode for this recommendation query. If set to `true`, a
 *  fake model is used that returns arbitrary Document IDs.
 *  Note that the validate only mode should only be used for testing the API,
 *  or if the model is not ready.
 */
// const validateOnly = true
/**
 *  Additional domain specific parameters for the recommendations.
 *  Allowed values:
 *  * `returnDocument`: Boolean. If set to `true`, the associated Document
 *     object is returned in
 *     RecommendResponse.RecommendationResult.document google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.document.
 *  * `returnScore`: Boolean. If set to true, the recommendation score
 *     corresponding to each returned Document is set in
 *     RecommendResponse.RecommendationResult.metadata google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.metadata.
 *     The given score indicates the probability of a Document conversion given
 *     the user's context and history.
 *  * `strictFiltering`: Boolean. True by default. If set to `false`, the
 *  service
 *     returns generic (unfiltered) popular Documents instead of empty if
 *     your filter blocks all recommendation results.
 *  * `diversityLevel`: String. Default empty. If set to be non-empty, then
 *     it needs to be one of:
 *      *  `no-diversity`
 *      *  `low-diversity`
 *      *  `medium-diversity`
 *      *  `high-diversity`
 *      *  `auto-diversity`
 *     This gives request-level control and adjusts recommendation results
 *     based on Document category.
 *  * `attributeFilteringSyntax`: Boolean. False by default. If set to true,
 *     the `filter` field is interpreted according to the new,
 *     attribute-based syntax.
 */
// const params = [1,2,3,4]
/**
 *  The user labels applied to a resource must meet the following requirements:
 *  * Each resource can have multiple labels, up to a maximum of 64.
 *  * Each label must be a key-value pair.
 *  * Keys have a minimum length of 1 character and a maximum length of 63
 *    characters and cannot be empty. Values can be empty and have a maximum
 *    length of 63 characters.
 *  * Keys and values can contain only lowercase letters, numeric characters,
 *    underscores, and dashes. All characters must use UTF-8 encoding, and
 *    international characters are allowed.
 *  * The key portion of a label must be unique. However, you can use the same
 *    key with multiple resources.
 *  * Keys must start with a lowercase letter or international character.
 *  See Requirements for
 *  labels (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
 *  for more details.
 */
// const userLabels = [1,2,3,4]

// Imports the Discoveryengine library
const {RecommendationServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// Instantiates a client
const discoveryengineClient = new RecommendationServiceClient();

async function callRecommend() {
  // Construct request
  const request = {
    servingConfig,
    userEvent,
  };

  // Run request
  const response = await discoveryengineClient.recommend(request);
  console.log(response);
}

callRecommend();

PHP

For more information, see the Vertex AI Agent Builder PHP API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\ApiCore\ApiException;
use Google\Cloud\DiscoveryEngine\V1beta\Client\RecommendationServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendRequest;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendResponse;
use Google\Cloud\DiscoveryEngine\V1beta\UserEvent;

/**
 * Makes a recommendation, which requires a contextual user event.
 *
 * @param string $formattedServingConfig Full resource name of a
 *                                       [ServingConfig][google.cloud.discoveryengine.v1beta.ServingConfig]:
 *                                       `projects/*/locations/global/collections/*/engines/*/servingConfigs/*`, or
 *                                       `projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*`
 *
 *                                       One default serving config is created along with your recommendation engine
 *                                       creation. The engine ID is used as the ID of the default serving
 *                                       config. For example, for Engine
 *                                       `projects/*/locations/global/collections/*/engines/my-engine`, you can use
 *                                       `projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine`
 *                                       for your
 *                                       [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend]
 *                                       requests. Please see
 *                                       {@see RecommendationServiceClient::servingConfigName()} for help formatting this field.
 * @param string $userEventEventType     User event type. Allowed values are:
 *
 *                                       Generic values:
 *
 *                                       * `search`: Search for Documents.
 *                                       * `view-item`: Detailed page view of a Document.
 *                                       * `view-item-list`: View of a panel or ordered list of Documents.
 *                                       * `view-home-page`: View of the home page.
 *                                       * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
 *
 *                                       Retail-related values:
 *
 *                                       * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
 *                                       * `purchase`: Purchase an item(s)
 *
 *                                       Media-related values:
 *
 *                                       * `media-play`: Start/resume watching a video, playing a song, etc.
 *                                       * `media-complete`: Finished or stopped midway through a video, song, etc.
 * @param string $userEventUserPseudoId  A unique identifier for tracking visitors.
 *
 *                                       For example, this could be implemented with an HTTP cookie, which should be
 *                                       able to uniquely identify a visitor on a single device. This unique
 *                                       identifier should not change if the visitor log in/out of the website.
 *
 *                                       Do not set the field to the same fixed ID for different users. This mixes
 *                                       the event history of those users together, which results in degraded model
 *                                       quality.
 *
 *                                       The field must be a UTF-8 encoded string with a length limit of 128
 *                                       characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 *
 *                                       The field should not contain PII or user-data. We recommend to use Google
 *                                       Analytics [Client
 *                                       ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
 *                                       for this field.
 */
function recommend_sample(
    string $formattedServingConfig,
    string $userEventEventType,
    string $userEventUserPseudoId
): void {
    // Create a client.
    $recommendationServiceClient = new RecommendationServiceClient();

    // Prepare the request message.
    $userEvent = (new UserEvent())
        ->setEventType($userEventEventType)
        ->setUserPseudoId($userEventUserPseudoId);
    $request = (new RecommendRequest())
        ->setServingConfig($formattedServingConfig)
        ->setUserEvent($userEvent);

    // Call the API and handle any network failures.
    try {
        /** @var RecommendResponse $response */
        $response = $recommendationServiceClient->recommend($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = RecommendationServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );
    $userEventEventType = '[EVENT_TYPE]';
    $userEventUserPseudoId = '[USER_PSEUDO_ID]';

    recommend_sample($formattedServingConfig, $userEventEventType, $userEventUserPseudoId);
}

Python

For more information, see the Vertex AI Agent Builder Python API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1beta


def sample_recommend():
    # Create a client
    client = discoveryengine_v1beta.RecommendationServiceClient()

    # Initialize request argument(s)
    user_event = discoveryengine_v1beta.UserEvent()
    user_event.event_type = "event_type_value"
    user_event.user_pseudo_id = "user_pseudo_id_value"

    request = discoveryengine_v1beta.RecommendRequest(
        serving_config="serving_config_value",
        user_event=user_event,
    )

    # Make the request
    response = client.recommend(request=request)

    # Handle the response
    print(response)

Ruby

For more information, see the Vertex AI Agent Builder Ruby API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the recommend call in the RecommendationService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend.
#
def recommend
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest.new

  # Call the recommend method.
  result = client.recommend request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse.
  p result
end

Get generic recommendations for an app with unstructured data

Preview — Recommendations (generic)

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Console

To use the Google Cloud console to preview generic recommendations, follow these steps:

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app for which you want to preview recommendations.

3. Click Preview.

4. Click the URI field. A list of URIs appears.

5. Click the URI for the document that you want recommendations for. Alternatively, enter a URI into the URI field.

6. Click Get recommendations. A list of URIs for recommended documents appears.

7. Click a URI to view the document.

REST

To use the API to get generic recommendations for an app with unstructured data, follow these steps:

1. Find your engine ID. If you already have your engine ID, skip to step 2.

   1. In the Google Cloud console, go to the Agent Builder page.

      Agent Builder

   2. Click the name of the app.

   3. Get the engine ID from the URL of the Google Cloud console. It is the text between engines/ and /data. For example, if the URL contains

      gen-app-builder/engines/demo_1234567890123/data/records
      

      then the engine ID is demo_1234567890123.

2. Find your data store ID. If you already have your data store ID, skip to the next step.

   1. In the Google Cloud console, go to the Agent Builder page and in the navigation menu, click Data Stores.

      Go to the Data Stores page

   2. Click the name of your data store.

   3. On the Data page for your data store, get the data store ID.

3. Make sure your engine is ready to previewing by polling the GetEngine method until it returns "servingState":"ACTIVE". At that point the engine is ready for previewing.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/ENGINE_ID
   

   • PROJECT_ID: The ID of your project.
   • ENGINE_ID: The ID of your engine.

4. Get recommendations.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{
     "userEvent": { "eventType":"view-item", "userPseudoId":"USER_PSEUDO_ID", "documents":[{"id":"DOCUMENT_ID"}]}}' \
     "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
   

   • PROJECT_ID: The ID of your project.
   • DATA_STORE_ID: The ID of the data store associated with your engine.
   • DOCUMENT_ID: The ID of document that you want to preview recommendations for. Use the document ID that you provided at the time you ingested your data.
   • USER_PSEUDO_ID: A pseudonymized identifier of the user. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. Don't set this field to the same identifier for multiple users—this would combine their event histories and degrade model quality. Don't include personally identifiable information (PII) in this field.
   • SERVING_CONFIG_ID: The ID of your serving config. Your serving config ID is the same as your engine ID, so use your engine ID here.

Note: Although Vertex AI Agent Builder currently does not leverage the pseudonymized ID for personalization functionality, Google strongly recommends including this value now for future implementations of Vertex AI Agent Builder.

C#

For more information, see the Vertex AI Agent Builder C# API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedRecommendationServiceClientSnippets
{
    /// <summary>Snippet for Recommend</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void RecommendRequestObject()
    {
        // Create client
        RecommendationServiceClient recommendationServiceClient = RecommendationServiceClient.Create();
        // Initialize request argument(s)
        RecommendRequest request = new RecommendRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            UserEvent = new UserEvent(),
            PageSize = 0,
            Filter = "",
            ValidateOnly = false,
            Params = { { "", new Value() }, },
            UserLabels = { { "", "" }, },
        };
        // Make the request
        RecommendResponse response = recommendationServiceClient.Recommend(request);
    }
}

Go

For more information, see the Vertex AI Agent Builder Go API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1beta"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewRecommendationClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.RecommendRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb#RecommendRequest.
	}
	resp, err := c.Recommend(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

For more information, see the Vertex AI Agent Builder Java API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.discoveryengine.v1beta.RecommendRequest;
import com.google.cloud.discoveryengine.v1beta.RecommendResponse;
import com.google.cloud.discoveryengine.v1beta.RecommendationServiceClient;
import com.google.cloud.discoveryengine.v1beta.ServingConfigName;
import com.google.cloud.discoveryengine.v1beta.UserEvent;
import com.google.protobuf.Value;
import java.util.HashMap;

public class SyncRecommend {

  public static void main(String[] args) throws Exception {
    syncRecommend();
  }

  public static void syncRecommend() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (RecommendationServiceClient recommendationServiceClient =
        RecommendationServiceClient.create()) {
      RecommendRequest request =
          RecommendRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.ofProjectLocationDataStoreServingConfigName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setPageSize(883849137)
              .setFilter("filter-1274492040")
              .setValidateOnly(true)
              .putAllParams(new HashMap<String, Value>())
              .putAllUserLabels(new HashMap<String, String>())
              .build();
      RecommendResponse response = recommendationServiceClient.recommend(request);
    }
  }
}

Node.js

For more information, see the Vertex AI Agent Builder Node.js API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Full resource name of a
 *  ServingConfig google.cloud.discoveryengine.v1beta.ServingConfig:
 *  `projects/* /locations/global/collections/* /engines/* /servingConfigs/*`, or
 *  `projects/* /locations/global/collections/* /dataStores/* /servingConfigs/*`
 *  One default serving config is created along with your recommendation engine
 *  creation. The engine ID is used as the ID of the default serving
 *  config. For example, for Engine
 *  `projects/* /locations/global/collections/* /engines/my-engine`, you can use
 *  `projects/* /locations/global/collections/* /engines/my-engine/servingConfigs/my-engine`
 *  for your
 *  RecommendationService.Recommend google.cloud.discoveryengine.v1beta.RecommendationService.Recommend 
 *  requests.
 */
// const servingConfig = 'abc123'
/**
 *  Required. Context about the user, what they are looking at and what action
 *  they took to trigger the Recommend request. Note that this user event
 *  detail won't be ingested to userEvent logs. Thus, a separate userEvent
 *  write request is required for event logging.
 *  Don't set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  or
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  to the same fixed ID for different users. If you are trying to receive
 *  non-personalized recommendations (not recommended; this can negatively
 *  impact model performance), instead set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  to a random unique ID and leave
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  unset.
 */
// const userEvent = {}
/**
 *  Maximum number of results to return. Set this property
 *  to the number of recommendation results needed. If zero, the service
 *  chooses a reasonable default. The maximum allowed value is 100. Values
 *  above 100 are set to 100.
 */
// const pageSize = 1234
/**
 *  Filter for restricting recommendation results with a length limit of 5,000
 *  characters. Currently, only filter expressions on the `filter_tags`
 *  attribute is supported.
 *  Examples:
 *   * `(filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))`
 *   * `(filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))`
 *  If `attributeFilteringSyntax` is set to true under the `params` field, then
 *  attribute-based expressions are expected instead of the above described
 *  tag-based syntax. Examples:
 *   * (launguage: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
 *   * (available: true) AND
 *     (launguage: ANY("en", "es")) OR (categories: ANY("Movie"))
 *  If your filter blocks all results, the API returns generic
 *  (unfiltered) popular Documents. If you only want results strictly matching
 *  the filters, set `strictFiltering` to `true` in
 *  RecommendRequest.params google.cloud.discoveryengine.v1beta.RecommendRequest.params 
 *  to receive empty results instead.
 *  Note that the API never returns
 *  Document google.cloud.discoveryengine.v1beta.Document s with
 *  `storageStatus` as `EXPIRED` or `DELETED` regardless of filter choices.
 */
// const filter = 'abc123'
/**
 *  Use validate only mode for this recommendation query. If set to `true`, a
 *  fake model is used that returns arbitrary Document IDs.
 *  Note that the validate only mode should only be used for testing the API,
 *  or if the model is not ready.
 */
// const validateOnly = true
/**
 *  Additional domain specific parameters for the recommendations.
 *  Allowed values:
 *  * `returnDocument`: Boolean. If set to `true`, the associated Document
 *     object is returned in
 *     RecommendResponse.RecommendationResult.document google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.document.
 *  * `returnScore`: Boolean. If set to true, the recommendation score
 *     corresponding to each returned Document is set in
 *     RecommendResponse.RecommendationResult.metadata google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.metadata.
 *     The given score indicates the probability of a Document conversion given
 *     the user's context and history.
 *  * `strictFiltering`: Boolean. True by default. If set to `false`, the
 *  service
 *     returns generic (unfiltered) popular Documents instead of empty if
 *     your filter blocks all recommendation results.
 *  * `diversityLevel`: String. Default empty. If set to be non-empty, then
 *     it needs to be one of:
 *      *  `no-diversity`
 *      *  `low-diversity`
 *      *  `medium-diversity`
 *      *  `high-diversity`
 *      *  `auto-diversity`
 *     This gives request-level control and adjusts recommendation results
 *     based on Document category.
 *  * `attributeFilteringSyntax`: Boolean. False by default. If set to true,
 *     the `filter` field is interpreted according to the new,
 *     attribute-based syntax.
 */
// const params = [1,2,3,4]
/**
 *  The user labels applied to a resource must meet the following requirements:
 *  * Each resource can have multiple labels, up to a maximum of 64.
 *  * Each label must be a key-value pair.
 *  * Keys have a minimum length of 1 character and a maximum length of 63
 *    characters and cannot be empty. Values can be empty and have a maximum
 *    length of 63 characters.
 *  * Keys and values can contain only lowercase letters, numeric characters,
 *    underscores, and dashes. All characters must use UTF-8 encoding, and
 *    international characters are allowed.
 *  * The key portion of a label must be unique. However, you can use the same
 *    key with multiple resources.
 *  * Keys must start with a lowercase letter or international character.
 *  See Requirements for
 *  labels (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
 *  for more details.
 */
// const userLabels = [1,2,3,4]

// Imports the Discoveryengine library
const {RecommendationServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// Instantiates a client
const discoveryengineClient = new RecommendationServiceClient();

async function callRecommend() {
  // Construct request
  const request = {
    servingConfig,
    userEvent,
  };

  // Run request
  const response = await discoveryengineClient.recommend(request);
  console.log(response);
}

callRecommend();

PHP

For more information, see the Vertex AI Agent Builder PHP API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\ApiCore\ApiException;
use Google\Cloud\DiscoveryEngine\V1beta\Client\RecommendationServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendRequest;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendResponse;
use Google\Cloud\DiscoveryEngine\V1beta\UserEvent;

/**
 * Makes a recommendation, which requires a contextual user event.
 *
 * @param string $formattedServingConfig Full resource name of a
 *                                       [ServingConfig][google.cloud.discoveryengine.v1beta.ServingConfig]:
 *                                       `projects/*/locations/global/collections/*/engines/*/servingConfigs/*`, or
 *                                       `projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*`
 *
 *                                       One default serving config is created along with your recommendation engine
 *                                       creation. The engine ID is used as the ID of the default serving
 *                                       config. For example, for Engine
 *                                       `projects/*/locations/global/collections/*/engines/my-engine`, you can use
 *                                       `projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine`
 *                                       for your
 *                                       [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend]
 *                                       requests. Please see
 *                                       {@see RecommendationServiceClient::servingConfigName()} for help formatting this field.
 * @param string $userEventEventType     User event type. Allowed values are:
 *
 *                                       Generic values:
 *
 *                                       * `search`: Search for Documents.
 *                                       * `view-item`: Detailed page view of a Document.
 *                                       * `view-item-list`: View of a panel or ordered list of Documents.
 *                                       * `view-home-page`: View of the home page.
 *                                       * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
 *
 *                                       Retail-related values:
 *
 *                                       * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
 *                                       * `purchase`: Purchase an item(s)
 *
 *                                       Media-related values:
 *
 *                                       * `media-play`: Start/resume watching a video, playing a song, etc.
 *                                       * `media-complete`: Finished or stopped midway through a video, song, etc.
 * @param string $userEventUserPseudoId  A unique identifier for tracking visitors.
 *
 *                                       For example, this could be implemented with an HTTP cookie, which should be
 *                                       able to uniquely identify a visitor on a single device. This unique
 *                                       identifier should not change if the visitor log in/out of the website.
 *
 *                                       Do not set the field to the same fixed ID for different users. This mixes
 *                                       the event history of those users together, which results in degraded model
 *                                       quality.
 *
 *                                       The field must be a UTF-8 encoded string with a length limit of 128
 *                                       characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 *
 *                                       The field should not contain PII or user-data. We recommend to use Google
 *                                       Analytics [Client
 *                                       ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
 *                                       for this field.
 */
function recommend_sample(
    string $formattedServingConfig,
    string $userEventEventType,
    string $userEventUserPseudoId
): void {
    // Create a client.
    $recommendationServiceClient = new RecommendationServiceClient();

    // Prepare the request message.
    $userEvent = (new UserEvent())
        ->setEventType($userEventEventType)
        ->setUserPseudoId($userEventUserPseudoId);
    $request = (new RecommendRequest())
        ->setServingConfig($formattedServingConfig)
        ->setUserEvent($userEvent);

    // Call the API and handle any network failures.
    try {
        /** @var RecommendResponse $response */
        $response = $recommendationServiceClient->recommend($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = RecommendationServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );
    $userEventEventType = '[EVENT_TYPE]';
    $userEventUserPseudoId = '[USER_PSEUDO_ID]';

    recommend_sample($formattedServingConfig, $userEventEventType, $userEventUserPseudoId);
}

Python

For more information, see the Vertex AI Agent Builder Python API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1beta


def sample_recommend():
    # Create a client
    client = discoveryengine_v1beta.RecommendationServiceClient()

    # Initialize request argument(s)
    user_event = discoveryengine_v1beta.UserEvent()
    user_event.event_type = "event_type_value"
    user_event.user_pseudo_id = "user_pseudo_id_value"

    request = discoveryengine_v1beta.RecommendRequest(
        serving_config="serving_config_value",
        user_event=user_event,
    )

    # Make the request
    response = client.recommend(request=request)

    # Handle the response
    print(response)

Ruby

For more information, see the Vertex AI Agent Builder Ruby API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the recommend call in the RecommendationService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend.
#
def recommend
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest.new

  # Call the recommend method.
  result = client.recommend request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse.
  p result
end

Get generic recommendations for an app with website data

Preview — Recommendations (generic)

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Console

To use the Google Cloud console to preview generic recommendations for your website app, follow these steps:

1. In the Google Cloud console, go to the Agent Builder page.

   Agent Builder

2. Click the name of the app for which you want to preview recommendations.

3. In the navigation menu, click Preview.

4. Click the URI field. A list of URLs from your website appears.

5. Click the URL for the web page that you want recommendations for. Alternatively, enter a URL from your website into the URL field.

6. Click Get recommendations. A list of URLs for recommended web pages appears.

7. Click a URL to view the web page.

REST

To use the API to get generic recommendations for an app with website data, use the servingConfigs.recommend method:

1. Find your engine ID. If you already have your engine ID, skip to step 2.

   1. In the Google Cloud console, go to the Agent Builder page.

      Agent Builder

   2. Click the name of the app.

   3. Get the engine ID from the URL of the Google Cloud console. It is the text between engines/ and /data. For example, if the URL contains

      gen-app-builder/engines/demo_1234567890123/data/records
      

      then the engine ID is demo_1234567890123.

2. Find your data store ID. If you already have your data store ID, skip to the next step.

   1. In the Google Cloud console, go to the Agent Builder page and in the navigation menu, click Data Stores.

      Go to the Data Stores page

   2. Click the name of your data store.

   3. On the Data page for your data store, get the data store ID.

3. Make sure your engine is ready to previewing by polling the GetEngine method until it returns "servingState":"ACTIVE". At that point the engine is ready for previewing.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/ENGINE_ID
   

   • PROJECT_ID: The ID of your project.
   • ENGINE_ID: The ID of your engine.

4. Get recommendations.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{
     "userEvent": { "eventType":"view-item", "userPseudoId":"USER_PSEUDO_ID", "documents":[{"uri":"WEBSITE_URL"}]}}' \
     "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
   

   • PROJECT_ID: The ID of your project.
   • DATA_STORE_ID: The ID of your data store.
   • WEBSITE_URL: The URL of the website that you want to preview recommendations for.
   • USER_PSEUDO_ID: A pseudonymized identifier of the user. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. Don't set this field to the same identifier for multiple users—this would combine their event histories and degrade model quality. Don't include personally identifiable information (PII) in this field.
   • SERVING_CONFIG_ID: The ID of your serving config. Your serving config ID is the same as your engine ID, so use your engine ID here.

Note: Although Vertex AI Agent Builder currently does not leverage the pseudonymized ID for personalization functionality, Google strongly recommends including this value now for future implementations of Vertex AI Agent Builder.

C#

For more information, see the Vertex AI Agent Builder C# API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedRecommendationServiceClientSnippets
{
    /// <summary>Snippet for Recommend</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void RecommendRequestObject()
    {
        // Create client
        RecommendationServiceClient recommendationServiceClient = RecommendationServiceClient.Create();
        // Initialize request argument(s)
        RecommendRequest request = new RecommendRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            UserEvent = new UserEvent(),
            PageSize = 0,
            Filter = "",
            ValidateOnly = false,
            Params = { { "", new Value() }, },
            UserLabels = { { "", "" }, },
        };
        // Make the request
        RecommendResponse response = recommendationServiceClient.Recommend(request);
    }
}

Go

For more information, see the Vertex AI Agent Builder Go API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1beta"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewRecommendationClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.RecommendRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb#RecommendRequest.
	}
	resp, err := c.Recommend(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

For more information, see the Vertex AI Agent Builder Java API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.discoveryengine.v1beta.RecommendRequest;
import com.google.cloud.discoveryengine.v1beta.RecommendResponse;
import com.google.cloud.discoveryengine.v1beta.RecommendationServiceClient;
import com.google.cloud.discoveryengine.v1beta.ServingConfigName;
import com.google.cloud.discoveryengine.v1beta.UserEvent;
import com.google.protobuf.Value;
import java.util.HashMap;

public class SyncRecommend {

  public static void main(String[] args) throws Exception {
    syncRecommend();
  }

  public static void syncRecommend() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (RecommendationServiceClient recommendationServiceClient =
        RecommendationServiceClient.create()) {
      RecommendRequest request =
          RecommendRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.ofProjectLocationDataStoreServingConfigName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setPageSize(883849137)
              .setFilter("filter-1274492040")
              .setValidateOnly(true)
              .putAllParams(new HashMap<String, Value>())
              .putAllUserLabels(new HashMap<String, String>())
              .build();
      RecommendResponse response = recommendationServiceClient.recommend(request);
    }
  }
}

Node.js

For more information, see the Vertex AI Agent Builder Node.js API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Full resource name of a
 *  ServingConfig google.cloud.discoveryengine.v1beta.ServingConfig:
 *  `projects/* /locations/global/collections/* /engines/* /servingConfigs/*`, or
 *  `projects/* /locations/global/collections/* /dataStores/* /servingConfigs/*`
 *  One default serving config is created along with your recommendation engine
 *  creation. The engine ID is used as the ID of the default serving
 *  config. For example, for Engine
 *  `projects/* /locations/global/collections/* /engines/my-engine`, you can use
 *  `projects/* /locations/global/collections/* /engines/my-engine/servingConfigs/my-engine`
 *  for your
 *  RecommendationService.Recommend google.cloud.discoveryengine.v1beta.RecommendationService.Recommend 
 *  requests.
 */
// const servingConfig = 'abc123'
/**
 *  Required. Context about the user, what they are looking at and what action
 *  they took to trigger the Recommend request. Note that this user event
 *  detail won't be ingested to userEvent logs. Thus, a separate userEvent
 *  write request is required for event logging.
 *  Don't set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  or
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  to the same fixed ID for different users. If you are trying to receive
 *  non-personalized recommendations (not recommended; this can negatively
 *  impact model performance), instead set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  to a random unique ID and leave
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  unset.
 */
// const userEvent = {}
/**
 *  Maximum number of results to return. Set this property
 *  to the number of recommendation results needed. If zero, the service
 *  chooses a reasonable default. The maximum allowed value is 100. Values
 *  above 100 are set to 100.
 */
// const pageSize = 1234
/**
 *  Filter for restricting recommendation results with a length limit of 5,000
 *  characters. Currently, only filter expressions on the `filter_tags`
 *  attribute is supported.
 *  Examples:
 *   * `(filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))`
 *   * `(filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))`
 *  If `attributeFilteringSyntax` is set to true under the `params` field, then
 *  attribute-based expressions are expected instead of the above described
 *  tag-based syntax. Examples:
 *   * (launguage: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
 *   * (available: true) AND
 *     (launguage: ANY("en", "es")) OR (categories: ANY("Movie"))
 *  If your filter blocks all results, the API returns generic
 *  (unfiltered) popular Documents. If you only want results strictly matching
 *  the filters, set `strictFiltering` to `true` in
 *  RecommendRequest.params google.cloud.discoveryengine.v1beta.RecommendRequest.params 
 *  to receive empty results instead.
 *  Note that the API never returns
 *  Document google.cloud.discoveryengine.v1beta.Document s with
 *  `storageStatus` as `EXPIRED` or `DELETED` regardless of filter choices.
 */
// const filter = 'abc123'
/**
 *  Use validate only mode for this recommendation query. If set to `true`, a
 *  fake model is used that returns arbitrary Document IDs.
 *  Note that the validate only mode should only be used for testing the API,
 *  or if the model is not ready.
 */
// const validateOnly = true
/**
 *  Additional domain specific parameters for the recommendations.
 *  Allowed values:
 *  * `returnDocument`: Boolean. If set to `true`, the associated Document
 *     object is returned in
 *     RecommendResponse.RecommendationResult.document google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.document.
 *  * `returnScore`: Boolean. If set to true, the recommendation score
 *     corresponding to each returned Document is set in
 *     RecommendResponse.RecommendationResult.metadata google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.metadata.
 *     The given score indicates the probability of a Document conversion given
 *     the user's context and history.
 *  * `strictFiltering`: Boolean. True by default. If set to `false`, the
 *  service
 *     returns generic (unfiltered) popular Documents instead of empty if
 *     your filter blocks all recommendation results.
 *  * `diversityLevel`: String. Default empty. If set to be non-empty, then
 *     it needs to be one of:
 *      *  `no-diversity`
 *      *  `low-diversity`
 *      *  `medium-diversity`
 *      *  `high-diversity`
 *      *  `auto-diversity`
 *     This gives request-level control and adjusts recommendation results
 *     based on Document category.
 *  * `attributeFilteringSyntax`: Boolean. False by default. If set to true,
 *     the `filter` field is interpreted according to the new,
 *     attribute-based syntax.
 */
// const params = [1,2,3,4]
/**
 *  The user labels applied to a resource must meet the following requirements:
 *  * Each resource can have multiple labels, up to a maximum of 64.
 *  * Each label must be a key-value pair.
 *  * Keys have a minimum length of 1 character and a maximum length of 63
 *    characters and cannot be empty. Values can be empty and have a maximum
 *    length of 63 characters.
 *  * Keys and values can contain only lowercase letters, numeric characters,
 *    underscores, and dashes. All characters must use UTF-8 encoding, and
 *    international characters are allowed.
 *  * The key portion of a label must be unique. However, you can use the same
 *    key with multiple resources.
 *  * Keys must start with a lowercase letter or international character.
 *  See Requirements for
 *  labels (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
 *  for more details.
 */
// const userLabels = [1,2,3,4]

// Imports the Discoveryengine library
const {RecommendationServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// Instantiates a client
const discoveryengineClient = new RecommendationServiceClient();

async function callRecommend() {
  // Construct request
  const request = {
    servingConfig,
    userEvent,
  };

  // Run request
  const response = await discoveryengineClient.recommend(request);
  console.log(response);
}

callRecommend();

PHP

For more information, see the Vertex AI Agent Builder PHP API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\ApiCore\ApiException;
use Google\Cloud\DiscoveryEngine\V1beta\Client\RecommendationServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendRequest;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendResponse;
use Google\Cloud\DiscoveryEngine\V1beta\UserEvent;

/**
 * Makes a recommendation, which requires a contextual user event.
 *
 * @param string $formattedServingConfig Full resource name of a
 *                                       [ServingConfig][google.cloud.discoveryengine.v1beta.ServingConfig]:
 *                                       `projects/*/locations/global/collections/*/engines/*/servingConfigs/*`, or
 *                                       `projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*`
 *
 *                                       One default serving config is created along with your recommendation engine
 *                                       creation. The engine ID is used as the ID of the default serving
 *                                       config. For example, for Engine
 *                                       `projects/*/locations/global/collections/*/engines/my-engine`, you can use
 *                                       `projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine`
 *                                       for your
 *                                       [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend]
 *                                       requests. Please see
 *                                       {@see RecommendationServiceClient::servingConfigName()} for help formatting this field.
 * @param string $userEventEventType     User event type. Allowed values are:
 *
 *                                       Generic values:
 *
 *                                       * `search`: Search for Documents.
 *                                       * `view-item`: Detailed page view of a Document.
 *                                       * `view-item-list`: View of a panel or ordered list of Documents.
 *                                       * `view-home-page`: View of the home page.
 *                                       * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
 *
 *                                       Retail-related values:
 *
 *                                       * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
 *                                       * `purchase`: Purchase an item(s)
 *
 *                                       Media-related values:
 *
 *                                       * `media-play`: Start/resume watching a video, playing a song, etc.
 *                                       * `media-complete`: Finished or stopped midway through a video, song, etc.
 * @param string $userEventUserPseudoId  A unique identifier for tracking visitors.
 *
 *                                       For example, this could be implemented with an HTTP cookie, which should be
 *                                       able to uniquely identify a visitor on a single device. This unique
 *                                       identifier should not change if the visitor log in/out of the website.
 *
 *                                       Do not set the field to the same fixed ID for different users. This mixes
 *                                       the event history of those users together, which results in degraded model
 *                                       quality.
 *
 *                                       The field must be a UTF-8 encoded string with a length limit of 128
 *                                       characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 *
 *                                       The field should not contain PII or user-data. We recommend to use Google
 *                                       Analytics [Client
 *                                       ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
 *                                       for this field.
 */
function recommend_sample(
    string $formattedServingConfig,
    string $userEventEventType,
    string $userEventUserPseudoId
): void {
    // Create a client.
    $recommendationServiceClient = new RecommendationServiceClient();

    // Prepare the request message.
    $userEvent = (new UserEvent())
        ->setEventType($userEventEventType)
        ->setUserPseudoId($userEventUserPseudoId);
    $request = (new RecommendRequest())
        ->setServingConfig($formattedServingConfig)
        ->setUserEvent($userEvent);

    // Call the API and handle any network failures.
    try {
        /** @var RecommendResponse $response */
        $response = $recommendationServiceClient->recommend($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = RecommendationServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );
    $userEventEventType = '[EVENT_TYPE]';
    $userEventUserPseudoId = '[USER_PSEUDO_ID]';

    recommend_sample($formattedServingConfig, $userEventEventType, $userEventUserPseudoId);
}

Python

For more information, see the Vertex AI Agent Builder Python API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1beta


def sample_recommend():
    # Create a client
    client = discoveryengine_v1beta.RecommendationServiceClient()

    # Initialize request argument(s)
    user_event = discoveryengine_v1beta.UserEvent()
    user_event.event_type = "event_type_value"
    user_event.user_pseudo_id = "user_pseudo_id_value"

    request = discoveryengine_v1beta.RecommendRequest(
        serving_config="serving_config_value",
        user_event=user_event,
    )

    # Make the request
    response = client.recommend(request=request)

    # Handle the response
    print(response)

Ruby

For more information, see the Vertex AI Agent Builder Ruby API reference documentation.

To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the recommend call in the RecommendationService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend.
#
def recommend
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest.new

  # Call the recommend method.
  result = client.recommend request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse.
  p result
end