Magai Actions enable users to integrate tools and services directly within chat conversations, allowing automation of processes, calculations, information retrieval, and interaction with external APIs based on user input or predefined conditions.
Actions Overview Table
Action Type | Description | Use Case |
Pre-Built Actions | Ready-to-use actions included with Magai | Quick implementation without coding |
Custom Actions | User-created actions with custom code | Specialized functionality for specific needs |
API Integrations | Connect to external services via API | Access third-party data and services |
Utility Actions | Simple data processing and formatting | Text manipulation, calculations, formatting |
Search Actions | Information retrieval capabilities | Find relevant information from databases |
Automation Actions | Trigger sequences of operations | Automate repetitive tasks and workflows |
Setting Up Actions
Creating a New Action
Option 1: Create an Individual Action
Navigate to the personas page
Select the "Actions" tab
Click "Create Action" to begin
Option 2: Add a New Action to a Persona
Create a new persona or select an existing one
In the persona edit modal, scroll to the actions section
Click the "Add Action" button
Either select an existing action from the list or click "Create Action" to define a new one
Action Creation Process
Defining Basic Information
Name: Enter a clear, descriptive name (this will be used when calling the action in chat)
Description: Provide a brief explanation of what the action does
Instructions: Add detailed guidance on how to use the action effectively
Writing the Code
Define the action logic using JavaScript by following these coding guidelines:
function exampleAction($$inputParameter) { // Your action's code goes here let apiKey = $$_apiKey; let processedInput = JSON.parse($$inputParameter).userValue; const url = "https://api.example.com/" + processedInput; return fetch(url, { method: 'GET', headers: { 'Authorization': apiKey } }).then(res => res.json()); } exampleAction($$inputParameter);Code Requirements and Best Practices
Input Parameter: Functions must accept one input parameter with the prefix
$$Browser Compatibility: Use only browser-compatible code (avoid Node.js specific code)
Variables: Use
$$_prefix for user-configurable variables (e.g.,let apiKey = $$_apiKey)Type Handling: All variable values are strings by default; convert types as needed
Return Value: Each function must return a result as a string
Function Call: Include the function call at the end of your code
String Concatenation: Use the
+operator instead of template literals/backticks
Auto-Generating Code
If you're unsure how to write the code:
Click the "Generate Code" button below the console
Describe the desired functionality in plain English
Click "Generate"
Review and modify the generated code as needed
Testing Your Action
Expand the code console for better visibility
Click "Test Code"
Provide any necessary input parameters
Click "Start Test"
Review the output or debug any errors
Saving and Assigning Actions
Once testing is complete, click "Save Action"
If creating within a persona, ensure the action is selected (enabled)
Complete the persona configuration and save changes
Using Actions in Chat
Preparing an Action for Use
Ensure the action is saved and assigned to at least one persona
Add comprehensive descriptions and instructions
In the persona's instructions, clearly explain:
The action's purpose and functionality
When it should be called
Required input format and examples
Invoking Actions in Conversation
Actions can be triggered in three primary ways:
Direct Selection:
Type
:in the chat to display available actionsSelect the desired action from the dropdown menu
Formatted Input:
Provide the required input in the specified format
Example:
HELLO||lowercaseto convert text to lowercase
Natural Language Request:
Simply ask the persona to perform the action
Example: "Can you convert this text to lowercase?"
Executing and Receiving Results
Once triggered, the system will:
Process the input according to the action's logic
Execute the code with the provided parameters
Return the output directly in the chat conversation
Allow for follow-up actions or modifications as needed
Managing Your Actions Library
Editing Existing Actions
Navigate to the Actions tab
Click the edit icon next to the action
Modify the code, description, or settings as needed
Test the changes and save
Removing Actions from Personas
Open the Edit Persona section
Locate the action in the assigned actions list
Click the minus (
-) button to remove itSave the persona changes
Deleting Actions Completely
Go to the Actions tab
Click the settings icon next to the action
Select "Delete" from the dropdown menu
Confirm deletion (note: this cannot be undone)
Action Configuration Options
API Key Management
Some actions require API keys for external services
Click the cogwheel icon to access configuration settings
Enter and save API keys securely
Default Values
Set default input values for common parameters
Configure global settings for actions used across multiple personas
Customize behavior based on specific use cases
Access Control
Determine which users can access specific actions
Set permissions for viewing, editing, or executing actions
Manage action availability across workspaces or teams
Best Practices
Clear Documentation: Always provide clear descriptions and usage examples
Error Handling: Include robust error handling in your code
Input Validation: Verify input format and values before processing
Testing: Thoroughly test actions with various inputs before deployment
Security: Never expose sensitive information in action descriptions
Modular Design: Create reusable actions that can be combined for complex workflows
Performance: Optimize code for quick execution and response
User Experience: Design actions with intuitive inputs and clear outputs
Troubleshooting Common Issues
Action Not Appearing
Ensure the action is saved and assigned to the current persona
Check that all required configurations are complete
Verify you have permission to use the action
Execution Errors
Review the error message in the testing console
Check input types and formats
Verify external API connections and authentication
Performance Issues
Simplify complex code
Ensure external API calls are optimized
Consider breaking complex actions into smaller, modular actions
Code Generation Problems
Provide clearer descriptions of desired functionality
Review and modify generated code as needed
Use simpler requests for the auto-generation feature
For additional assistance with Magai Actions, consult the full documentation or contact Magai support.