Prerequisites: Basic understanding of REST APIs. If you’re new to APIs, check out this video first, then come back.

What is an action?

An action is a task that your agent can execute that involves interfacing with the outside world. For example:

1. Calling the Google Calendar API to book an appointment for a user.

2. Fetching a funny quote from a public API and reciting it to a user.

Fundamentally, actions are flexible and discrete pieces of functionality that you can build into any agent — and unlock limitless utility!

Great, how do I create an Action?

Step 1 - get to the right place

Navigate to our Actions page:

Where you will find a form that looks like this:

Step 2 - Describe your action

Agents determine when to invoke actions using the description that you assign when creating an action. If your action description is “Get a funny quote”, when you ask your agent during a conversation “hi, can you get me a funny quote”, your agent will happily do so. However, if your action description is “fry me a hot dog”, the agent will have no idea what to do.

Step 3 - Enter your endpoint and choose your request method

This is where the (slightly technical work) comes in. At this stage, you’ll enter the URL for the API you want your agent to retrieve data from or send data to. It can be a public API, an API you built yourself, or anything in between.

Step 4 - Configure your parameters (optional)

This is where the fun begins. Actions can be configured with headers, body parameters, query, parameters, and URL parameters using any combination of static and dynamic parameters.

What are static parameters?

Static parameters are parameters that you want to remain the same every time the action is invoked. This is often useful for parameters such as API keys, which generally remain the same for each call:

For static values, be sure to uncheck the “Conversation time parameter” checkbox.

What are dynamic parameters?

Dynamic parameters are parameters that you’d like the agent to determine based off of the conversation. For example, the user’s name, or email address.

Step 5 - Enable your action:

To enable your action, either edit an existing agent, or create your own. At the bottom of the composition form, you should see your new action!

Simply check the box corresponding to the action you’d like to enable - and you’re all set.

How do I test my action?

Once your action is enabled, your agents will intelligently invoke it during conversations. To test your first action, navigate to your agents, start a conversation, and ask the agent to do whatever it is that your action description entails. If the action succeeds, you’re done!

However, if for some reason the action initially fails, you debug by navigating to the conversations page and viewing the transcript of the relevant conversation.

That’s all for now. Feel free to shoot any questions or provide any feedback you have to oliver@play.ht Thanks for reading!