Some products and features are in the process of being renamed. Generative playbook and flow features are also being migrated to a single consolidated console. See the details.

Playbook examples

Each playbook should have one or more examples. These examples are sample conversations between an end-user and the playbook, including the dialogue and actions performed by the agent. These are effectively few-shot prompt examples for the LLM.

The console provides an interface for you to enter actions.

Multilingual agents

If you want your agent to handle multiple languages, your examples should use each of the languages.

Example input summary and output summary

In addition to input and output parameters, playbooks support receiving an input summary and emitting an output summary for exchanging information with other playbooks. Summaries are helpful for passing abstract contextual information between playbooks, while parameters are more helpful for passing structured, well defined fields between playbooks. Parameters are the only way to exchange data between flows and playbooks.

Add relevant input summaries to examples to condition the playbook to adjust its actions based on the input summaries at runtime. Add output summaries including relevant, accurate details about the example conversation to show the playbook what details are important to summarize.

Example state

At a given point in the conversation, a playbook will be in one of the following states:

OK: The playbook successfully achieved its goal and control will now transfer to the parent playbook.
CANCELLED: The user decided not to proceed with the goal assigned to the playbook. The control will now transfer to the parent playbook. If the parent playbook is a CX flow, intent of the user input will be detected before the flow runs.
FAILED: The playbook cannot proceed with the goal due to some error (e.g. tool returns 500 error). The session will end with status fail. An EndInteraction message will be added to the response.
ESCALATED: The playbook decided that it cannot achieve the goal and needs to escalate the situation to a human. The session will end with status escalated. An EndInteraction message will be added to the response.
PENDING: The conversation is still continuing within the playbook.

The top-level example and its playbook invocations should be denoted with a state which corresponds to the playbook they are referencing.

Selection strategy

The selection strategy setting controls whether an example is included in the playbook's prompt sent to the LLM. The following options are available:

Dynamically select: The example is conditionally included, based on how relevant it is for the current conversation context. The example may be omitted if the prompt is approaching the token limit. You can optionally provide word matches.
Always select: The example is always included, regardless of the conversation context. The example may be omitted if the prompt is approaching the token limit.
Never select: The example is never included in the prompt. The example will have no effect on the playbook's performance. This setting is useful for temporarily excluding an example for testing.

Word matches

You can optionally provide word matches for examples with a dynamic selection strategy. This lets you gain better control over whether the example is included in the prompt. This is recommended for playbooks that have more than 100 examples.

You can provide multiple match expressions as simple words to match or regular expressions, and each match expression can be one of the following types:

user: Matches are checked against end-user messages.
agent: Matches are checked against agent messages.
any: Matches are checked against end-user and agent messages, as well as actions.

When checking for a match, expressions are matched against at most the latest 5 conversational turns and the first end-user message.

If a match is found for the example, the example is prioritized over other dynamically selected examples without word matches.

The format for word matches is a comma separated list, where each expression starts with the expression type and a colon. For example:

user:red,agent:blue,any:placeOrder

These would match if any of the following are true:

An end-user message contains red.
An agent message contains blue.
Any message contains or action matches placeOrder.

Add action

An example provided within a playbook consists of a series of actions. These actions may vary in their combinations, but they primarily depict the interaction between the user and the playbook, along with the actions taken in between to fulfill the user's query or requirements.

There are two ways to add actions to an example:

To add an action manually, click the + button at the bottom of the right pane or the Add action button when you hold the pointer over existing actions. You can use these options when you create a new example by clicking the + Example option or when you edit an existing example.
To generate actions automatically based on the existing playbook instructions, enter a user input in the Enter user input field at the bottom of the right pane. You can use this option when you create or edit an example. Alternatively, you can use this option when you test your playbook at runtime in the Preview playbook pane on the right. To save actions to an example from the Preview playbook pane, click Save example after selecting the playbook invocation from the invocation list on the left of the Preview playbook pane.

Make sure to check the automatically generated actions correctness and edit them if necessary. This is especially important for the playbooks with few or no examples.

The following types of actions are supported by the playbook:

Playbook response

The playbook response to the user query.

User input

The user query.

Tool use

This is a tool invocation to get additional information needed to fulfill the user's query. This action should specify the following details:

Tool: Name of the tool that should be invoked.
Action: Name of the operation for the OpenAPI tool that should be invoked. For data store tools and function tool, the action name is the same as the tool name.
Tool input: Inputs to be included in the tool call. These are usually derived from the previous conversation turns with the user.

For Open API tools, requestBody JSON is required for POST, PUT and PATCH method types.

Sample Open API tool requestBody input for createPet action:
```
{
  "id": 1,
  "name": "Luna"
}
```
For data store tool, the sample requestBody where the query is required and other fields are optional.
```
{
  "query": "Where is my nearest store?",
  "filter": "country: ANY(\"United States\")",
  "userMetadata": {
    "userCity": "San Fransisco",
  },
  "fallback": "We don't have any stores in your area."
}
```

Tool output: The response of the tool invocation. This is a valid JSON response from the tool to the given input. For Open API tools, it can also be a string error (for example, "404 Not found").

Sample Open API tool output for listPets action:

{
  "pets": [
    {
      "id": 1,
      "name": "Luna"
    },
    {
      "id": 2,
      "name": "Charlie"
    }]
}

Sample Data store tool output:

{
  "answer": "Here's the address to your nearest store ...",
  "snippets": [
    {
      "title": "San Fransisco Downtown",
      "uri": "https://www.example.com/San_Fransisco_Downtown",
      "text": "Address for San Fransisco Downtown .."
    }
  ]
}

To ensure the playbook is fail-safe, also include examples of how the playbook should respond when tool invocation fails. Open API tool invocation failure can be represented as an error string ("404 not found") in the tool output. For data store tools the fallback input can be used to specify how to respond if there is no summarized answer.

If you want your data store tool to include URI in the playbook response, add examples which contain the URI you want the playbook to respond with. If this URI is coming from the data store tool, then the data store tool output should contain a URI which matches the URI in the playbook response. Note fallback cannot be used in this scenario because it will disable the capability of the LLM playbook to rephrase the data store tool answer to include URIs in playbook response.

Examples containing tool use actions can get quite verbose and contribute to increased input token limit consumption. To ensure efficient use of tokens, ensure that tool outputs are concise and contain information relevant to the playbook's goals. For data store tools, consider removing snippets from examples as they can contribute to high input token consumption.

Playbook invocation

This action is used when the playbook should invoke another playbook to fulfill the user query. This action should specify the following details:

Playbook: Name of the playbook to be invoked.
Playbook invocation input summary: A summary of the relevant portions of the preceding conversation useful to the playbook being invoked.
Input parameters: Input parameters to pass to the playbook
Playbook invocation output summary: A summary of what the playbook should generate upon completion of its goal.
Output parameters: Output parameters generated by the playbook upon completion of its goal.

Playbook instructions

Playbook parameters