Bring your social platforms into your AG2 workflow with DiscordAgent, SlackAgent, and TelegramAgent.

Available as standalone agents or as tools that you can add to your own agents.

These tools are currently in our experimental namespace, indicating that we have tested the functionality but their interface may change. Please use them with that in mind and we appreciate any feedback on them.

If you do find any bugs please log an issue in the AG2 repository. If you would like to add more tools or functionality, we would love your contribution.

Installation

Install AG2 with the necessary extra for the platform(s) you need.

pip install ag2[commsagent-discord]
pip install ag2[commsagent-slack]
pip install ag2[commsagent-telegram]

Capabilities

The send functionality is consistent across agents/send tools, they take a message and post it to the configured channel/group/bot. If a message is longer than the platforms permitted message length, the tool will split the message into multiple messages.

The common retrieve functionality includes:

  • Retrieve the latest X messages from a channel/group/bot.
  • Retrieve messages since a given date.
  • Retrieve messages since a given message ID.
  • Retrieve a message given its ID.

The Telegram retrieve tool also has the ability to retrieve messages using a search string (and this can be done in combination with the retrieval options above).

The agent will automatically determine how to retrieve the messages based on the conversation.

Platform configuration

Each agent/tool is configured for a specific channel/group/bot. This configuration is applied when you create the agent/tool.

Discord, Slack, and Telegram all have their own authentication and channel/group/bot identifiers. See this notebook for more guidance on establishing those authentication details and identifiers.

Using the Agents

The three communication agents have two in-built tools for sending and retrieving messages, respectively. The agents will automatically determine which tool(s) to call based on the conversation (you can influence this by adjusting their system message).

AgentSend ToolRetrieve Tool
DiscordAgentDiscordSendToolDiscordRetrieveTool
SlackAgentSlackSendToolSlackRetrieveTool
TelegramAgentTelegramSendToolTelegramRetrieveTool

As the agents are based on ConversableAgent you can use them in any conversation pattern in AG2.

An important component of the new agents (as opposed to just using their tools) is that the platform’s messaging requirements will be appended to their system message.

They cover aspects like maximum message length, preferred format (e.g. Markdown), and provide tips like using emojis.

AgentSystem Message guidance
DiscordAgent2,000 character limit, Markdown, bold/italic/code, use emojis
SlackAgent40,000 character limit, Markdown, bold/italic/code, emojis, notification formats
TelegramAgent4,096 character limit, HTML, mentions and emojis

These are enabled by default, but you can turn these off by setting has_writing_instructions to False when creating the agent.

Here’s a simple example using the DiscordAgent where we will use both tools by retrieving the latest message and then sending back a poem about it.

# Agents are available in the autogen.agents namespace
from autogen import ConversableAgent
from autogen.agents.experimental import DiscordAgent

# LLM configuration for our agent to select the tools and craft the message
# Put your key in the OPENAI_API_KEY environment variable
llm_config = {"api_type": "openai", "model": "gpt-4o-mini"}

# Tokens and Ids (CHANGE THESE)
my_discord_bot_token = "ABC..."
my_discord_guild_name = "My Discord Server Name"
my_discord_channel_name = "general"

# Create DiscordAgent with defaults
discord_agent = DiscordAgent(
    name="discord_agent",
    llm_config=llm_config,
    bot_token=my_discord_bot_token,
    guild_name=my_discord_guild_name,
    channel_name=my_discord_channel_name,
)

# Tool execution is carried out by another agent
# Will output TERMINATE to end the conversation when complete
tool_executor = ConversableAgent(
    name="tool_executor",
    system_message=(
        "You execute send and retrieve functions for Discord platforms.\n"
        "Respond with 'TERMINATE' when finished."
        ),
    llm_config=llm_config,
    human_input_mode="NEVER",
    )

# Register the tools from the DiscordAgent with the tool_executor for execution
for tool in discord_agent.tools:
    tool.register_for_execution(tool_executor)

# Let's get the latest message from Discord and send one back as a poem.
tool_executor.initiate_chat(
    recipient=discord_agent,
    message="Get the latest message from Discord and send back a message with a poem about it."
)

Here’s the message it retrieved and the poem it sent back.

Code examples

See our blog post for a demonstration of using the communication agents.

For supporting guidance on establishing the relevant authentication tokens and IDs, see this notebook.

Using the Tools directly

You can create and add any of the available communication tools to your agents, empowering your agents with communication abilities.

Here’s a simple example using the Slack tools with a ConversableAgent-based agent to send a weather forecast to a Slack channel.

# Tools are available in the autogen.tools namespace
from autogen import ConversableAgent, register_function
from autogen.tools.experimental import SlackRetrieveTool, SlackSendTool

# LLM configuration for our agent to select the tools and craft the message
# Put your key in the OPENAI_API_KEY environment variable
llm_config = {"api_type": "openai", "model": "gpt-4o-mini"}

# Our tool executor agent, which will run the tools once recommended by the slack_agent, no LLM required
executor_agent = ConversableAgent(
    name="executor_agent",
    human_input_mode="NEVER",
)

# The main star of the show, our ConversableAgent-based agent
# We will attach the tools to this agent
slack_agent = ConversableAgent(
    name="slack_agent",
    llm_config=llm_config,
)

# Create tools and register them with the agents

_bot_token = "xoxo..."  # CHANGE THIS, OAuth token
_channel_id = "C1234567"  # CHANGE THIS, ID of the Slack channel

# Create our Send tool
slack_send_tool = SlackSendTool(bot_token=_bot_token, channel_id=_channel_id)

# Register it for recommendation by our Slack agent
slack_send_tool.register_for_llm(slack_agent)

# Register it for execution by our executor agent
slack_send_tool.register_for_execution(executor_agent)

# And the same for our our Retrieve tool
slack_retrieve_tool = SlackRetrieveTool(bot_token=_bot_token, channel_id=_channel_id)
slack_retrieve_tool.register_for_llm(slack_agent)
slack_retrieve_tool.register_for_execution(executor_agent)

# Here we create a dummy weather function that will be used by our agent
def get_weather():
    return "The weather today is 25 degrees Celsius and sunny, with a late storm."

# Register it with the slack_agent for LLM tool recommendations
# and the executor_agent to execute it
register_function(
    get_weather,
    caller=slack_agent,
    executor=executor_agent,
    description="Get the current weather forecast",
)

# Start the conversation
# The slack_agent suggests the weather and send tools, crafting the Slack message
# while the executor_agent executes the weather tool and the Slack send tool
executor_agent.initiate_chat(
    recipient=slack_agent,
    message="Get the latest weather forecast and send it to our Slack channel. Use some emojis to make it fun!",
    max_turns=3,
)

The main difference between this example and using the SlackAgent agent is that the agent in this example doesn’t have the Slack-specific system message, including formatting instructions.

Code examples

See this notebook for examples of using all the communication tools, and guidance on establishing the relevant authentication tokens and IDs.

Tool execution

In AG2 the tool execution is typically handled by a separate agent that will follow the agent in the conversation (unless its an agent in a swarm whereby tools are executed automatically). So, you will need to register the tools with another agent for execution.

You will see an example of this is the examples above and linked blog/notebook.