Building your AI assistant with actions

In AI assistant builder, an action represents a discrete outcome that you want your AI assistant to accomplish in response to a user's request. An action consists of steps, which are the predefined prompts for the conversation between a customer and the AI assistant. This conversation begins with the user input that starts the action (for example, I want to withdraw money). It might then include more exchanges as the AI assistant gathers more information, and it ends when the AI assistant completes the requested tasks or answers the customer's question.

You can use AI assistant builder to build AI assistant that act like a human personal assistant. You can build your AI assistant by creating AI-guided actions, skill-based actions, or custom-built actions.

The examples in this topic relate to a use case about building an action for money withdraw. Adapt the example values to build an action that fits your use case.

Creating an AI-guided action

You can create AI-guided actions to help your assistants to respond to a specific set of inquiries that are based on the preloaded knowledge and instructions.

To create an AI-guided action, do the following steps:

  1. Click the AI assistant builder tile in watsonx Orchestrate to go to AI assistant builder.

  2. In AI assistant builder, go to Actions > New action > AI-guided action.

  3. In the New action dialog, enter the phrase that the customer must type to start the interaction.

  4. Click Save.

  5. In the AI-guided action page, select the large language model (LLM) from the Select a model dropdown. 'Table 1. LLMs in AI Assistant Builder' shows the list of LLMs supported by AI Assistant Builder.

    LLMs in AI assistant builder
    LLM model Description
    ibm/granite-13b-chat-v2 The Granite 13 Billion chat V2 (granite-13b-chat-v2) model is the chat-focused variant initialized from the pre-trained Granite Base 13 Billion Base V2 (granite-13b-base-v2) model. granite-13b-base-v2 has been trained using over 2.5T tokens. IBM Generative AI Large Language Foundation Models are Enterprise-level English-language models trained with large a volume of data that has been subjected to intensive pre-processing and careful analysis.
    ibm/granite-3-8b-instruct Granite-3.0-8B-Instruct is a 8B parameter model finetuned from Granite-3.0-8B-Base using a combination of open source instruction datasets with permissive license and internally collected synthetic datasets. The model is designed to respond to general instructions and can be used to build AI assistants for multiple domains, including bussiness applications.
    ibm/granite-3-2b-instruct Granite-3.0-2B-Instruct is a lightweight and open-source 2B parameter model fine tuned from Granite-3.0-2B-Base on a combination of open-source and proprietary instruction data with a permissively licensed. The model is designed to respond to general instructions and can be used to build AI assistants for multiple domains, including bussiness applications.
    meta-llama/llama-3-1-70b-instruct The Meta Llama 3.1 collection of multilingual large language models (LLMs) is a collection of pretrained and instruction tuned generative models. Instruction tuned text only models are intended for assistant-like chat, whereas pretrained models can be adapted for a variety of natural language generation tasks. The Llama 3.1 model collection also supports the ability to leverage the outputs of its models to improve other models including synthetic data generation and distillation.
    meta-llama/llama-3-1-8b-instruct The Meta Llama 3.1 collection of multilingual large language models (LLMs) is a collection of pretrained and instruction tuned generative models. Instruction tuned text only models are intended for assistant-like chat, whereas pretrained models can be adapted for a variety of natural language generation tasks. The Llama 3.1 model collection also supports the ability to leverage the outputs of its models to improve other models including synthetic data generation and distillation.
    meta-llama/llama-3-405b-instruct Llama 3 is intended for commercial and research use in English. Instruction tuned models are intended for assistant-like chat, whereas pretrained models can be adapted for a variety of natural language generation tasks.
    meta-llama/llama-3-70b-instruct Llama 3 is intended for commercial and research use in English. Instruction tuned models are intended for assistant-like chat, whereas pretrained models can be adapted for a variety of natural language generation tasks.
    meta-llama/llama-3-8b-instruct Llama 3 is intended for commercial and research use in English. Instruction tuned models are intended for assistant-like chat, whereas pretrained models can be adapted for a variety of natural language generation tasks.
    mistralai/mistral-large Mistral Large 2 is a cutting-edge Large Language Model (LLM) that excels in reasoning, knowledge, and coding domains.
    mistralai/mixtral-8x7b-instruct-v01 The Mixtral-8x7B Large Language Model (LLM) is a pretrained generative Sparse Mixture of Experts.

  6. Optional: In the Add knowledge field, you can add a content, which is the knowledge reference for the AI-guided action. This knowledge is sent to the LLM along with the prompt.

    : You can concatenate the knowledge reference text with values of session variables. To do it, reference the session variable by using the ${} structure. For example, ${sessionVariable}. When you do it, make sure that the variable is not empty, otherwise the variable name is shown on the AI assistant chat.

  7. In the Add prompt instructions section, click the Add instructions button if you want to add instructions for the default prompt in your assistant.

  8. Enter the prompt instructions in the Prompt instruction field that help the LLM in your assistant to give refined responses and guide the conversations with clarity and specificity.

    : You can concatenate the prompt instructions text with values of session variables. To do it, reference the session variable by using the ${} structure. For example, ${sessionVariable}. When you do it, make sure that the session variable is not empty, otherwise the variable name is shown on the AI assistant chat.

Creating a skill-based action

Create an action from a skill when you want to implement orchestration for specific conversations in your AI assistant through the skills available on watsonx Orchestrate.

Tip:Skill-based actions, also known as conversational skill actions, are the skills that you add to AI assistants to implement orchestration for specific conversations.

Before you begin

Important:You must connect to the app of the skill for it to appear as an option in this step. For more information, see Managing connections.

Creating skill-based actions from skill flows require that you adjust the component skills of the skill flows to comply with the following criteria:

  • Conversational
    • By default all skills are conversational, unless the annotation x-ibm-conversational-skill is set to false.
  • Connected
    • All the component skills must be connected to the skillset.
    • wo-identity based Automation builder skill is considered to be connected by default.
  • Published
    • All the component skills must be published in the skill set.
  • Visible
    • By default, all skill flows created are allowed to use only visible skills.
Note:
  • Skill flows don't have the x-ibm-conversational-skill property to set them available as skill-based actions. Make sure that the component skills follow the previous criteria to turn skill flows eligible to create actions.
  • Skill-based actions don't support getting input values from other actions or mapping output values to other actions.
Information: Review the known issues and limitations for Skill-based actions.

Procedure

To create a skill-based action, do the following steps:

  1. Click the AI assistant builder tile in watsonx Orchestrate to go to AI assistant builder.

  2. In AI assistant builder, go to Actions > New action > Skill-based action.

  3. In the Build an action from a skill page, click the skill to which you want to link the action to, making the skill the foundation to your action.

    Important:You must connect to the app of the skill for it to appear as an option in this step. For more information, see Managing connections.

  4. In the Name your action field, enter a name for your action.

  5. In the Add action conditions, you can add or edit conditions for the action trigger.

    For more information, see Adding or editing conditions to trigger an action for skill

  6. In the Enter a phrase field, enter the phrase that customers must type or ask to trigger an action for the watsonx Orchestrate skill. For example, I want to pay my electricity bills.

  7. You use the following options on the upper-right corner of the page to improve the AI assistant experience:

    • Action response mode Defines the response mode for your AI assistant such as **Clarifying or Confident.

    • Action notes Opens the Action notes window to add a description, documentation, comments, or any other annotations to help you track your work as you build an action.

    • Action settings Opens the Action settings window to enable or disable Ask clarifying question and Change conversation topic configurations in action.

  8. Click the Save button to save the action.

Tip:When a user triggers a skill-based action, it can return the answer either as a form or as a multi-turn conversation. For more information about how to define how users interact with skill-based actions over the chat, see Defining how to prompt to a skill in a conversation

Creating a custom-built action

You create a new action from scratch when you want to define each step of your action in your conversation. You can define the steps with or without conditions, which help you to control the customer responses.

You can also use the AI-guided and skill-based actions that you created as subactions for your steps. Its enables to the possibility to pass generated values between these actions to use as you want. For more information about how to use AI-guided and skill-based actions as subactions, see Go to a subaction.

To create an action from scratch, do the following steps:

  1. Click the AI assistants tile in watsonx Orchestrate to go to AI assistant builder.

  2. In AI assistant builder, go to Actions > Create action > Custom-built action.

  3. In the New action dialog, enter the phrase that the customer must type to start the interaction. For example, I want to withdraw money.

    New action
    New action

  4. Click the Save button to save the new entry and build the action.

Initially, you need to specify only one example of typical user input that starts the action. You can add more examples of user input later.

Defining steps in an action

An action consists of one or more steps. The steps in an action form a sequence of prompts that define the conversation turns with the user after the input of the action triggering phrase. In a simple case, a step might consist of a direct answer to a question from the customer. For example, if the customer asks What are your business hours?, an AI assistant with a single-step action replies with We are open Monday through Friday from 9 AM to 5 PM..

An action requires multiple steps to fully understand the customer's request. For example, for the user input I want to withdraw money, AI assistant requires the following additional information:

  • Which account should the money come from?
  • What is the amount to withdraw?

Each of the follow-up questions represents a step in the action.

In AI assistant builder, you can add, edit, or duplicate steps in an action. Within a step, you define the following things:

  • A step title that describes what the step does. The step title is optional.
  • Any conditions that determine whether the step is processed at run time. (By default, a step is always processed if the user input matches.)
  • What the assistant says to the customer when the step is processed.
  • Rules for how the customer can reply to what the assistant says (if any response is expected).
  • What to do after the step finishes.

See the following topics for more information about adding, editing, and duplicating steps in action:

Adding a new step

After entering the phrase to start the interaction, you must add steps in an action to create the conversation flow. To add a step, use the following instructions:

  1. In AI assistant builder, go to Home>Actions.

  2. Click the New step button in the Conversation steps pane to add a step.

Editing a step

Action editor showing parts of a step
Step

  1. Click the Edit step title icon and enter the title Determine account.

  2. In the Is taken field, use the default value of without conditions. This step is always required for any withdrawal.

  3. In the Assistant says field, type Withdraw from which account?.

  4. Click Define customer response.

    Defining the customer response for a step
    Define customer response

    Because we are asking the user to select from a list of predefined choices, click Options. The Edit Response window opens.

  5. In the Option 1 field, type Savings. When you enter a value for option 1, a field appears for option 2.

    Editing an Options response
    Edit response

    Click Option 2 and type Checking.

    Click Apply to save the customer response.

  6. Now we can check that the step works like we expect. Click Preview to open the Preview pane, and type I want to withdraw money:

    Previewing action with one step
    Preview

    As expected, the assistant now prompts you to select the account you want to withdraw money from.

Duplicating a step

Duplicate a step if you want to create a step similar to another one but with minor modifications.

Complete the following steps to duplicate a step:

  1. Click the Duplicate icon on the step that you want to duplicate.

    Duplicate button on a step
    Duplicate icon

    A step appears immediately following the step that you duplicated. This step is identical to the duplicated step and displays a blue circle in the upper right to indicate that the step is a duplicate.

    Duplicated step
    Duplicated step

  2. Edit the information in the new step as necessary.

Adding conditional steps

Suppose our bank charges a fee for withdrawals from checking accounts, and we need to confirm that the customer understands. Our action needs to have slightly different behavior depending on which kind of account the customer selects. We can handle this using step conditions.

When a step asks for information from the user, the user's response is stored as an action variable. By referring to the action variables stored by previous steps, you can construct step conditions based on your customer's previous responses.

  1. Click New step.

  2. In the Step 2 is taken field, select with conditions. The Conditions section expands.

    Action editor: specifying conditions
    Conditions

  3. By default, a condition is automatically created based on the action variable that is stored by the previous step (Withdraw from which account?). However, by default it is checking for a value of Savings, which is not what we want. Click the value field and select Checking instead.

    Editing a condition to select Checking as the value to check for
    Edit condition

  4. In the Assistant says field, type Withdrawals from checking accounts might incur a fee. Do you want to continue?

  5. Click Define customer response and select Confirmation, which has the choices Yes and No.

    Click Apply to save the customer response.

  6. Because we want to make sure that the customer always agrees explicitly, click the Settings icon to open Customer response settings, then select Always ask for this information, regardless of earlier messages.

    Customer response settings
    Customer response settings

Now we need another conditional step to handle the situation where the customer decides not to continue.

  1. Click New step.

  2. In the Step 3 is taken field, select with conditions.

  3. Edit the condition so it checks that the customer's response to step 2 was No.

    Action editor: specifying conditions
    Edit conditions

  4. In the Assistant says field, type Canceling transaction..

  5. In the And then field, select End the action. If this step is executed (meaning that the customer decides not to proceed), no subsequent steps in the action are executed.

We don't need a conditional step to handle a response of Yes in step 2 because in that situation processing just continues as normal.

Using the action editor

When you create the action, the action editor opens.

Action editor showing newly created action
Action editor

The editor window shows the parts of an action:

  • The Customer starts with: tile shows the customer input that starts the action. You can click this tile to edit the example text or add more examples, but we'll leave it as is for now.

  • Under Conversation steps, you can see the steps that make up the action. A step is an interaction between the assistant and the customer; steps are executed in order, from first to last. You can reorder the steps in an action by clicking and dragging steps in the list.

  • The Preview button opens a pane that shows you how the assistant responds to customer input. You can preview the assistant at any time to see the effect of changes you make.

  • The Action notes icon opens an area where you can add a description, documentation, comments, or any other annotations to help you track your work as you build an action.

The action editor supports basic Markdown syntax.

Visualizing the flow of the action

After you created an action from scratch, you have the option to switch between the Edit tab and the Visualization tab. Go to the visualization tab to view the action's flow chart.

Editor
Editor

While you are viewing the flow chart of the action, you are able to zoom and pan around the canvas.

Visualization
Visualization

Getting the amount

We need one more piece of information before we can complete the customer's request: the amount of money to withdraw.

  1. Click New step.

  2. In the Assistant says field, type How much do you want to withdraw?.

  3. Click Define customer response. We need the customer to specify a monetary amount, so select Currency.

Finishing the action

We now have all the information that we need. For our example, we're not going to implement any real logic for making a withdrawal, but we can send a final message to summarize what we're doing.

To do this summary, we need to insert action variables (representing customer responses from previous steps) into our response. At run time, these action variables are replaced with the actual values that are supplied by the customer.

  1. Click New step.

  2. Now we need to build a confirmation message that says "OK, we will withdraw amount from your account_type account."

    To create this response, type the text of the message in the Assistant says field, but in place of the variable values, click the Insert a variable Action variable icon icon to insert references to action variables:

    • For amount, select 4. How much do you want to withdraw?.
    • For account_type, select 1. Withdraw from which account?.

    Action editor: message including variable references

  3. Because this is the last step in the action, you don't need to specify any customer response.

If you decide a step is no longer needed, you can delete it from the action. To delete a step, click the Delete icon on the tile for the step.

Testing the action

We can now test the action to make sure it's working. Click Preview to open the Preview pane. (If the text from a previous test is still shown, click the Refresh icon to restart the conversation.)

Start by typing I want to withdraw money. Try various permutations of your input to test how the assistant behaves:

  • Try selecting both Savings and Checking. Confirm that if you select Checking, the assistant warns you about incurring a fee and asks if you want to continue, but if you select Savings, it proceeds without the warning.

  • When you select Checking, try both responses when the assistant asks if you want to continue. Confirm that if you select No, the action ends.

  • Try including additional information in your initial message. For example, try typing I want to withdraw $50 from my savings account. Confirm that the assistant does not ask you again to specify the information you already provided.

That's it! You built a simple action that includes multiple steps, collects information that it stores as action variables, and conditions its responses based on what your customer chooses. There is a lot more you can do with actions, but all of it is built on this basic pattern.