Making your Agents React to External Events

Introduction

Custom Events in BrainSoup allow for the dynamic injection of data into chat rooms via special messages. This enable agents to activate and perform tasks autonomously, paving the way for advanced automation within the platform. To learn more about events in BrainSoup, you can refer to this dedicated article. The current article focuses on Custom Events—how to create them, send them, and make your agents react to them.

Possible Uses

One of the primary uses of Custom Events is to facilitate task automation in background chat rooms. This feature allows agents to operate without direct user intervention, streamlining workflows and enhancing productivity. This can be for example:

• Making an agent perform a specific task every day at a certain time.
• Triggering an agent to perform a specific action when a certain data becomes available.

How to Create and Send a Custom Event

Creating a Custom Event involves a few key steps:

Step 1: Defining Your Event

Custom Events must follow a specific JSON structure. For comprehensive details on this structure, please refer to this dedicated article.

Example of a simple Custom Event informing agents about a new order:

{
  "subject": "OrderCreated",
  "displayName": "Order Created",
  "message": "A new order has been created.",
  "data": {
    "orderId": "12345",
    "customerName": "John Doe",
    "totalAmount": 100.00
    "Items": [
      {
        "name": "Product A",
        "quantity": 2,
        "price": 25.00
      },
      {
        "name": "Product B",
        "quantity": 1,
        "price": 50.00
      }
    ]
  }
}

Step 2: Sending Your Event

Place the JSON file representing your Custom Event into the BrainSoup C:\Users\\AppData\Roaming\BrainSoup\Events folder. The name of the file has no importance and can be random. The system automatically consumes these files, triggering the corresponding events. A special message will be displayed in all the chat rooms subscribed to this event, enabling agents to react accordingly.

Step 3: Automation through Scripts

In real scenarios, you will likely want to automate the generation of Custom Events using scripts. This method opens up vast possibilities for integrating external data sources and systems with BrainSoup. For example, you can use a script (e.g., Python, PowerShell, Bash) triggered by your Operating System's scheduler (e.g., Windows Task Scheduler) to generate Custom Events based on specific conditions.

How to Subscribe a Chat Room to an Event

To have a chat room respond to a Custom Event, it must subscribe to the event's Subject. This process involves two main steps:

Step 1: Registering the Event Subject

Ensure the Custom Event has been generated at least once so that BrainSoup recognizes its Subject. This can be done by manually placing the JSON file in the Events folder or by running a script that generates the event.

Step 2: Configuring Chat Room Settings

Navigate to the chat room settings and locate the Event Subscriptions section. Add the Subject of the Custom Event to the list of subscribed events. This action will enable the chat room to receive and react to the event.

Guiding Agent Responses

It's crucial to instruct agents on how they should react upon receiving an event. This guidance can be provided in two ways:

• Through pinned messages within the chat room (pinning a message will prevent agents from forgetting it).
• Embedded within an agent's persona if they are dedicated to handling specific tasks.

Conclusion

Custom Events are a powerful tool within BrainSoup, offering significant flexibility and automation capabilities. By following these guidelines, users can effectively utilize Custom Events to enhance their interactions with agents and connect external systems seamlessly with the platform.