Build an agent using playbooks

This guide shows you how to build and test a simple shirt ordering agent using playbooks. When interacting with this agent, you can ask for the store location, get store hours, or make a shirt order.

Before you begin

You should do the following before reading this guide:

  1. If you have not already, follow the Dialogflow setup instructions.

About playbooks

An agent is composed of one or more playbooks. Each playbook has a clearly defined and limited scope. A playbook has the following data:

X Item
Name A name used to identify the playbook.
Goal Goals are high level descriptions of what the playbook should accomplish.
Instructions Instructions are high level steps that should be taken to accomplish the playbook's goal.
Examples Examples are sample conversations between an end-user and the agent. These examples are effectively few-shot prompt examples for the LLM.

Create the agent

To create the agent:

  1. Go to the Agent Builder console:

    Agent Builder console

  2. Select your project from the console drop-down.

  3. If you have not already activated the API, read and agree to the Terms of Service, then click Continue and activate the API.

  4. Click Create a New App or New App.

  5. Select Agent.

  6. Provide "Shirt Ordering Assistant" for the app name.

  7. Select a region.

  8. Click Create.

  9. The user interface takes you to the default playbook named Default Agent.

  10. Click the back button to see the list of playbooks.

Create the order playbook

The Order playbook handles shirt orders. To create this playbook:

  1. Click Create.
  2. Enter the name: Order.
  3. Enter the following goal:

    You are a shirt store ordering assistant. Help customers purchase shirts.
    Help the customer choose a size and color.
    The shirts come in small, medium, and large.
    The shirts can be red, green, or blue.
    
  4. Enter the following instructions:

    - If the customer has not provided a size, ask them to choose a size.
    - If the customer has not provided a color, ask them to choose a color.
    - Once the customer has selected a size and color for the shirt,
      repeat the selection to the customer, and ask them to confirm the selection.
    - Once the customer has confirmed their selection,
      let them know that the shirt is now ordered.
    - Do not provide prices or collect payment.
    - Do not collect the customer's name or address.
    
  5. Click Save.

    Screenshot of order agent

  6. Click the back button to return to the playbook list.

Create the information playbook

The Information playbook handles questions about the store. To create this playbook:

  1. Click Create.
  2. Enter the name: Information.
  3. Enter the following goal:

    You provide information about a shirt store.
    The store is open between 8 AM and 6 PM every day.
    The store is located at 1007 Mountain Drive, Gotham City, NJ.
    
  4. Enter the following instructions:

    - If the customer asks for the store location, provide them with the address.
    - If the customer asks for the store hours, provide them with the hours.
    
  5. Click Save.

  6. Click the back button to return to the playbook list.

Update the default playbook

When you first created the application, a default playbook was created for you. This playbook should steer the conversation to the appropriate playbooks with specific goals. In the instructions below, you can see how the default playbook references the other playbooks. To update this playbook:

  1. Click the default playbook. This playbook has a highlighted star.
  2. Enter the following goal:

    You are an assistant for a shirt store.
    Your name is "Samantha".
    Your job is to direct customers to other playbooks based on the customer's questions.
    
  3. Enter the following instructions:

    - If the customer hasn't been greeted yet, greet the customer,
      introduce yourself, and ask the user how you can help.
    - If the customer wants information about the store,
      route them to ${AGENT: Information}
    - If the customer wants to purchase a shirt,
      route them to ${AGENT: Order}
    
  4. Click Save.

  5. Click the back button to return to the playbook list.

Provide examples

At this point, your playbook is functional. However, You must provide examples to ensure quality responses.

You can manually provide examples from the Examples tab when you have a playbook open. However, it is often easier to have a conversation with the functioning playbook and save the conversation as an example.

An example conversation with a default playbook is short. This playbook just needs to direct you to another playbook. To have a conversation with the default playbook:

  1. Close or cancel any panel that might be present on the right side of the screen. You want to see the simulator panel that contains Send a message to see how your agent responds.
  2. Select the default playbook.
  3. Select the model: gemini-pro.
  4. In the text box that says Enter user input, type Hello, then press enter.
  5. The playbook responds with a greeting.

To save this conversation as an example:

  1. Click the Save example button near the top right of the interface.
  2. The example editor panel opens. You can use this editor to add, edit, delete, or reorder actions.
  3. Provide the example name: Greeting.
  4. Update the playbook responses as necessary.
  5. Click Save.

    Screenshot of greetings example

Add a location example for the information playbook:

  1. Close or cancel any panel that might be present on the right side of the screen. If necessary, reset the conversation with the reset restart_alt button.
  2. Select the information playbook.
  3. Select the model: gemini-pro.
  4. Enter the message: Where are you located?.
  5. The playbook responds with a location.
  6. Save this conversation as an example named Location. Only the default playbook examples can start with a user action, so you must delete the action that contains "Where are you located". Enter the Preceding conversation context summary: The customer asked "Where are you located?". Enter the Example execution summary: The store is located at 1007 Mountain Drive, Gotham City, NJ.

Add an hours example for the information playbook:

  1. Similar to steps above, but enter the message: What are your hours? and name the example: Hours.

Add a selection example for the order playbook:

  1. Similar to steps above, but name the example Selection, select the order playbook, and send the following messages:

    • I want to buy a shirt
    • Large
    • Green
    • Yes

    Screenshot of example entry

Test the agent

Your agent is now ready to test. Open the simulator panel and have a conversation with the agent. You do not need to have the same conversations as above. For example, you can ask this agent which colors are available for shirts. If you are not getting the desired behavior, refining your examples and creating new ones will improve responses.

Interacting with the agent using the API

See Interactions with the API.