Scenes

In combination with intents, scenes are the other major building block of your conversation model. Scenes represent individual states of your conversation and their main purpose is to organize your conversation into logical chunks, execute tasks, and return prompts to users.

Some features of scenes include:

  • Looped execution - Scenes execute within a loop until it meets transition criteria that you define. This lets you create control logic flows much more efficiently within a single scene.
  • Dialog separation - In combination with intents, scenes let you group dialogs into logical chunks, giving you easy ways to build user request and Action response pairs.
  • Intent match scoping - Because only one scene can be active at a time, you can scope intent matching to scenes of your choice and have them match only when those scenes are active.
  • Slot filling - You can use slot filling within a scene to collect multiple pieces of typed user input, without having to create multiple intents
  • In-scene conditions - You can check slots, session, user, and home storage to carry out simple, conditional logic without triggering a webhook.

You can define scenes as part of your conversational model as a custom scene. The conversational logic of Assistant also includes system scenes that provide standard functionality for your conversation.

Custom scenes

A custom scene is a building block of conversational logic that forms a part of your Action's conversation model. Custom scenes have stages that define how and when it starts, called the Activation, the conversational processing it performs, called the Execution lifecycle, and how the scene ends, called the Transition:

  • Activation - Before a scene can execute, you must activate it through a global intent match or scene transition.
  • Execution - When a scene is active, it executes in a well-defined lifecycle that lets you carry out a variety of tasks such as slot filling, conditional checking, prompt generation, and triggering webhook events.
  • Transition - When a scene meets criteria that you define, such as matching an intent or completing slot filling, you can transition to another scene to carry out even more logic. Alternatively, you can transition to the End conversation system scene, which ends the conversation with the user.
Figure 1. A common scene transition. A global intent activates a scene during invocation, the scene consumes user input and matches an intent, which transitions and activates another scene.

Activation

Before a scene can execute, it needs to be active. Only one scene can be active at any time. You can activate scenes in the following ways:

  • Invocation - When user input matches a global intent's language model, you can activate a scene to process the invocation.
  • Static scene transition - When a scene meets transition criteria, you can define a transition to another scene.
  • Dynamic scene transition - Within a webhook handler, you can programmatically transition to another scene.

Execution lifecycle

When a scene is active, it executes within a well-defined lifecycle that loops until the scene meets transition criteria that you set. A scene's execution lifecycle is separated into optional stages that run in the following order:

  1. On enter - This stage runs only once when a scene is activated. You can trigger a webhook or prompt the user to do one-time setup of your scene.

  2. Conditions - Conditions lets you evaluate certain criteria before advancing lifecycle stages, triggering a webhook, or sending prompts. This stage can define transition criteria to exit the execution loop.

  3. Slot filling - A scene can automatically prompt users until it collects all required slots (typed data). A scene prompts for a single slot each time through its execution loop. If any slots are missing, the scene's lifecycle eventually loops back to the slot filling stage and prompts for the next required slot. This stage can define transition criteria to exit the execution loop.

  4. Prompts - Assistant delivers the prompt queue to the user and clears the queue. The prompt queue is the merged collection of prompts that were aggregated since the last time this stage cleared the queue.

  5. Input - Assistant consumes and returns user input to your scene, so you can process it, which might include intent matching (global intents or user intents within a scene), continuing slot filling (if it isn't complete), or handling no match or no input errors. This stage can define transition criteria to exit the execution loop. If it doesn't transition, the execution loop returns to the conditions stage.

Figure 2. Scene execution lifecycle

The following sections describe each lifecycle stage in more detail.

On enter

On enter is the only stage that doesn't execute in a scene's execution loop. It does one-time initialization of your scene in the following order:

  • If the Assistant runtime can fill any slots from a previously matched intent, it does so now to prepare the scene for the slot filling stage. For example, some user input might match an intent and provide a slot. That intent match activates a scene and can fill a slot in a scene if the slot names match.
  • If a webhook is enabled, it triggers an event synchronously and waits for your web service to return a response.
  • When the runtime receives a webhook response, it resolves any parameter references in prompts and selects a prompt candidate based on the user surface and then selects one variant for the candidate to send to the user later.
  • If the webhook response contains a prompt, it adds it to the prompt queue. If a static prompt also exists, the webhook prompt is merged into the prompt queue first, followed by the static prompt.
  • If the webhook response contains a transition, it does so now. If not, the scene continues to the slot filling stage.

Conditions

Conditions lets you check session, user, or slot data for a condition to be true. For example, you can check to see if all slots are filled and set that as a criteria to transition to another scene to process the slots.

  • The Assistant runtime evaluates each condition in the order that they're specified. The first condition that evaluates to true executes the associated handler and stops conditions evaluation.
  • A condition else if scene.slots.status = "FINAL" is automatically added to the condition list if you do slot filling. This optional condition checks for slot filling to be complete and can trigger a webhook or add prompts to the prompt queue.

After condition evaluation, if the scene doesn't define a transition, it continues to slot filling.

Slot filling

This stage adds a slot prompt for a single, unfilled and required slot. If you don't define any slots in the scene, this stage does nothing.

  • The Assistant runtime selects the first unfilled slot and adds the corresponding prompt to the prompt queue. Because the scene's execution loops, additional, unfilled slots are handled later when the execution loop returns to this stage.
  • The current, active slot can have error handling prompts that override the ones defined in the scene's input stage.
  • When the user fills a slot, you can validate it in a web service by triggering a webhook.

Prompts

The Assistant runtime delivers the prompt queue to the user, clears the queue, and consumes user input.

Input

The Assistant runtime tries to match the input to an intent or a slot:

  • In the case of a user intent match, the scene executes the associated intent handler (user or system intent). A scene's intent handler takes precedence over any global intents. If you didn't define a transition, the scene execution loops back the conditions stage.
  • In the case of a slot match, the scene returns to the slot filling stage.
  • In the case of a system intent match (for example, no input or no match), you can add prompts to the prompt queue, trigger a webhook, or transition. In the event of multiple no match prompts defined, the Assistant runtime chooses the most relevant, in the following order: slot filling, scene, then global no match prompts. Consecutive no matches generate a corresponding event:

    • no_match_1
    • no_match_2
    • no_match_final

    Each level of no match (slot filling, scene, and global) can trigger webhook events. By default, the third and final no match ends the conversation.

Transition

Transitions can happen in the following stages:

  • Conditions - You can transition to another scene based on conditions you define. A common condition to check for is slot filling to be complete.
  • Input (user intent matching) - If an intent matches, it can trigger a transition to another scene.
  • Input (system intent matching) - You can trigger webhooks during any system intent match event. For no match and no input events, the scene, by default, transitions to the End conversation scene after three occurrences.

System scenes

System scenes let you use built-in, conversational logic provided by Assistant, which lets you add standard conversational flows to your user experience. For example, the account linking system scene lets Assistant momentarily take over to carry out the account linking flow, returning the information you need to actually link the user's accounts. System scenes don't follow the standard scene lifecycle.

The following list describes supported system scenes and how to use them:

  • End conversation - Closes the mic and ends the conversation with the user. The Assistant takes back control of the user experience after this scene executes.
  • Account linking - Guides the user through an account linking flow and provides your Actions the required information to link the user's account on your backend servers with the user's Google account. See the account linking documentation for more information on how to use this scene.
  • Daily updates - Guides the user through a confirmation flow to add your Actions to a user's daily updates. See the daily updates documentation for more information on how to use this scene.
  • Notifications - Guides the user through a confirmation flow to receive notifications from your Actions. See the push notifications documentation for more information on how to use this scene.