Creating a Custom Tool to Send Messages on Slack

Introduction

BrainSoup is a versatile AI platform offering users the ability to easily extend AI agents' capabilities through the creation of Custom Tools. These tools empower agents to interact with external systems to gather information or perform specific tasks beyond their built-in capabilities. This tutorial will walk you through the process of creating a Custom Tool, using the Slack tool as an example. This tool enables BrainSoup agents to send messages to Slack channels, demonstrating how you can integrate external services into your BrainSoup environment. It is already included in the BrainSoup distribution for your reference, you can find it in the Tools/Custom directory.

The Slack Custom Tool Example

The Slack tool serves as a practical example of how Custom Tools can be structured and implemented within BrainSoup. It consists of three files:

  • manifest.json - Defines the tool, its functions, and parameters.
  • config.ps1 - Contains configuration settings, such as API keys or webhooks.
  • send.ps1 - The script that executes the tool's main functionality.

Note: For this example, the scripting language used is PowerShell, due to its native support on Windows systems, but you are free to use any language as long as the corresponding interpreter is installed on the system.

Tip: Doc-E, BrainSoup's built-in expert agent, can greatly assist you in creating Custom Tools and may event write the scripts for you. Simply describe the tool you want to create, and Doc-E will generate the necessary code in the language of your choice! 💪🤖

manifest.json

The manifest file serves both to explain to the agent what the tool is for, how to use it, and to BrainSoup which command to run (in this case, a PowerShell script) when an agent uses the tool. It must follow a specific structure to be correctly interpreted by BrainSoup. You can learn more about the manifest file in this article.

{
    "description": "Send messages to Slack channels",
    "functions": [
        {
            "name": "Send",
            "description": "Send a message to the Slack channel. No need to introduce yourself as your name is already displayed.",
            "parameters": [
                {
                    "name": "message",
                    "description": "Content of the message",
                    "isRequired": true
                }
            ],
            "command": "powershell -File {{toolPath}}send.ps1",
            "timeout": 10
        }
    ]
}

config.ps1

This configuration file is crucial for separating sensitive information (like webhooks, API keys, credentials, etc.) from your script logic. Keeping configurations in separate files allows for easier updates and maintenance without altering the core script and make your Custom Tool easier to share with others. In the Slack example, the config.ps1 file is trivial, but for more complex tools, it can contain multiple settings.

# WebHook of a Slack channel
# To get the WebHook URL, go to https://my.slack.com/apps/A0F7XDUAZ-incoming-webhooks
$WebHook = ''

send.ps1

The PowerShell script performs the action of sending a message to a specified Slack channel. It loads settings from config.ps1 , constructs a request with headers and body content, then sends this data to Slack's webhook URL.

# Load configuration
. config.ps1

# Check arguments
if ([string]::IsNullOrWhiteSpace($WebHook)) {
    Write-Error "WebHook is not set in the config.ps1 file of the Slack custom tool."
    exit 1
}

# Build request
$Headers = @{
    'Content-Type' = 'application/json; charset=utf-8'
}
$Body = @{
    username = $env:ARGS_AGENTNAME
    text  = $env:ARGS_MESSAGE
    icon_url = $env:ARGS_AGENTAVATARURL
} | ConvertTo-Json

# Encode body to UTF8 to make sure non-ASCII characters are handled correctly
$BodyUtf8 = [System.Text.Encoding]::UTF8.GetBytes($Body)

# Send request
$Response = Invoke-WebRequest -Method Post -Uri $WebHook -Headers $Headers -Body $BodyUtf8

Testing Your Custom Tool

After placing your Custom Tool in the Tools/Custom directory of BrainSoup, it's automatically recognized by the system—no restart required. To test it:

  1. Authorize an agent to use this tool by adding it to their Allowed tools list.
  2. Ask the agent to perform a task involving the use of the tool. For example, you can ask the agent to send a message to the Slack channel.
  3. Review Technical details in agent's response to confirm successful execution.

Tips:

  • You can quickly access the Tools folder from the BrainSoup interface by going to Settings > App Folders > Tools.
  • The Technical details are accessible by clicking on the small circled 'i' button located at the top right of the message.

Conclusion

Custom Tools like the Slack example offer powerful ways to expand BrainSoup's capabilities, integrating external services directly into your workflows. By following best practices for structure and configuration, you can create robust tools that enhance your agents' abilities while maintaining security and ease of maintenance. Whether you're automating notifications or integrating complex systems, Custom Tools unlock endless possibilities for personalized automation within BrainSoup.

Remember, this guide merely scratches the surface of what's possible with Custom Tools in BrainSoup. For further details on Tools and Custom Tools, visit this dedicated article in the BrainSoup documentation.

Related Articles