Creating your own assistant tools

The best thing about Flow XO AI Assistants is their ability to use various "tools" to interact with the Flow XO and the outside world. Flow XO comes with a variety of useful built in tools, but if you want to take your assistants the next level, you'll eventually want to create your own tools to utilize your own data sources, send e-mails, etc. 

Creating custom Flow XO tools is very easy - it's just a matter of building a Flow and registering the flow as a tool with your assistant.

in this article, we'll create two custom tools that together implement an "Email Verification" system that our business can use to validate that a user owns a particular e-mail address using the familiar method of sending a code to a user's email and verifying that they give us back the same code.

Although our main goal is to demonstrate how to create custom tools, adding this ability to your bot can be extremely useful to validate that a user in your conversation is who they say they are, so that you can safely show them their account data from your back end systems or CRM, or allow them to access workflows that modify their account with you.

First, let's summarize the steps to building a custom assistant tool:

  1. Create a flow with "New Trigger" trigger
  2. Add some logic to your flow to do something useful. This can be anything.
  3. Use the "Set Outputs" task to define what data will get sent back to the assistant.
  4. In your assistant, create a new tool and associate it with your new flow
  5. Add some instructions to your assistant to let it know how to use the tool, as needed

First, let's create a simple assistant that we can use to test our our tools. We'll create a "Verify Email Address" assistant and give it some instructions. We'll use this assistant to test our our tools, but me might want to keep it around as a "component" or tool in and of itself. This is because entire assistants can ALSO be used as tools, meaning that if we have several other assistants, say a Customer Service assistant and a Lead Qualification assistant, and each assistant needs to verify email addresses, we can avoid having to build the same logic in each assistant by simply adding our Email Verification assistant as an available tool to each of our main assistants. Pretty elegant!

Ok then, this is what our Verify Email Address assistant looks like:

If you want to copy and paste the instructions, here they are in text format: 

# GOAL
The user has verified their email address, or failed to verify the email address, and you have noted the outcome as an output field.

# PERSONA
You are an email verification specialist. Your ONLY job is to validate that a user owns the email address they are claiming. You are polite and friendly, but very efficient and serious about your job. You don't engage in smalltalk, you don't participate in off topic discussions - you are laser focused on verifying the email address of the current user.

# INSTRUCTIONS
1. If you don't know the user's email address, ask them for it, otherwise go to step 2
2. Send the user an authorization code
3. Ask the use to enter the authorization code
4. Verify the authorization code
5. If the authorization code was verified, you are done, otherwise go to step 6
6. Ask the user to re-enter their authorization code
7. Go to step 4. After two tries, go to step 8
8. The authorization has failed

# USER DESCRIPTION
Email: {{user.email}}
Preferred Language: {{user.language}}

Most of the Assistant description is self explanatory (one of the great things about assistants is how easy it is to understand what they do - it's just written in plain language!), but I want to call out a few aspects that may be less obvious.

  • We are using GPT-4 Turbo rather than GPT 3.5. In our tests GPT 3.5 worked OK, but for something like this, where it is rather important that the assistant follow the logic you define exactly, GPT 4 Turbo will be much more reliable. You should experiment both both models to determine which works best for you.
  • We added an output field, of type True/False, called "emailVerificationSucceeded". This is useful in case we decide to use this assistant later from another assistant as a tool, so that the first assistant knows the outcome of the process and can take action accordinglky.
  • The User Description section, which is entirely optional, as two elements. One is to provide the email in case we already have it associated with our user. The other is to provide the language (which we get whenever possible from the messaging channel, such as the Web bot or Telegram, etc) so that our assistant will speak the users native language from the get go if it can. If you want to see what variables are available (and you can add variables like this in Goal, Persona, Instructions OR User Description) read more here.

If we try to use this assistant now, it won't work, because the assistant doesn't know how to "Send a user an authorization code" nor does it know how to verify one. That's where our custom tools come in. First, let's build our tool to send the verification by email. Click on "Flows" in the main navigation and then create a new blank flow. We'll use the "New Trigger" trigger type, which is the trigger type to use for most of your tools.

Here's what the finished flow looks like, and you can install it in your own account here: https://flowxo.com/share/penguins-ducks-8054. Let's talk about what should go in the "Word or Phrase" configuration. This can be anything you want, and depending on how you plan to set up your tool in your assistant. You can read more about that here. In this example, we'll choose the first method so the exact text of the trigger phrase isn't important.

Note that you'll need a Mailgun account to use this flow as is, or you can use a different mail provider using SMTP.

Let's briefly talk about what each of the steps does.

1. Generate a Unique Identifier. 
We need to send a verification code to the user. Obviously, it would very insecure to just always use the same code, so we want to generate a new random one for each verification. We can use the Generate a Unique Identifier action from the "Flow XO Utilities" integration.to do that. Here's how I configured it:

We want the code to be long enough that it would very difficult to guess at, and short enough that if the user has to type it in without copying pasting, perhaps they are reading the phone on their email while typing it into a desktop, that it won't be too cumbersome. So we chose 6 characters, which seems fairly typical for this kind of code.

2. Store the code as a user attribute.
Once we have generated the code, before we send it to the user's, we need to save it to their user profile so that we can use it later to verify what they typed in. This is quite simple:



3. Send the code to the user.
Now that we have a code and stored it, we need to email it to the user so they can actually verify their email address. This uses the Mailgun integration, but you can use any outbound email provider you like using the vanilla SMTP email task as well. Although we're just sending a simple plain text notification for our example, you may want to use a nicely formatted template so that it looks more professional and therefore trustworthy.

The main thing I want to point out here is where to get the user's email address from. When you define "Flow" tool for your assistant, you will choose what "input variables" the AI should pass to the tool. In this case, we will only need one - the "email" of the user we want to verify. When the assistant calls your flow, it will put any input variables into the metadata for the Flow, so you can use them wherever you need to.

That's the whole flow. Let's add it to our assistant and try it out. Go back to your Assistant editor, edit your assistant, and click "AddTool" near the bottom of the form. 

There are several important configurations we have to make in this form. 

1. The "Type" must be "Flow" - this is how we add any custom tools that require some logic, and that is the main topic of this article. If you only need to access a REST endpoint for your tool, you can use the "HTTP" tool type, but we aren't covering that here.
2. Give the tool a descriptive name. When configuring your assistants, the "name" and "description" of your tools is much more important than in most areas of Flow XO, where the name and description are only used to help you organize things like flows, intents, etc. This is because the AI will use the name and description to decide when and how to call your tool. So they should be as specific and clear as possible..
3. Make sure to set "Beahvior" to "Wait for the flow to complete". This is important, because it tells your assistant that it should temporarily redirect the conversation to your Flow to perform a task, but will take over the conversation once it gets a result. The other option, "transfer", tells your assistant that once it calls your tool it should end its part of the conversation. Think of it like a human receptionist - if someone asks for a piece of information from a receptionist, she may put the user on hold, speak privately with a colleague to get the answer, then relay that answer to the customer and contine to help them. This is the "Wait" behavior, and will be most common when you make your own tools. "Transfer" is analogous to the receptionist transferring the call to her colleague and then moving on to do other things.
4. Trigger type - In this case, we'll choose "Direct", so that we can select the "Send Auth Code" flow from the picklist. 

We're almost done with this tool but we still need to add the input parameter. In this case, we need the assistant to send our tool an "email" parameter so it knows where to send the auth code. Click "Add input parameter" and then name your parameter "email". The default type of "text" is perfect.

Also make the field "required" - the tool is useless without an email. Again you can set a description here, some options and other things that will help you in more advanced scenarios. However in this case, it's really a no brainer to understand to put the email it collected from the user into the "email" input field, so we can move on.

Ok - save your assistant - we're ready to test the first of our custom tools!

Once your assistant is saved, click "Test", and let's see how it goes:

Here's the email I got:

Worked like a charm!

Now - a quick note if you plan to build something like this in your actual bots. After you send the verification code to the user, you really need it to expire at some point in the near future, certainly within 24 hours or so. The code is being sent via email, which isn't the most secure channel, so it should have a short lifespan. You can do this by creating another flow that "erases" the user attribute you set after a period of time, and triggering that "erase code" flow from the flow we just built. The "erase" flow would use a "Wait for Awhile" task to wait for 24 hours (or whatever you choose) and then set the user attribute that holds the code to an empty value, which deletes it. You would trigger that flow using "Continue" instead of "Wait". Here are some resources you should read if you want to build something similar: working with subflows, user attributes, pausing a flow

Back to our example - we're halfway there. At this point, the user could enter the code into the chat, but it wouldn't work, because the assistant doesn't have a way to verify the code. We'll build another tool for that purpose now.

I'm not going to go through each step in as much detail, because you already know the basics of how to set up a flow as a tool, but here's what the verification flow would look like:

Install it in your own account here: https://flowxo.com/share/intangible-generation-1570

The "Verify Auth Code" flow starts the same way as the "Send Auth Code" flow - with a "New Trigger" trigger. This is standard for your flows that are meant to be tools.

The "Send Auth Code" tool didn't really need to send any data back to the assistant, because it just did a simple task, sending an email, and the fact that it completed at all was everything the assistant needed to know to move forward.

However in this case, we need to be more specific, because the outcome of verifying the auth code can have one of two results, which are very different from one another. Either the verification succeeded, and the entered code matched what was stored in the user attribute, or it failed. And we need to send this result back to the assistant in an unambiguous manner. For that we'll use a "Set Output" task.

This action is configured just like a Set Attributes action, except that instead of storing data with the user profile, it tells the flow exactly what its outputs should be when responding to the assistant that called it. The AI will then be able to interpret that output to make decisions on what to do next. 

First, we'll deal with the case where the user entered a codes that does NOT match the generated code:


Not se set the output "auth_code_verified" to "false" 

The name of the output variable is important - it should be clear enough and self explanatory enough that the AI can clearly understand the result of the tool from the name of the output variable. For instance, "output_1" would be a terrible name, because we aren't giving the AI any information about what it means. GPT-4 may be smart enough to figure it out anyway in many cases, but you really don't want to leave that to chance, so give your output variables, like your input variables, nice clear names.

On the next page of the "Set Output", we need to set two things. First, we need to set the filter so that this task runs only when the authorization code we got from the assistant does NOT match what we already stored in the user attribute for the user.

Remember that the input from the assistant will be in the flow Metadata. Will use the input variable name "emailAuthCode". This will need to match the input variable we define in our assistant tool later.
This input the assistant sends to our flow should match the user attribute that we stored earlier. In this case though, we're handling the case where they DO NOT match. That is why our filter, if converted to english, would be something like "The emailAuthCode entered by the user DOES NOT EQUAL the email_auth_code attribute stored on the user".
We will also check the "Also stop the rest of the flow if conditions are met". This is important, because as soon as we realize the codes don't match, we're done. The verification failed, and we can report back to the assistant. Notice the "Stops flow" badge on the "No Match" action.

Ok, so what if they do match? Pretty much the same thing, except that we'll set our "authCodeVerified" output to "true" to indicate the verification was a success. interestingly, we don't need to use a filter for this task. The reason is that we handled the "No Match" scenario first, and stopped the flow when the filter indicated that the code was incorrect. Because of that, for every action that happens afterwards, we can assume the codes matched and don't need any specific filter to tell us that, because when they didn't match, the flow was halted already.

So here's what the "Codes Match" action looks like:


Functionally speaking, we could already be done, because by telling the AI the result of the verification, it has everything it needs to know what to do next. However, we're going to also take the time to clear the auth code out of the user attribute, so that this is a one time use code. This is more secure, because even if the verification code were leaked or exposed somehow, it would now be useless. To do that we will simply use a Set Attributes task to se our user attribute to an empty value, which deletes it:

And while we're setting attributes, we might as well also set an attribute on the user "email_address_verified" to true. That way we will know from now on if the user is authenticated, so that if we wanted to use different logic for authenticated users in our flows and assistants we could easily do so.

Now that's it for the verification tool. Let's tell our verification assistant how to use it. Just like before, edit your assistant and click "New Tool":

This tool will be set up in a very similar fashion to our previous tool. The differences are that the name will be different, "verify_email_auth_code" instead of "send_email_auth_code", the name of the input parameter should be "emailAuthCode" instead of "email", because the assistant uses this tool to send the auth code entered by the user to the flow for verification, and finally and obviously, we need to choose "Verify Auth Code" in the flow picklist rather than the "Send Auth Code"

That's it! Our verification assistant is all done - it now has the ability to take an email it has gathered from the user, send that user a randomly generated authorization code, and then confirm that authorization code the user typed or pasted into the chat matches. Powers we gave it using easy to build, no code custom tools. Let's try it out!

Worked like a charm! 

Now you can make your assistants to pretty much anything you can imagine. By using one of our many integrations, or integrating via HTTP with Zapier or Make or your own REST services, there are really no limits at all.

That's it for now, as always we love feedback, or are happy to answer questions and solve any problems you encounter, just reach out to support@flowxo.com

Happy flowing!

Still need help? Contact Us Contact Us