# AIsuru functions

AIsuru offers a set of built-in, ready-to-use functions that let your Agent interact with the outside world. These functions are already configured and can be enabled easily — but they do require careful setup in the Agent's instructions to be used effectively.

### Overview of available functions

AIsuru offers seven main built-in functions:

1. **Context variables**: let the Agent dynamically manage conversation topics;
2. **Artifacts**: create and download interactive content in various formats (HTML, CSS, JavaScript, JSON, markdown, svg, etc.) directly in the chat;
3. **Send email**: lets the Agent send email communications to registered users;
4. **Convert OpenAPI to functions**: automatically generates functions from OpenAPI specifications;
5. **Create function from file**: lets the Agent access a file during conversations;
6. **Perplexity Search**: lets the Agent perform intelligent web searches with AI-synthesized results;
7. **Emotions**: lets your Agent express emotions through facial expressions and animations when displayed with a 3D avatar.

You can start using them right away — just enable the toggle for the function you want to use inside your Agent!

Keep in mind, though, that to simplify the interaction and improve the user experience, you'll need to explain to the Agent how and when to use them in its [instructions](/en/generative-ai/ai-instructions.md).

Let's look at each one in detail 👇

## 1. Context variables

Context variables let your Agent dynamically manage conversation contexts.

This function is particularly useful for:

* Automatically applying specific contexts based on the user's responses;
* Removing contexts when they're no longer relevant;
* Naturally guiding the conversation between different topics.

#### How it works

The generative AI can:

* Set a new context when it detects a topic change;
* Remove a context when the topic is no longer relevant;
* Use multiple contexts at the same time to respond accurately.

#### Setting it up in the instructions

It's important to guide the Agent in its use of context variables through the instructions, specifying:

* Which contexts it can apply (be precise about the context to apply);
* When to apply the different contexts;
* How to handle transitions between contexts: which contexts are compatible and when to remove ones that are no longer relevant.

For example:

```
When discussing a specific product, set 
PRODUCT:[product name]. If the user changes topic, 
remove the context with PRODUCT:-. 
Example: if the user asks about product X, set PRODUCT:X
```

## 2. Artifacts

#### What they are

Artifacts are content your Agent can create inside the chat with the user. This content can be used interactively, downloaded, and shared.

The Agent can create any type of file using artifacts, for example:

* Interactive web pages: a single HTML file containing CSS and JS code;
* Text files: such as txt and markdown;
* CSV, SVG, and other file types.

#### How they work

Once the Artifacts function is enabled, your Agent can immediately start creating this content. To guide it more precisely, remember to explain in the [instructions](/en/generative-ai/ai-instructions.md) when it should use artifacts and how.

During the conversation, if the Agent creates an artifact, the user will see it in a separate panel on the right side of the page.

#### Interacting with artifacts

At the top of each artifact there's a toolbar with several buttons for managing the content. From left to right:

* **Code icon**: shows the artifact's source code;
* **Eye icon**: shows the formatted or rendered file (only available for Markdown and HTML files; for other file types you'll only see the code);
* **"Copy" button**: copies the source code to the clipboard;
* **Additional options menu (down arrow)**: clicking the arrow next to the "Copy" button opens a menu with the following options:
  * Download as HTML or Markdown (HTML and Markdown files only);
  * Download as PDF (Markdown files only);
  * Open in a new window;
  * Print.

All these features make it easy to view, copy, share, or save any artifact generated during the conversation.

#### Limitations

Artifacts cannot be displayed if the user is interacting through a "Website Assistant" [sharing layout](/en/sharing/create-and-manage-sharing-layouts.md).

## 3. Send email

The **Send email** function lets your Agent send email communications to all registered users on the platform (on aisuru.com or within your PaaS). This function uses the SMTP protocol and can be configured with any email provider that supports it.

#### 3.1 How it works

The Agent can send emails automatically during conversations, using the SMTP credentials you've configured. The function automatically retrieves the user's email address from their registered account, so the user doesn't need to provide it during the conversation.

**Important**: This integration only works with users who have registered and logged in to the platform. It doesn't work with anonymous users.

#### 3.2 SMTP configuration

To configure email sending in your Agent:

1. Go to the **Functions** section of your Agent;
2. Find the **"Send Email"** box and enable the function by pressing "edit parameters" when you hover over the box.
3. Choose your "SMTP configuration mode":
   1. Inherit from tenant: the agent uses the [tenant's SMTP configuration](/en/paas/admin-panel/tenant-management.md) (disabled if not configured);
   2. Custom SMTP configuration: enter SMTP credentials specific to this agent. If you choose this option, fill in the required fields.

**Configuration fields**

| Field               | Description                                 | Example                                     |
| ------------------- | ------------------------------------------- | ------------------------------------------- |
| **SMTP Server**     | The address of your email provider's server | smtp.gmail.com, smtp-mail.outlook.com       |
| **Port**            | The server's SMTP port                      | 465 (SSL), 587 (STARTTLS), 25 (unencrypted) |
| **Username**        | Your full email address                     | <name@company.com>                          |
| **Password**        | The email account password or app password  | •••••••••••••••••                           |
| **Sender email**    | The address that will appear as the sender  | <name@company.com>                          |
| **Sender name**     | The name that will appear as the sender     | Company Name                                |
| **Socket security** | The type of encryption used                 | SSL/TLS, STARTTLS                           |

5. Press the **"Save"** button to confirm the settings.

#### 3.3 Gmail / Google Workspace specific setup

If you use Gmail or Google Workspace, follow this detailed guide for a secure setup that complies with Google's policies:

**3.3.1 SMTP credentials for Gmail**

<table><thead><tr><th width="255">Field</th><th>Value to enter</th></tr></thead><tbody><tr><td><strong>SMTP Server</strong></td><td>smtp.gmail.com</td></tr><tr><td><strong>Port</strong></td><td>465 (SSL) or 587 (TLS)</td></tr><tr><td><strong>Security method</strong></td><td>SslOnConnect or StartTls (see port)</td></tr><tr><td><strong>Username</strong></td><td>full address (e.g. name@company.com)</td></tr><tr><td><strong>Password</strong></td><td>App password generated by Google*</td></tr><tr><td><strong>Send limit</strong></td><td>2,000 emails/day per account</td></tr></tbody></table>

**3.3.2 Step-by-step guide for Gmail**

1. **Enable 2-Step Verification** on your Google account;
2. **Generate an App Password**:
   * Go to [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords);
   * Enter a descriptive name for your app password (e.g., "AIsuru Mail");
   * Click Create and copy the generated password.
3. **Configure in the AIsuru panel**:
   * SMTP Server: `smtp.gmail.com`;
   * Port: `465` (SSL)
   * Username: your full email address;
   * Password: the app password you just copied;
   * Socket security: leave blank unless you're an advanced user. Options are None, Auto, SslOnConnect, StartTls, or StartTlsWhenAvailable. The default is Auto.
4. **Save and test**: you should receive a test email within a few seconds.

#### 3.4 Other email providers

The email sending function can be configured with any provider that supports SMTP. Check your provider's documentation to get:

* SMTP server and port;
* Supported encryption type;
* Authentication credentials.

#### 3.5 Configuring in the Agent's instructions

It's essential to define in the Agent's **Instructions** how to use this function. Here's an example — make sure to adapt it to your specific use case:

```
EMAIL SENDING FUNCTION

WHEN TO SEND EMAIL:
- Send email only when the user explicitly requests documentation, reports, or specific material

STANDARD EMAIL FORMAT:
- Subject: "Requested documentation - [topic]"
- Body: brief introduction, link/attachment, support contacts

CONFIRMATION MESSAGE:
```

#### 3.6 Best practices

* **Define clear templates** for different types of communication;
* **Set limits** on sending frequency (maximum 2 emails per conversation);
* **Implement security checks** in the instructions;
* **Handle personal data properly** in accordance with privacy regulations;
* **Monitor usage** to avoid overloading the SMTP server;
* **Test the configuration regularly** to make sure it's working.

#### 3.7 Security and compliance

* Never share SMTP credentials in plain text;
* Always use encrypted connections (SSL/TLS);
* Periodically regenerate app passwords;
* Monitor sending logs to detect misuse;
* Respect your provider's sending limits to avoid blocks.

With this configuration, your Agent will be able to send emails securely and professionally, improving the user experience and providing a direct communication channel.

## 4. Convert OpenAPI to functions

The **Convert OpenAPI to functions** feature lets you automatically generate AIsuru functions from an existing OpenAPI specification.

#### How it works

This function lets you:

* **Upload a JSON OpenAPI file** with the documentation of an existing API and its webhook;
* **Automatically generate** all the functions needed to interact with the API;
* **Have functions ready to use** with parameters, descriptions, and configurations already set up.

#### Setting up the OpenAPI conversion

To convert an OpenAPI specification to functions:

1. Go to the **Functions** section of your Agent;
2. Select the **AIsuru Functions** tab;
3. Find the **Convert OpenAPI to functions** box:
   1. Enter the base URL of the webhook (i.e., the API — e.g., `https://api.example.com`);
   2. Click "Load OpenAPI JSON" and select the file to upload.

#### Best practices

1. **Review the generated functions**: check the created functions to make sure they're correct;
2. **Test the functions**: use the "Test" button to verify they work;
3. **Update the instructions**: explain to the Agent how and when to use the new functions.

## 5. Create function from file

The create-from-file function lets the Agent access files like Excel, PDF, HTML, or TXT during conversations, enabling it to use information contained in those documents.

**How it works**

This function lets you:

* Upload a file (Excel, PDF, HTML, or TXT) smaller than 500,000 characters
* Provide a description that explains to the generative AI how to use this file during conversations
* Make the file accessible to the Agent as a source of information

**Setting up the function from file**

To create a new function from a file:

1. Go to the **Functions** section of your Agent
2. Select the **Advanced functions** tab
3. Click the **Create function from file** button
4. On the page that opens, you can:
   * Upload a file (Excel, PDF, HTML, or TXT) smaller than 500,000 characters
   * Enter a **function description** that explains to the generative AI how to use the file's content

The **function description** is essential: it must clearly indicate to the AI when to use this function and how to interpret the data in the file.

**Example**

If you upload a price list in Excel format, you might write a description like:

```
Use this function when the user asks about the prices of our products.

The file contains the updated price list with the following columns:
- Product code
- Product name
- Category
- List price
- Discounted price
- Availability

When the user asks for the price of a specific product, look it up in the list and provide all available information for that product.
```

**Best practices for creating functions from files**

* Use well-structured files to make it easier for the AI to read them
* Provide detailed descriptions that guide the AI in using the file
* Keep files under 500,000 characters for optimal performance
* Update files periodically to keep information accurate

## 6. Perplexity Search

**Perplexity Search** lets your Agent perform intelligent web searches using Perplexity's AI, which combines real-time search with the ability to synthesize and analyze results.

#### How it works

Unlike a simple web search, Perplexity:

* Searches for up-to-date information on the internet;
* Analyzes and synthesizes the results;
* Provides complete answers with source citations;
* Returns both search results and an AI-synthesized response.

#### Setting up Perplexity Search

You can configure the API key in two ways:

* **Inherit from tenant**: the API key is inherited from the tenant (PaaS) configuration. Any tenant administrator can modify this key at any time on the dedicated page. Changes apply automatically to all agents using the tenant configuration.
* **Custom API key**: you can configure a specific API key for this agent.

**Configuration steps**

To enable this function:

1. In the AIsuru Functions section, find "Perplexity Search";
2. Enable the toggle to activate the function;
3. Choose the API key mode:
   * Select "Inherit from tenant" to use the centralized configuration;
   * Select "Custom API key" and enter your Perplexity API Key in the field;
4. Press "Save" to confirm the settings.

#### Instructions

Remember to update your Agent's instructions to explain how it should compose the query to pass to Perplexity (which will handle the actual search).

## 7. Emotions

AIsuru's **Emotions** function lets your Agent express emotions through facial expressions and animations when displayed with a 3D avatar. This system significantly improves interaction, making communication more natural and expressive.

#### How to enable the Emotions function

To enable this function:

1. Go to the **management panel** of your Agent
2. Navigate to the "**Functions**" section in the sidebar
3. Find the "**Emotions**" function under the "**AIsuru Functions**" tab
4. Enable the **toggle** to activate this feature

#### How Emotions works

When you enable the Emotions function, the behavior depends on the type of avatar you're using:

* **With an avatar**: you'll immediately have access to 5 default emotions that the avatar can show (Happiness, Sadness, Anger, Surprise, Fear)
* **With custom GLB models**: the model must include the desired animations and expressions

The function **doesn't require any specific prompt** to be activated. Once enabled, AIsuru's backend will automatically manage emotions by inserting the necessary tags into the Agent's responses based on the conversation context.

#### Displaying emotions

To see emotions in action, you need to view your Agent in an environment that supports 3D avatars, such as:

* In AIsuru **Virtual Spaces**
* Using **layouts** that support 3D avatars

#### Animation categorization system

The system automatically categorizes animations based on their name:

* **IDLE**: base animations that loop continuously (the animation name contains "idle")
* **LOADING**: animations that indicate a waiting state (the name contains "loading" or "wait")
* **ACTION**: all other animations that show specific actions or emotions

#### Custom GLB models and animations

If you use a custom GLB model:

* If the model has an **RPM-compatible skeleton** (Ready Player Me), standard animations will work automatically
* The model **must have at least one IDLE animation** (the animation name must contain the word "idle") to work correctly
* Animations are triggered by the backend based on the conversation context
* For best results, the model should include animations for the basic emotions (happiness, sadness, anger, surprise, fear)

#### Advanced customization through instructions

For more detailed control over animations, you can add specific instructions in your **Agent's Instructions** (Settings > AI > Instructions).

**Single animations**

```
<output class="animation">AnimationName</output>
```

**Looping animations**

```
<output class="animation">AnimationName[loop=N]</output>
```

Where the loop values are:

* **\[loop=0]**: loops the animation indefinitely
* **\[loop=1]**: plays the animation once (default)
* **\[loop=N]**: repeats the animation N times

IDLE animations default to `loop=0` (infinite).

**Animation sequences**

```
<output class="animation-sequence">Animation1->Animation2->Animation3</output>
```

You can also specify a loop parameter for sequences:

```
<output class="animation-sequence">Animation1->Animation2->Animation3[loop=2]</output>
```

**Default emotions (for RPM avatars)**

```
<output class="memori-emotion">Happiness</output>  <!-- or Sadness, Anger, Surprise, Fear -->
```

#### Agent instruction guide

You can guide the generative AI by adding specific instructions in your **Agent's Instructions** (Settings > AI > Instructions).

Example instructions for the Agent:

```
GUIDE FOR EMOTIONAL EXPRESSIONS: When communicating with the user, express your emotions by writing exactly the following patterns: 1. For an EMOTION SEQUENCE: <output class="animation-sequence">Surprise->Happiness</output> Example: "I was surprised at first, but now I'm happy about the news! <output class="animation-sequence">Surprise->Happiness</output>" 2. For REPEATED ANIMATIONS (use for emphasis): <output class="animation">Wave[loop=3]</output> Example: "I'm waving enthusiastically! <output class="animation">Wave[loop=3]</output>"
```

#### Example instructions for dance movements

If your model supports specific movements, you can create custom instructions like:

```
DANCE MOVEMENTS:- AIDA1: Slow spin with arms extended upward- AIDA2: Undulating movement of hips and arms- AIDA3: Side step with leg cross and torso rotationEMOTIONAL STATES:- Joy (Joy1, Joy2, Joy3)- Sadness (Sadness1, Sadness2, Sadness3)To create a dance sequence, use this syntax:<output class="animation-sequence">AIDA1->AIDA2->Joy1->AIDA3</output>Rules for sequences:1. Use -> to link animations2. Maximum 5 animations per sequence3. No spaces4. You can freely combine dance movements and emotions in the same sequence
```

#### Best Practices

1. **Enable the Emotions function** from the Functions panel
2. **Don't modify the instructions** unless you need advanced customization
3. For an avatar created with AIsuru's avatar maker, the system will automatically use the 5 default emotions
4. For **custom GLB models**, make sure they have at least one IDLE animation and a compatible skeleton
5. For **complex sequences**, use advanced instructions with animation tags
6. **Keep sequences to** 3–5 animations for best performance
7. **Test animations** with different avatar types to verify compatibility

By enabling the Emotions function, your Agent will be able to communicate in a more expressive and engaging way, significantly improving the user experience in 3D environments.

### Security considerations

For all these functions, it's essential to:

* Carefully configure the Agent's instructions;
* Limit access to sensitive resources;
* Monitor function usage;
* Implement verification mechanisms;
* Comply with privacy and data protection regulations.

### Performance optimization

To get the best results:

* Combine different functions synergistically;
* Keep instructions clear and up to date;
* Regularly monitor function usage;
* Collect user feedback;
* Continuously refine configurations.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aisuru.com/en/advanced-features/integrations/functions/aisuru-functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.