Functions

Functions allow an AI instance (or agents) to consume data from an API endpoint. Administrators can apply settings to functions which determine how an agent makes requests to an API.

Menu location

Functions can be created and or edited from the following menu: Settings > Functions

Types of Function

The following function types are available:

1. API - Calls to retrieve information from an api
2. Python - Calls to a python code template that gets executed dynamically with injectable parameters
3. DB - Calls to predefined stored procedures on the SQL database of choice
4. HTML - HTML embedding of elements in the chat
5. CHAT - Scripts and predefined next steps for the agent to follow in a chat

note

HTML functions are available only from Pro plan onwards and DB functions are available only for Enterprise plans.

Function Configuration

Core Settings

Every function requires these basic settings:

• Name
• Description
• Callback

When configuring the setting Description it is especially important to clearly state the specific purpose of the function, because the chat agent is basing its decision to invoke a function on this field. We recommend to include as much detail as possible in this field try to stay short and concise.

When rather than What

The Description field is used by the agent to determine when to call the function. The agent will call the function based on the scenario described in description field - not so much what it actually does as this information is inferred in the parameters and the code block (if any). An example is Use this tool when the user asks for the weather in a specific location rather than This function retrieves the weather in a specific location.

Regarding the callback setting, when it is Off the function will be called upon the user asking a question, while when it is On the function will be called upon the agent answering the question. This allows the user to have more control over when the function is called. For example if the function needs to log the user's details, it is better to have the callback setting set to On so that the function is called after the agent has answered the question. While insted if the function needs to retrieve some information from an external source, it is better to have the callback setting set to Off so that the function is called before the agent answers the question.

API Function specific configuration

• URL - The endpoint of the API for the associated Agent to consume
• Request Type - The type of request to be made to the API (GET, POST, PUT and DELETE) - GET is the default.
• Authorisation type - The type of authorisation to be used for the API request. This is optional. ToothFairyAI supports OAuth2, API key and Bearer token authorisation types
• Authorisation - The authorisation token to be used for the API request. This is optional and can be set in the Authorisations section of the function settings.

JSON response required

API functions assume the response from the API will be a JSON parsable object. If the response is not a JSON parsable object, you may need to modify your code to handle the response appropriately as in the Tools details the request might appear in error!

Python Function specific configuration

• Code execution template - The code execution template to be used for the function. This is required for the function to work. It is important to note that all dynamic parameters wrapped in {{}} must be defined in the parameters section of the function definition.

DB Function specific configuration

• Stored procedure - Procedure of the db that is to be executed
• Connection type - Type of SQL database

HTML Function specific configuration

• URL - URL of the html that is to be included
• Message on successful submit
• Message on failed submit

Chat Function specific configuration

• Chat script - Script of the chatbot that is to be included. When the Chat action type selected is suggestion - the user can include in the text a link in markdown format to redirect to user to a custom webpage overriding the normal behavior of the suggestion in the chat.
• Chat action - Whether the chatbot should suggest a different question or indicate the next step of the conversation

Advanced settings

Dynamic URL (API only)

The dynamic URL setting allows the user to set a dynamic URL for the API endpoint. This is useful when the API endpoint is not static and needs to be generated dynamically based on the user input or other parameters. The dynamic URL can be set using the {{}} syntax, similarly to how it is done in the code execution settings. For example, if the API endpoint is https://api.example.com/weather/{{location}}, the location parameter will be replaced with the actual value provided by the user. It is important that the name of the dynamic parameter in the URL matches the name of the related variable inside the parameters section of the function settings. The dynamic URL can be used in conjunction with the parameters section to create a fully dynamic API endpoint.

Handling of path parameters

When a variable is used in the URL, it is automatically removed from the body of the request. This means that the variable will not be included in the request body, and only the remaining parameters will be sent in the request body.

Parameter settings (API, Python and DB only)

When creating a function, by default a code block is provided which demonstrates the required settings needed to consume the API URL. The properties object is required and must include the parameters which the API needs to make requests. The code block which is provided by default when creating a function is below:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, e.g. San Francisco, CA"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius","fahrenheit"]
    }
  },
  "required": ["location"]
}

For each object within the properties object, a key (or property) which relates to the API's parameters needs to be included. In the example code block above, location is a required parameter for consuming the API. Within each property is a type which must be included. A type is the data type which is used by this parameter eg ("string", "number", "array", "object" types).

These properties (or parameter objects) should also contain a description key with details about what the property is. The more descriptive and accurate the description, the better the results an agent can provide. The agent will use these description items as a reference for how to answer questions and consume the API.

The required array is used to list out the mandatory properties needed for making requests.

Python function

Each dynamic parameter wrapped in {{}} must be defined in the parameters section of the function definition. This will effectively instruct the agent on how to replace the dynamic parameter with the actual value. The parameters defined in the function should be dictated by the Code execution template selected. A Python function always requires an Environment to be selected.

Dynamic URL

Each dynamic parameter wrapped in {{}} defined in the url must be defined in the parameters section of the function definition. This will instruct the agent on how to construct the dynamic URL.

How to handle multipart and encoded form data

When the API requires a multipart/form-data or application/x-www-form-urlencoded content type, you simply need to include the Content-Type header in the additional headers section of the function settings. The Content-Type header should be set to multipart/form-data or application/x-www-form-urlencoded respectively.

danger

Unless specified otherwise in the Headers section, the Content-Type header is automatically set to application/json when the request type is POST or PUT.

Scope (API and DB only)

Scope is extremely useful when the function is required to persist data for the duration of the conversation and especially when the agents need to authenticate the customer or the case prior to disclosing any sensitive information. ToothFairyAI abstracts the two key components of such interactions in the chat with the concept of Customer and Case. This allows complex service interactions or internal workflows to be handled by the agent without overloading the agent with unnecessary information. The scope setting allows the user to define what kind of the data is being persisted within the chat session for any given agent and function.

The available options are Customer retrieval, Case retrieval, Customer authentication, and Case authentication.

• Customer retrieval - This scope is used to persist data related to the customer for the duration of the conversation. The data is stored in the customerInfo object and can be accessed by the agent throughout the conversation. To take effect, the function must have the customer id populated manually at the creation of the chat or a Customer authentication function must be accessible by the agent to store the customer id at runtime based on the information provided by the user in the conversation.
• Case retrieval - This scope is used to persist data related to the case for the duration of the conversation. The data is stored in the caseInfo object and can be accessed by the agent throughout the conversation. To take effect, the function must have the case id populated manually at the creation of the chat or a Case authentication function by the agent to store the case id at runtime based on the information provided by the user in the conversation.
• Customer authentication - This scope is used to persist only the customer id within the session (use JSON path extractor to correctly set up this workflow when the response is a JSON object). The data is stored in the customerId field and can be used by any agent with a function with Customer retrieval as scope to retrieve the customer information.
• Case authentication - This scope is used to persist only the case id within the session (use JSON path extractor to correctly set up this workflow when the response is a JSON object). The data is stored in the caseId field and can be used by any agent with a function with Case retrieval as scope to retrieve the case information.

It is recommended to couple the scope setting with the Agent hand-off feature to implement additional information segregation with unauthenticated customer/case.

Thanks to these settings virtually any customer/employee interaction can be handled by the agent with focus on a customer and/or a case (quotation, ticket, meeting etc).

JSON path extractor (API and DB only)

The JSON path extractor is an optional setting which allows the user to extract specific data from the API response. The JSON path extractor is used to extract data from the API and DB stored procedure response at a specific path. For example if the API response is:

{
  "customer": {
    "name": "John",
    "tickets": [
      {
        "id": 1,
        "status": "open"
      },
      {
        "id": 2,
        "status": "closed"
      }
    ]
  }
}

And we are only interested in the id of the first ticket, the JSON path extractor would be customer.tickets.0.id.

Request type (API only)

The available requests options for the request type is limited to GET, POST, PUT and DELETE.

Authorisation type (API only)

This optional setting is available to authenticate the request if it is required. API keys, OAuth2 credentials, and Bearer tokens must be set in the authorisations section of the function settings. Once an authorisation is created, select the authorisation type using the dropdown menu. After an authorisation type is selected, the Authorisation dropdown will appear allowing the user to select the authorisation created.

Additional headers (API only)

This optional setting is available to provide additional headers when making requests if it is required. This can be used to set the Content-Type header to application/x-www-form-urlencoded or multipart/form-data when the API requires it.

Multipart Request Handling

When sending multipart requests, the data should be structured as a dictionary with specific formats for different types of content.

Base64 File Data

For file data, use base64 data URI format:

{
  "field_name": "data:[content-type];base64,[base64-encoded-data]"
}

Static arguments (API only)

This optional setting is available to allow constant settings for the predefined properties when the agent consumes the API. For example, if a property is the same for all requests (eg a userID), then adding those details in this area will ensure that this property is always set to the same value.

Hand-off between Agents via Functions

The hand-off setting is available to allow the user to pass the conversation to another chat agent. This is useful when the workspace has multiple agents with multiple skills and the user needs to be transferred to another agent to answer a specific question. A common flow for this setting can be seen below:

1. Receptionist agent is created to answer general questions with very limited access to the customer database (e.g. the agent can only answer questions about the company's products and services or retrieve customer and case id based on the information provided by users in the chat). In other words, the agent is not able to retrieve any information from the customer database aside from the customer or the case id.
2. Customer service officer agent is created to answer questions with access to the customer database - therefore it can retrieve personal information about the customer and the case.
   1. The agent is assigned to a function which allows the agent to consume an API to retrieve information from the customer database to match name and phone number or order id to the customer ID.
   2. The information required to retrieve customer and case information is completely unopinionated and it can be easily customized to meet any verification requirement.
      1. For the function to persist the customer and the case information, the function must have Customer authentication or Case authentication set as scope.
   3. Regardless of the information required, the function must have the Agent hand-off enabled by selecting the agent Customer service officer to hand-off to.
3. A customer makes an inquiry about their order status providing the order number or their name and phone number.
4. The Receptionist agent will consume the API to retrieve the customer ID and case ID. The agent will then hand-off the conversation to the Customer service officer agent which has access to the customer database.
5. Moving forward the Customer service officer agent will be able to provide the customer with the information they require.

The hand-off setting allows an agent to hand off the conversation with multiple agents in the workspace depending on the interaction with the users in the chat. As it is part of the function settings, the hand-off can be chained with multiple agents in the workspace. Simple chain Agent A > Agent B > Agent C > Agent D Complex chain Agent A > [Agent B > Agent C] > Agent D

danger

The agent hand-off poses a security risk if the function is not correctly configured. It is important to ensure that the function is correctly configured to prevent any data leakage as, due to the hand-off, data will be passed to another agent that should not have access to the information accessible by the initial agent.

Hand-off with Planner agents

Planner agents override the hand-off setting of any function; in other words no hand-off is executed during the execution of a plan designed by a planner agent.

This means that only if a planner agent determines as part of the plan execution that the task needs to be assigned to another agent, the hand-off will be executed. Our recommendation is to use hand-off for more deterministic tasks where the agent is not able to answer the question and the hand-off is required to pass the conversation to another agent; while instead planner agents should be used for more complex tasks where the agent needs to determine the next step is a pure agentic behaviour.

Agent settings for Functions

An agent needs to be created in order to assign a function to it. One agent can be assigned to multiple functions of multiple types.

When configuring the function settings for an agent, it is possible to provide context to the function when choosing which one to call and how to call it. In other words, context allows to dramatically increase the accuracy of the request by providing the agent with additional information.

Context settings

The available options are:

• Customer - The customer information that is passed to the function. This is useful when the function needs to retrieve information about the customer. This assume the customer information has been retrieved by the agent using a Customer authentication function or a previous function with Customer retrieval scope.
• Case - The case information that is passed to the function. This is useful when the function needs to retrieve information about the case. This assume the case information has been retrieved by the agent using a Case authentication function or a previous function with Case retrieval scope.
• Chat - The chat information contains metadata about the conversation such as current date, time, summary of the conversation and user id. This is useful when the function needs to use and manipulate information present in the chat to correctly consume the function.

Passing information from HTML functions to ToothFairyAI

Information from a displayed HTML element in the chat can be passed back to ToothFairy's AI agent via window.top.postMessage. The data that gets send to ToothFairy needs to be a JSON object where all elements to be sent are given as a value in JSON object form to the key "data". To ensure that ToothFairy knows that the data is coming from an HTML element, the key "tf_event_type" needs to be set to "form_submit". An example of how this can be done is shown below:

var message_form = {
            "data":{
                "name":name,
                "surname":surname,
                "driving_license":drivingLicense
            },
"tf_event_type" : "form_submit"
        }
window.top.postMessage(message_form, '*')