# Actions **Actions** define specific tasks that an agent must perform as part of its goal-driven workflow. Their primary purpose is to **guide the collection of required data** by specifying what information is needed, in which order it should be obtained, and whether each piece of data is mandatory. Based on this definition, the agent gathers the input in the most appropriate way and then activates a action. The action uses the collected data to execute a specific function—such as summarizing information, generating content or reports, or automating workflows. Within the dialogue flow, **actions act as the data collection mechanism**, while the flow itself uses that data to carry out the intended operation in real time.
{% hint style="warning" %} The name and Instruction fields are critical steps that will determine how to process and execute the action. {% endhint %} ## New Action Fill the presented fields: * **Name**: It should be clear and descriptive of the task the action will perform. Use lowercase letters and separate words with underscore (e.g., search\_flight, destination\_recommender). * **Instructions:** This field provides detailed information about what the action does, its purpose, and when it should be triggered, **which makes it essential for its correct functioning**. For the action *search\_flight*, for instance, the description is *“Trigeer this action when users request to book a flight, buy a ticket, reserve a trip, or similar actions, execute them accordingly.”* ## Parameters Once you've defined what it should do, now specify how. Breakdown which data should be collected by using the Parameters block. Start by choosing between two approaches: **Basic** and **Advanced**. In advanced mode, you can use a JSON containing all the parameters required for the success of this action for more technical and precise action definition. Here is a JSON example for Advanced Mode: ``` { "type": "object", "properties": { "date": { "type": "string", "description": "The departure date for the flight, formatted as YYYY-MM-DD." }, "origin": { "type": "string", "description": "The departure location or airport code (e.g., JFK, LAX)." }, "destination": { "type": "string", "description": "The arrival location or airport code (e.g., CDG, NRT)." }, "type_of_flight": { "type": "string", "description": "The type of flight, such as 'one-way' or 'round-trip'." }, "number_of_passengers": { "type": "integer", "description": "The total number of passengers traveling." } }, "required": ["date", "origin", "destination", "type_of_flight", "number_of_passengers"] } ``` Whereas in basic mode, you can add the parameters individually for easier configuration. Fill the presented fields: * **Parameter Name** * **Type**: Defines the data format (string, boolean, number) that the parameter accepts * **Parameter Description**: Explains the purpose and expected values for this specific parameter * **Variable** (optional): Assigns a reference name that can be used elsewhere in the agent's workflow. The value can be accessed through $hiddenContext.variable, such as: $hiddenContext.numberOfPassengers (see table). * **Rules** (optional): Specifies constraints, validations, or conditional behaviors that govern how the parameter works. They serve as tactical directives. For the action *search\_flight* above mentioned, there are five parameters: date, origin, destination, type of flight, number of passengers. Here's a more detailed breakdown for two of them:
NamenumberOfPassengersdates
TypeStringString
DescriptionThe number of passengers traveling, including both adults and children. The passengers must be adults.The dates of travel, including departure and optionally return, provided in a format like YYYY-MM-DD or DD/MM/YY. The date provided is a valid date, i.e. it must be a future date, The departure and destination dates must correspond to a valid period. The current year is 2025.
Variablenumberpassengers--
Rules

- If you are informed that they are a children or student, kindly recommend that they book the flight online: website.com/buy-tickets

- The number of passengers must be 9 people max. If there are more than 9 people, kindly recommend that they book the flight online: website.com

If the user gives you a round-trip date, assume it is a 'round-trip flight'
{% hint style="info" %} **Note on Data Persistence:** When an Action successfully captures specific data, this information is automatically preserved in the conversation context. This persistence creates an important consideration for multi-agent workflows: If you want a subsequent agent to explicitly verify or reconfirm this information with the user, you must clearly state this requirement in that agent's instruction field. Without such explicit instructions, the following agent will assume this information is already validated and will suppress redundant questions or confirmations. {% endhint %} These fields collectively form the framework that enables an agent to properly understand, process, and respond to user inputs while executing the specific tasks needed to achieve its goals. ## Tools If you need to execute an API call, add a [Service cell ](/user-guide/build-dialogs/dialog-cells/services.md)right after after the desired action in the workflow. It can be a Webhook or a Rest Connector cell, mechanisms that transforms the Action's intent into concrete API interactions, allowing the agent to retrieve or manipulate data needed to fulfill its purpose. In the example, a Rest cell was chosen to perform an API call. At a visual level, you’ll see the Agent cell and the branches for each Action added and for error handling. In this case, *itinerary\_option* and *destination\_recommender*, and the button *error*.

SCAI Workspace

## Action templates Examples of actions to speed up your agent creation process. Adapt and change according to your business cases.
Actions to trigger tools #### **Customer Satisfaction Survey** * **Name**: `collect_satisfaction_feedback` * **Description**: Request an evaluation of the experience and a rating from 1 to 5, and then sends this information to the customer service. Asks if there is any optional comments they may want to share. * **Parameters**: * `rating` (number): User satisfaction score. A number from 1 to 5, where 1 is very dissatisfied and 5 is very satisfied. * `comments` (string): Text input with feedback. * `recommend_to_others` (boolean): Would recommend to others *** #### **Customer Lookup or Identification** * **Name**: `identify_customer` * **Description**: Request key information to identify the customer, such as name, ID, or contact details. Use the inputs to search for the customer in the system. * **Parameters**: * `customer_id` (string): Unique identifier, if available. * `email` (string): Email address. * `phone` (string): Phone number. *** #### **Transfer to Human Agent** * **Name**: `handover_to_human` * **Description**: Initiate the handover process to a live agent. Collect necessary context and inform the user about the transfer. * **Parameters**: * `reason` (string): Reason for the handover. * `urgency` (string): Optional level of urgency (e.g., low, medium, high). *** #### **Offer Search** * **Name**: `search_offers` * **Description**: Search for available offers or promotions based on the user’s preferences or profile. * **Parameters**: * `category` (string): Type of offer or service area (e.g., internet, mobile, insurance). * `location` (string): Optional filter by user’s region. * `customer_segment` (string): Customer type or profile (e.g., new customer, existing, premium). *** #### **Schedule technical visit** * **Name**: `schedule_technical_visit` * **Description**: Collect necessary data from the user to schedule a technical visit, such as date preferences and address. All visits have a 3-hour window: 9 to 12, from 12 to 15, from 15 to 18 and from 18 to 20. If someone asks to schedule at any moment within any of those windows, inform the schedule will be within this range. * **Parameters**: * `timetable` (string): Refers to the start time of one of these ranges: 9-12, 13-15, 16-18. Entries within these ranges must be the initial value. * `preferred_date` (string): User’s preferred date for the visit. The day must be informed. * `address` (string): Location for the visit. * `issue_type` (string): Brief description of the issue to be resolved. *** #### **Collect data for API calls (transactional services)** * **Name**: `collect_api_data` * **Description**: Gather structured data from the user required to trigger a transactional API call, such as service request, purchase, or account update. * **Parameters**: * `operation_type` (string): Type of operation (e.g., payment, subscription update). * `required_fields` (object): Key-value pairs with the necessary inputs (e.g., `{"account_id": "12345", "amount": "50.00`
Channel customization and text formatting #### **Web** * **Name**: `customize_web_response` * **Description**: Format and adjust the response for a web-based chat interface. Prioritize clarity, readability, and proper formatting using HTML or line breaks when needed. Avoid emojis or informal tone. * **Parameters**: * `format_type` (string): Optional format style (e.g., paragraph, bullet list). * **Variable:** web\_response *** #### **Facebook/Meta** * **Name**: `customize_facebook_response` * **Description**: Adapt the response for Facebook Messenger or Meta platforms. Keep the tone conversational and friendly. Emojis are allowed. Keep messages short and engaging, using quick replies or buttons when appropriate. * **Parameters**: * `facebook_custom` (string): Facebook-formatted response ready for delivery * **Variable:** custom\_response *** #### **WhatsApp** * **Name**: `customize_whatsapp_response` * **Description**: If there is a list of topics, use bullet points. Format the response for WhatsApp. Use markdown where supported (bold, italics), and avoid long paragraphs. Keep messages compact and mobile-friendly. Split long responses into multiple shorter messages when necessary. * **Parameters**: * `whatsapp_response` (string): WhatsApp-formatted response ready for delivery * **Variable:** wpp\_response *** #### **HMTL Formatting** * **Name**: `format_html_response` * **Description**: This action should be triggered whenever the agent is going to deliver a response to the user, with the aim of formatting the HTML content. It organizes the text in a structured and visually clear way, applying HTML styles and markups according to the context of the response, ensuring a richer and more interactive presentation of the information. * **Parameters**: * `html_response` (string): Always format all answers using HTML. Use the following guidelines to present the content: 1\. List items or options using HTML tags \`\
After the branch for the formatting actions, add an answer cell with the variable registered in the parameters.
--- # 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.conversational-ai.syntphony.com/user-guide/ai-agents/actions.md?ask= ``` 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.