> For the complete documentation index, see [llms.txt](https://docs-conversational-ai.syntphony.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-conversational-ai.syntphony.com/ai-agents/actions.md). # 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. {% hint style="info" %} The Name and Instruction fields are critical steps that will determine how to process and execute the Action. {% endhint %} ## 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:
NamenumberOfPassengersdates
TypeStringString
DetailsThe 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.
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 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. {% endhint %} 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**](/build-dialogs/dialog-cells/services.md) 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**,](/ai-agents/ai-agents.md#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

{% hint style="info" %} 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. {% endhint %} ## 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 \`\
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs-conversational-ai.syntphony.com/ai-agents/actions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.