Actions

Actions are the specific tasks an AI Agent performs to support a given use case. They define what needs to happen to resolve a user request and may include key elements such as:

• Required data to collect;

• Conditions or rules to follow;

• Steps needed to complete the task successfully.

Actions may involve collecting information, executing a request, or applying specific business logic. For transactional actions, service components (service cells) can also be integrated to extend capabilities and enable interactions with external systems, ensuring the action is fully completed.

Action modal fields

New Action

Fill the presented fields:

• Name: Clearly describe the task the action performs.

• Instructions: Describe in detail what the Action does, its purpose, and when it should be triggered. This ensures correct behavior. Also include how properties should be managed at a high level (if any) and their execution order. In short, explain how the action runs and how its properties are handled.

The Name and Instruction fields are critical steps that will determine how to process and execute the Action.

Properties

After defining what the Action should do, the next step is to define how it will achieve its goal.

The Properties block defines the key properties required for the Action. These properties may represent:

• Data to collect;

• Conditions to meet;

• Inputs that guide how the Action runs.

Start by choosing one of two approaches: Basic or Advanced.

In Advanced mode, a JSON file can be used to define all required properties with greater technical precision.

Below 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"]
    }

In Basic mode, Properties can be added individually for easier configuration.

Fill the presented fields:

• Property name;

• Type: Defines the data format (string, boolean, number) the Property accepts;

• Property details: Explains the purpose and expected values for this specific Property;

• Variable: Defines a reference name that can be reused in other parts of the AI Agent workflow. The value can be accessed through $hiddenContext.variable, for example: $hiddenContext.numberOfPassengers (see table);

• Rules: Defines constraints, validations, or conditional behaviors that control how the Property works. These act as tactical directives;

• Make property optional: A toggle that defines whether the Property is required or optional to execute an Action.

For the Action search_flight mentioned above, there are five properties: date, origin, destination, type of flight, and number of passengers. Below is a more detailed breakdown of two of them:

Name	numberOfPassengers	dates
Type	String	String
Details	The 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 2026.
Variable	numberpassengers	--
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'

Note on Data Persistence: When an Action captures data successfully, that information is automatically stored in the conversation context. This is particularly important in multi-agent workflows. If a subsequent AI Agent needs to verify or reconfirm this information, the requirement must be clearly defined in the AI Agent’s Instruction field. Without explicit instructions, the next AI Agent will assume the data has already been validated and will avoid redundant questions or confirmations.

Together, these fields form the structure that enables an AI Agent to understand, process, and respond to user inputs while executing the tasks required to achieve its goals.

Tools

To execute an API call from an Agent workflow, place a Service cell immediately after the Action that should trigger the call.

A Service cell can be configured as a Webhook or a REST Connector, depending on how the external system receives and returns data.

The Action identifies the user’s intent. The Service cell turns that intent into an external API interaction, allowing the AI Agent to retrieve, validate, create, or update the information required to continue the workflow.

In this example, the AI Agent collects the customer’s service request through the collect_service_request_details action. The request details are then sent to the service_request_intake service cell, which structures the request and returns the next routing decision.

Visually, the flow shows the Agent cell, the branch for the configured Action, the Service cell, the successful route_request output, the Knowledge cell, and the error paths.

SCAI Workspace

About the error handling, if the AI Agent cannot complete the request, the error branch is triggered. Add a response cell after the error branch to guide the next step.

Action templates

Examples of Actions to speed up the agent creation process. Adapt them to specific business cases:

Actions to trigger tools

Customer Satisfaction Survey

• Name: collect_satisfaction_feedback

• Details: 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.

• Properties:

  • 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

• Details: 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.

• Properties:

  • customer_id (string): Unique identifier, if available.

  • email (string): Email address.

  • phone (string): Phone number.

---

Transfer to Human Agent

• Name: handover_to_human

• Details: Initiate the handover process to a human agent. Collect necessary context and inform the user about the transfer.

• Properties:

  • reason (string): Reason for the handover.

  • urgency (string): Optional level of urgency (e.g., low, medium, high).

---

Offer Search

• Name: search_offers

• Details: Search for available offers or promotions based on the user’s preferences or profile.

• Properties:

  • 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

• Details: 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.

• Properties:

  • 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

• Details: Gather structured data from the user required to trigger a transactional API call, such as service request, purchase, or account update.

• Properties:

  • 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

• Details: 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.

• Properties:

  • format_type (string): Optional format style (e.g., paragraph, bullet list).

• Variable: web_response

---

Facebook/Meta

• Name: customize_facebook_response

• Details: 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.

• Properties:

  • 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

---

HTML formatting

• Name: format_html_response

• Description: This action should be triggered whenever the AI 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 `<ul>` and `<li>` to create an organized list.

    2. Highlight important names or key terms using the `<strong>` tag for bold.

    3. Use paragraphs `<p>` to separate blocks of text, ensuring visual organization.

    4. All formatting must be semantically correct in HTML.

    5. Responsive resolution (mobile version)

    The output must be well structured to be used directly on any HTML page.

• Variable: html_response

After the branch for the formatting Actions, add an Answer Cell with the variable registered in the properties.