SlackAgent Code Submission

This code submission is provided exclusively for the EMNLP conference review process.

IMPORTANT NOTICE:

• This code is submitted solely for academic review purposes as part of our EMNLP submission
• This code is NOT intended for public distribution or commercial use
• All rights reserved by Salesforce
• Please do not redistribute or share this code outside of the review process

For any questions regarding this submission, please contact the authors through the conference review system.

---

SlackAgents: Scalable Collaboration of Multiple AI Agents in Workspaces

Installation | Quick Start | Multi-Agent Collaboration | Proactive Agent | CLI | Build Your Own Workflow | Examples

---

🤖 SlackAgents is a flexible library designed to facilitate the deployment of AI agents within your Slack workspaces. It supports scalable multi-agent collaboration and management, making it an ideal choice for organizations looking to enhance their Slack environments with agentic automation.

🌟 Key Features

• Scalable Multi-Agent Collaboration: Easily manage and deploy multiple agents within Slack.
• Integration with OpenAI: Leverage powerful language models to enhance agent capabilities.
• Customizable and Extensible: Build custom tools and workflows tailored to your needs.
• User-Friendly CLI: Simplifies agent management with intuitive commands.

📁 Repository Overview

The repository is structured as follows:

• src/slackagents: Contains the main implementation of the SlackAgents library.
• app: Includes Slack application-specific code and configurations.
• examples: Provides example scripts and notebooks to demonstrate the usage of SlackAgents.
• tests: Contains unit tests for the library.

🔧 Installation

Create a new conda environment:

conda create -n slackagents python=3.12 -y
conda activate slackagents

To install the package, use pip:

pip install slackagents

For development purposes, we recommend you install the package using poetry:

pip install poetry
poetry install

Finally, set the necessary environment variables by exporting them in your terminal session. For example:

export OPENAI_API_KEY=your_openai_api_key

🚀 Quick Start

Follow these steps to quickly set up and start using SlackAgents to create an assistant agent in Slack:

1. Create Your Slack App

Option 1: (Recommended) Use the Slack Manifest and slack_sdk API

We recommend using the Slack manifest to set up your Slack app. An example manifest JSON file is provided in the app/your_first_slack_assistant folder.

Before getting started, obtain your App Configuration Access Token here and export it as an environment variable:

export SLACK_APP_CONFIG_TOKEN=xoxe.xoxp...

Next, go to the app/your_first_slack_assistant folder, or copy this folder and rename it accordingly. Then update the agent_config.json file with your agent's name and description. These values will automatically populate the following fields in the example_manifest.json file: display_information.name, display_information.description, and features.bot_user.display_name.

This is handled by our create_slack_app.py script. To create the Slack app, run the following command, optionally specifying paths to your configuration files:

cd app/your_first_slack_assistant
python create_slack_app.py --manifest example_manifest.json --agent-config agent_config.json

Once the app is created, you can find it in the Slack App Dashboard. The script will also save the App ID in the slack_bolt_id.json file. You will need to update this file later with the corresponding tokens.

Refer to Step 1-6 in Tokens and Installing Apps to set up your App-level tokens with connections:write scope under the Basic Information section, and Bot tokens under the OAuth & Permissions section.

After that, make sure you select the Allow users to send Slash commands and messages from the messages tab option in the App Home section, and reinstall the App to your workspace. Since we are using an example manifest, no additional scope modifications are needed. You can learn more about these scopes here.

After completing these steps, you should have the following credentials:

• App ID: Found in the Basic Information section of your app's dashboard.
• SLACK_BOT_TOKEN: Found in the OAuth & Permissions section of your app's dashboard (e.g., xoxb-...).
• SLACK_APP_TOKEN: Found in the Basic Information section of your app's dashboard (e.g., xapp-...).

Option 2: Manually Create the App

1. Follow the Slack Bolt Python Getting Started Guide to set up your Slack app.
2. Complete these steps:
   • Create an App
   • Tokens and Installing Apps
   • Setting Up Events

Ensure that you select both:

• Allow users to send Slash commands and messages from the messages tab
• Always Show My Bot as Online (in the App Home section).

After completing these steps, you should have the following credentials:

• App ID: Found in the Basic Information section of your app's dashboard.
• SLACK_BOT_TOKEN: Found in the OAuth & Permissions section of your app's dashboard.
• SLACK_APP_TOKEN: Found in the Basic Information section of your app's dashboard (e.g., xapp-...).

Additionally, ensure that your app has these scopes: groups:read, channels:history, channels:read, im:history, chat:write, users:read, im:read, and app_mentions:read. You can check and add them in the OAuth & Permissions section of your app's dashboard.

2. Configure Your Slack Bolt ID and Enable the Direct Message Feature

Update the slack_bolt_id.json file with your App ID, SLACK_BOT_TOKEN, and SLACK_APP_TOKEN.

To enable direct messaging, follow these steps:

1. Go to the Slack App Dashboard.
2. In the left sidebar, click on the App Home tab.
3. Scroll to the Messages Tab section and check the box labeled Allow users to send Slash commands and messages from the messages tab.

After enabling this setting, reinstall the app by navigating to the OAuth & Permissions section and clicking Reinstall App. Then, refresh or restart your Slack client (use Ctrl+R on Windows/Linux or Cmd+R on Mac).

Note: Sometimes, the message window may not appear immediately after creating the app. If this happens, please be patient and try restarting Slack after a few minutes.

3. Start Your Agent

To launch your direct message agent, execute the following command:

python my_agent.py --type dm --agent-config agent_config.json --bolt-config slack_bolt_id.json

You can choose from type dm or assistant, where the later one will respond to you whenver you @ it in a channel. Read me the tutorial here for more details.

4. Interact with Your Agent in Slack

Once your agent is running, you can interact with it directly in Slack by searching for it under Apps or the General Search Window Bar. Simply send messages to your app in Slack, and your agent will respond accordingly.

If you're unable to send direct messages to the app, please revisit Step 2 to ensure that everything is set up correctly.

🤝 Multi-Agent Collaboration in a Slack Channel

This guide will walk you through setting up multi-agent collaboration in a Slack channel using SlackAgents. Follow the steps below to configure the bot, set up colleagues, and enable collaboration.

1. Set Up Bolt Configuration

One of the key features of SlackAgents is its ability to interact with users in a Slack channel. To enable this feature, you need to:

a. Invite the Bot to the Channel

First, invite your bot to the channel where you want it to participate. This allows the bot to listen and respond to messages from users.

b. Obtain the Bot's user_id

To properly configure the bot, you'll need its user_id within the channel. Here's how to get it:

1. Click on the bot's icon in the channel.
2. Look for the Member ID, which will appear in the format UXXXXXXXXX.

This user_id is crucial as it will be used as one of the dictionary keys in your configuration. For more details on how to retrieve and use user_id, refer to this link and this link.

c. Update the Bot's ID in Code

Once you have obtained the user_id, update the slack_bolt_id.py file by replacing the placeholder with the actual user_id you retrieved.

2. Set Up Colleagues for Multi-Agent Collaboration

To enable multi-agent collaboration within a Slack channel, you need to define "colleagues" for your agent. This setup allows multiple agents (or users) to interact with each other within the same workspace.

a. Define Colleagues

The colleagues' configuration is a dictionary that maps each colleague's user_id to their name and description. This dictionary sets up a collaborative environment for agents within the channel.

• Ensure that your own user_id and those of other users who wish to interact with the agent are included in the get_channel_user_ids_and_names function.
• If you want your agent to collaborate with other agents, include their user_id in this dictionary.

For an enhanced collaboration experience, provide detailed information about each colleague in their corresponding description field.

Example Colleagues Dictionary:

colleagues = {
    "UXXXXXXXXX": {"name": "AgentA", "description": "Handles customer queries"},
    "UYYYYYYYYY": {"name": "AgentB", "description": "Specializes in technical support"}
}

3. Restarting Your Agent

After updating your configuration, ensure that any previously running instance of your agent is shut down. Then, restart it using the following command:

python examples/slack_agent/slack_agent_run.py

4. Start Chatting with Your Agent in Slack

Once everything is set up, you can now interact with your agent by mentioning it directly in the Slack channel. The agent will respond based on its configuration and collaborate with other agents or users as specified.

🙋🏻 Proactive Agent Assistant

The Proactive Agent Assistant is a demonstration of our advanced Slack agent, AgentPro, designed to enhance workplace communication by seamlessly integrating AI assistance into natural conversations. This demo is located in the app/proactive_assistant directory.

Key Features

• Contextual Awareness: AgentPro understands ongoing discussions and provides relevant information to enhance the conversation.
• Selective Engagement: The agent engages only when necessary, ensuring it does not interrupt the flow of communication.
• Proactive Assistance: Offers assistance when directly addressed or when it identifies a need, ensuring timely and relevant support.
• Google Search Tool: Utilizes the SerpAPI to perform web searches, providing real-time information to users.

For more detailed information, please refer to the app/proactive_assistant/README.md.

💻 Command Line Interface (CLI)

SlackAgents offers a command-line interface to facilitate the management of AI agents within your Slack workspace. The following commands are available:

Getting Started

The CLI is super simple to use:

slackagents [COMMAND] [OPTIONS]

Need help? Just run slackagents in terminal to see all available commands!

Available Commands

Create a New Agent

slackagents create

This interactive wizard will guide you through creating a new agent step by step. Perfect for getting started!

Add an Existing Agent

slackagents add [FOLDER_PATH]

This command will add an existing agent in a standard SlackAgents app folder structure to the CLI for management. FOLDER_PATH is the relative or absolute path to the folder that contains the agent's app.py file.

List Your Agents

slackagents list

See all your agents at a glance! This command shows: APP_ID, Agent Name, Current Status, Agent Type, and more in --verbose mode! Users should use this command to monitor the status of the agents and get the APP_ID of the agents they want to start or stop.

Start an Agent

slackagents start [APP_ID]

Got your APP_ID from the list command? Fire up your agent with this simple command!

Stop an Agent

slackagents stop [APP_ID]

Need to pause an agent? No problem! Just stop it with this command.

Delete an Agent

slackagents delete [APP_ID]

Want to remove an agent completely? This command will clean up everything related to the specified agent.

Pro Tips

• Always start with slackagents list to get an overview of your agents
• Use the --help flag with any command for detailed information
• Keep track of your APP_IDs - they're your keys to managing specific agents!

Here are my suggestions for improving the section, including a better name and some additional refinements:

🧑‍💻 Build Your Own Agent and Workflow

This section provides an overview of how to set up individual agents and create complex workflows using SlackAgents. You'll learn how to configure assistants for specific tasks and combine them into workflows that automate multi-step processes.

🤖 Assistant

Assistants are the core building blocks of SlackAgents. They are designed to interact with users and perform various tasks across channels and direct messages (DMs). Below is an example of an assistant that performs mathematical operations:

from slackagents import Assistant, FunctionTool, OpenAILLM, BaseLLMConfig

def multiply(a: float, b: float) -> float:
    """Multiplies two numbers."""
    return a * b

# Create a tool from the multiply function
multiply_tool = FunctionTool.from_function(function=multiply)

# Initialize the LLM
llm_config = BaseLLMConfig(model="gpt-4o", temperature=0.7)
llm = OpenAILLM(config=llm_config)

# Create an assistant
assistant = Assistant(
    name="Math Assistant",
    desc="An assistant that can perform mathematical operations.",
    llm=llm,
    tools=[multiply_tool],
    verbose=True
)

# Interact with the assistant
response = assistant.chat("What's 5 times 7?")
print(response)

In this example:

• The multiply function is wrapped as a tool using FunctionTool.
• The assistant is powered by OpenAI's GPT model (gpt-4o) with a custom configuration.
• The assistant can now respond to mathematical queries in Slack or other channels.

🔄 Workflow Agent

The WorkflowAgent allows you to create complex workflows involving multiple agents. Each agent in the workflow performs specific tasks, and transitions define how agents pass information between each other.

Here's an example workflow for automating employee quarterly check-ins:

from slackagents import Assistant, WorkflowAgent, FunctionTool
from slackagents.graph.execution_graph import ExecutionGraph, ExecutionTransition

# Define tools for each agent
def load_jira_record_tool(employee_id: str):
    # Implementation...

def write_tool(content: str, document_name: str):
    # Implementation...

def load_employee_calendar_tool(employee_id: str):
    # Implementation...

def send_calendar_invite_tool(employee_id: str, time_slot: str, meeting_title: str, notes: str):
    # Implementation...

def send_email_tool(employee_id: str, subject: str, body: str):
    # Implementation...

# Create agents with specific roles
data_agent = Assistant(
    name="Data Agent",
    desc="AI agent designed to load an employee's Jira record and generate a report for the quarterly check-in meeting.",
    tools=[
        FunctionTool.from_function(load_jira_record_tool),
        FunctionTool.from_function(write_tool),
    ],
    system_prompt="...",  # Define system prompt
)

calendar_agent = Assistant(
    name="Calendar Agent",
    desc="AI agent designed to load an employee's calendar and send the calendar invites",
    tools=[
        FunctionTool.from_function(load_employee_calendar_tool),
        FunctionTool.from_function(send_calendar_invite_tool)
    ],
    system_prompt="...",  # Define system prompt
)

email_agent = Assistant(
    name="Email Agent",
    desc="AI agent designed to send emails to employees",
    tools=[FunctionTool.from_function(send_email_tool)],
    system_prompt="...",  # Define system prompt
)

# Create execution graph
graph = ExecutionGraph()
graph.add_agent(data_agent)
graph.add_agent(calendar_agent)
graph.add_agent(email_agent)

# Define transitions between agents
graph.add_transition(
    ExecutionTransition(
        source_module=graph.get_module("Data Agent"), 
        target_module=graph.get_module("Calendar Agent"), 
        desc="When the report written to the employee's local directory, you should schedule the meeting with the employees."
    )
)

graph.add_transition(
    ExecutionTransition(
        source_module=graph.get_module("Calendar Agent"), 
        target_module=graph.get_module("Email Agent"), 
        desc="Once the meeting is scheduled, send email notifications."
    )
)

# Set initial agent in the workflow
graph.set_initial_module(graph.get_module("Data Agent"))

# Create WorkflowAgent for quarterly check-ins
quarterly_checkin_agent = WorkflowAgent(
    name="Quarterly Check-in Workflow",
    desc="Workflow designed to automate the employee quarterly check-in process",
    graph=graph,
    verbose=True
)

# Use the WorkflowAgent to start the process
response = quarterly_checkin_agent.chat("The quarterly check-in is due in a week. Please help prepare.")
print(response)

In this example:

• Data Agent loads Jira records and generates reports.
• Calendar Agent schedules meetings based on employee calendars.
• Email Agent sends notifications once meetings are scheduled.
• Transitions define when one agent passes control to another based on task completion.

📚 Main Modules and APIs

SlackAgents provides several key modules and APIs that form its core functionality. Here’s an overview of some of the most important ones:

Module/API	Description	File Reference
Assistant	A base class for creating AI assistants	src/slackagents/agent/assistant.py
WorkflowAgent	An agent designed for executing multi-step workflows	src/slackagents/agent/workflow_agent.py
SlackAssistant	An AI assistant integrated with Slack	src/slackagents/agent/slack_assistant.py
SlackWorkflowAgent	A workflow agent integrated with Slack	src/slackagents/agent/slack_workflow_agent.py
SlackDMAgent	An agent for handling direct messages in Slack	src/slackagents/agent/slack_dm_agent.py
FunctionTool	A tool for creating custom functions that agents can use	src/slackagents/tools/function_tool.py
OpenAPITool	A tool for integrating OpenAPI specifications	src/slackagents/tools/openapi_tool.py
OpenAILLM	An interface for OpenAI's language models	src/slackagents/llms/openai.py
BaseLLMConfig	A configuration class for language models	src/slackagents/llms/openai.py

These modules and APIs provide a comprehensive toolkit for building AI-powered agents within Slack workspaces. Whether you're creating simple assistants or complex workflows, these components offer flexibility and power.

🔍 Examples

For more detailed examples, please check the examples folder in the repository. It contains notebooks demonstrating various use cases, including:

• Creating custom tools
• Using OpenAPI specifications
• Integrating with Slack
• Building workflow agents
• Automating employee quarterly check-ins

🧪 Tests

unittests is used to run our tests. You can run the following command to run the tests:

sh scripts/tests.sh

📦 Publish on PyPi

Important: Before publishing, edit __version__ in src/init to match the wanted new version.

poetry build
poetry publish

📞 Contact

For questions or suggestions, please reach out by submitting an issue or pull request, or send an email to the project maintainers.