The Shopping Assistant
[playbook-based, prebuilt agent](https://docs.cloud.google.com/dialogflow/cx/docs/concept/playbook/prebuilt)
provides retail product queries, ordering, order status, and order cancellation.
It uses [Agent Search for Retail](https://docs.cloud.google.com/retail/docs) and
[custom fulfillment payloads](https://docs.cloud.google.com/dialogflow/cx/docs/concept/integration/dialogflow-messenger/fulfillment)
to provide a rich visual experience.

## Sample dialog

This sample dialog shows common scenarios that this prebuilt agent handles.

### Product and review comparison

1. The user asks to browse traditional sarees.
2. The agent presents some popular options and the user selects the first one.
3. The user asks for matching shoes.
4. The agent presents some popular options and the user asks to compare reviews and selects the highest-rated option.
5. The agent asks about the size and confirms the shoes were added to the cart.

| User Input | Agent Response |
|---|---|
| show me traditional sarees |   |
|   | \[Presents products\] Do any of these products catch your interest, or are you after different options? |
| 1st one is looking good |   |
|   | Great choice! The Indian beauty Self Design, Printed Fashion Georgette Sari is a beautiful piece. Since sarees are typically one size, it will fit perfectly. Would you like to add it to your cart? |
| do you have a matching heels with it? |   |
|   | \[Presents products\] Do any of these products catch your interest, or are you after different options? |
| yes but can you go through the customer review and pick the best one from these |   |
|   | The Flat n Heels Women Heels has an average rating of 4 out of 5 stars, while the Glitzy Galz Women Heels has an average rating of 4.5 out of 5 stars. Customers who purchased the Flat n Heels Women Heels had mixed reviews, with some finding them comfortable at first but uncomfortable after a few hours, while others praised their comfort. The Glitzy Galz Women Heels, on the other hand, received mostly positive reviews, with customers praising their fit, quality, and design. Which one would you like to add to your cart? |
| whichever has the best review and ratings |   |
|   | The Glitzy Galz Women Heels has the highest rating of 4.5 out of 5 stars. What size would you like to go with the Glitzy Galz Women Heels? We have sizes ranging from 5 to 11. |
| 6 |   |
|   | Perfect! The Glitzy Galz Women Heels in size 6 has been added to your cart with quantity 1. Is there anything else you'd like to add to your cart? |

### End-to-end shopping experience

1. The user browses the product catalog.
2. The agent presents recommendations based on the user's request.
3. After a few searches, the user finds an item to purchase.
4. The agent confirms the size and quantity of the item to purchase, and the expected delivery date.
5. The user requests a different delivery date, which isn't available, and agrees to the original delivery date.
6. The agent confirms the delivery, payment, and contact information on file.
7. The user updates the delivery information and confirms.
8. The agent places the order and provides the user with the order number.

| User Input | Agent Response |
|---|---|
| It is getting cold. Do you have good sweaters |   |
|   | \[Presents products\]. Do any of these products catch your interest, or are you after different options? |
| I like the women's sweater for my wife, but i am looking for a boy's sweater |   |
|   | \[Presents products\]. Do any of these products catch your interest, or are you after different options? |
| add the first women's sweater to the cart |   |
|   | What size would you like to go with the Nineteen Solid Round Neck Casual Women's Sweater? We have sizes ranging from extra small to extra-large. |
| medium |   |
|   | Perfect! The Nineteen Solid Round Neck Casual Women's Sweater in size medium has been added to your cart with quantity 1. Is there anything else you'd like to add to your cart? |
| no |   |
|   | The earliest we can get the Nineteen Solid Round Neck Casual Women's Sweater to you is by April 29, 2024. Does that work for you? |
| can you deliver it on April 28? |   |
|   | I'm sorry, but we're unable to deliver the Nineteen Solid Round Neck Casual Women's Sweater on April 28, 2024. The earliest we can deliver it is April 29, 2024. |
| ok keep the delivery date as it is |   |
|   | Alright, your Nineteen Solid Round Neck Casual Women's Sweater will be delivered on April 29, 2024. Now, let's review your profile details to ensure everything is up-to-date:\\ |
| Delivery Address: 638 Maple Street, Apt 11, Cupertino, CA 95014\\ |   |
|   | Payment Info: Visa ending in 4111 Contact Number: 416-555-5555 Email: email@example.com Please review these details. If everything is correct, simply confirm. If you need to make any changes, let me know. |
| my address has changed to 371 Talbot Street Carmichael, CA 95608 |   |
|   | Your delivery address has been successfully updated to 371 Talbot Street, Carmichael, CA 95608. Is there anything else you'd like to modify? |
| no |   |
|   | Your order for the Nineteen Solid Round Neck Casual Women's Sweater has been successfully placed with the order ID ee6b4cc7. It's scheduled for delivery on April 29, 2024. |
| thanks |   |
|   | Your order has been placed successfully! Is there anything else I can help you with? |
| no thanks |   |
|   | I'm glad I could help! If you ever need anything from Cymbal Apparel, I'm just a click away.\\ |

### Checking the status of an order

1. The user requests to check the status of an order.
2. The agent collects the order number and retrieves the order information.
3. The agent provides details about the items in the order and their expected delivery date.

| User Input | Agent Response |
|---|---|
| Hi |   |
|   | Feel free to select from the options above, or just type in what you're looking for and I'll assist you. |
| I want to check the status of my order |   |
|   | Sure, I can help you with that. To get started, can you please provide me with your order ID? |
| ee6b4cc7 |   |
|   | Your order is confirmed! It's currently being processed. Here's what you ordered: Nineteen Solid Round Neck Casual Women's Sweater Size: Medium Quantity: 1 Estimated Delivery: April 29, 2024 Is there anything else I can help you with? |
| No thanks |   |
|   | I'm glad I could help! If you ever need anything from Cymbal Apparel, I'm just a click away. |

### Returning an order

1. The user wants to return an order.
2. The agent collects the order number, retrieves the order details and confirms the item to be returned.
3. The agent initiates the return process and provides a return label for the user to print and attach to the package.

| User Input | Agent Response |
|---|---|
| Hi |   |
|   | Feel free to select from the options above, or just type in what you're looking for and I'll assist you. |
| I want to return my order |   |
|   | I'm here to help you with your return. To kick things off, could you please share your order number with me? |
| 0fc77d64 |   |
|   | Thank you for providing your order number. I've found your order placed on April 12th, 2024. The order contains a YK Printed Boy's Round Neck Dark Blue T-Shirt in size small. Is that the item you'd like to return? |
| yes |   |
|   | Alright, I've initiated the return process. You'll find the return label attached below. Please print it out and attach it to your package before sending it back. Is there anything else I can help you with? |
| No thanks |   |
|   | I'm glad I could help! If you ever need anything from Cymbal Apparel, I'm just a click away. |

## Basic setup

To set up this prebuilt agent:

1. [Import the prebuilt agent](https://docs.cloud.google.com/dialogflow/cx/docs/concept/playbook/prebuilt#import).
2. Configure the provided [tools](https://docs.cloud.google.com/dialogflow/cx/docs/concept/playbook/tool) with your external services. For more information, see [Tool setup](https://docs.cloud.google.com/dialogflow/cx/docs/concept/playbook/prebuilt/shopping-assistant#tool-setup).

## Tool setup

This agent includes [tools](https://docs.cloud.google.com/dialogflow/cx/docs/concept/playbook/tool) that are
used to integrate with external services. To configure these tools, follow
these steps:

1. Create a [Firestore database](https://docs.cloud.google.com/firestore/docs/manage-databases#create_a_database) named `apparel-db`.
2. Create a [Firestore Integration connector](https://docs.cloud.google.com/integration-connectors/docs/connectors/gsc_firestore/configure).
3. [Download](https://storage.googleapis.com/gassets-api-ai/prebuilt_agents/generative-prebuilt-agents/retail_assistant/apparel-search-prod-app-integration.json) the Application Integration for the Shopping Assistant.
4. Replace all references to `projects/customermod-genai-sa/locations/us-central1/connections/firestore` with the identifier of the connector created in step 2.
5. [Upload](https://docs.cloud.google.com/application-integration/docs/upload-download-integrations#upload-an-integration) and [publish](https://docs.cloud.google.com/application-integration/docs/test-publish-integrations#publish-integrations) the integration.
6. Grant the `Cloud Functions Invoker` role to your Dialogflow Service Agent.
7. Follow the steps to [set up your Retail catalog](https://docs.cloud.google.com/retail/docs/overview).
8. Update the [attribute controls](https://docs.cloud.google.com/retail/docs/attribute-config) to make the following fields retrievable: ageGroups, availability, categories, colorFamilies, colors, conditions, cost, currencyCode, description, discount, images, materials, patterns, price, sizes, title, URI.
9. [Import](https://docs.cloud.google.com/retail/docs/upload-catalog) the [sample catalog](https://storage.googleapis.com/gassets-api-ai/prebuilt_agents/generative-prebuilt-agents/retail_assistant/products.jsonl) into branch 1 of your catalog and make it the default branch.
10. Download the [Cloud Run Function](https://github.com/GoogleCloudPlatform/dialogflow-integrations/tree/master/dialogflow-prebuilt-agents/cloud-functions) and update `config.toml`.
11. Follow the steps to [deploy the Cloud Run Function](https://docs.cloud.google.com/functions/docs/deploy).
12. Grant the `Retail Viewer` IAM role to the Cloud Run Function you deployed.
13. For the following tools: `get-order-status`, `order-lookup`, `place-order` and `return-order`, update the `paths` property to reference the integration you created in step 5 in the OpenAPI specs and choose [Service Account authentication](https://docs.cloud.google.com/dialogflow/cx/docs/concept/playbook/tool#openapi_tool_api_authentication) with a service account to which you grant the `Application Integration Invoker` role.
14. Update the server URL property to the Cloud Run Function you deployed for the remaining tools.

### Search Products tool

The `search-products` tool retrieves the best-matched products based on the
search query and the offset value from the product catalog. The tool returns a
custom payload response which includes product details. This custom payload is
used by the UI to display the products in rich content form.

### Get Product Details tool

The `get-product-details` tool fetches product details from the product catalog
using the AI Commerce Search API. The system then transforms and returns the
retrieved product details in a simplified format, which the agent uses to answer
questions about the products it has shown the user.

### Get Reviews tool

The `get-reviews` tool retrieves reviews for products. It expects a list of
shown products and fetches reviews for each product. The generated reviews
are transformed into a custom template (`review_template`) format suitable for
display in a rich user interface.

### Similar Products tool

The `similar-products` tool facilitates the discovery of products similar to a
specified product using the Retail Recommendation API. It accepts a product ID
and uses the Retail Recommendation API to predict similar products from the
product catalog.

### Delivery Date tools

The `store-delivery-date` tool is responsible for storing the user's preferred
delivery date for items in the shopping cart that should be compared to the
earliest estimated delivery date.

The `get-delivery-date` tool estimates the delivery date for items in the
shopping cart.

### Get User Info tool

The `get-user-info` tool retrieves the user's personal information, including
shipping address, payment information, phone number, and email. The
`update-user-info` tool updates the user's information.

### Place Order tool

The `place-order` tool places an order for shopping cart items. It stores the
order data in Firestore, including the order ID, status, creation
timestamp, and product list, and then returns the order number to the agent.

### Order Lookup tool

The `order-lookup` tool fetches order data from a Firestore database
using the provided order ID and returns the order information to the agent.

### Return Order tool

The `return-order` tool updates the status of an order to "return_pending" in
the Firestore database, indicating that a return was initiated and is
pending.

### Get Order Status tool

The `get-order-status` tool fetches the status of an order and, if the order
ships, tracks it using the DHL API. It provides appropriate messages based on
the order status.

## Complete

Your agent and its integrations should now be set up and ready to test.