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 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 Conversational Agents console:

   Conversational Agents console

2. If you haven't already, select or create a project.

3. Click Create agent.

4. Click Build your own.

5. Provide "Shirt Ordering - Playbooks" for the agent name.

6. Provide a location.

7. Provide a time zone.

8. Provide a default language.

9. Select Playbook for the Conversation start option.

10. Click Create.

11. The user interface takes you to the default playbook named Default Generative Playbook.

12. 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. Select the Task playbook option.
3. Enter the playbook name: Order.

4. 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.
   

5. 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.
   

6. Click Save.

7. 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. Select the Task playbook option.
3. Enter the playbook name: Information.

4. 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.
   

5. 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.
   

6. Click Save.

7. 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 ${PLAYBOOK: Information}
   - If the customer wants to purchase a shirt,
     route them to ${PLAYBOOK: Order}
   

4. Click Save.

5. Note that the playbook references are highlighted because there are no examples yet. These will be added in the next section.

6. 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.
2. Click the simulator question_answer button in the top row navigation.
3. For resource, select the default playbook.
4. Use the default model or select an alternative.
5. In the text box that says Enter user input, type Hello, then press enter.
6. The playbook responds with a greeting.

To save this conversation as an example:

1. Select the default playbook in the Invocations dropdown.
2. Click the Save as example button near the top right of the interface.
3. The example editor panel opens. You can use this editor to add, edit, delete, or reorder actions.
4. Provide the example name: Greeting.
5. Update the playbook responses as necessary.
6. Scroll down to the End example with output information and enter The user is greeted. in the Summary section.
7. Click the save icon.

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.
2. If necessary, reset the conversation with the reset restart_alt button.
3. Select the information playbook in the simulator Start Resource dropdown.
4. Enter the message: Where are you located?.
5. The playbook responds with a location.
6. Select the information playbook in the Invocations dropdown.
7. Click the Save as example button.
8. Provide the example name: Location.
9. Before saving this conversation as an example, you must delete the action that contains "Where are you located". Only the default playbook examples can start with a user action.
10. To provide the example with the context that started the conversation, expand the Summary of the preceding conversation... section and enter the following in the Starts example with input information field: The customer asked "Where are you located?".
11. To provide the example with the context that completes the conversation, expand the Summary of the playbook execution... section and enter the following in the End example with output information field: The store is located at 1007 Mountain Drive, Gotham City, NJ..
12. Click the save icon.

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

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.