If you want to add the ability for your agents to send and/or retrieve messages for your Discord community DiscordSendTool and DiscordRetrieveTool are easy to add.

If you haven’t had a chance to read about how AG2’s Communication Platform agents and tools work, read the overview first.

​
Installation

Install AG2 with the LLM model provider and Discord platform extra.

pip install ag2[openai,commsagent-discord]

​
Capabilities

DiscordSendTool can:

  • Construct and send a message to the configured channel. If a message is longer than the platforms permitted message length, they will split the message into multiple messages.

DiscordRetrieveTool can:

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

Consider DiscordAgent if you don’t want to build your agent with these tools, it is a ready-to-go AG2 agent that already incorporates the tools and messaging instructions.

​
Platform configuration

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

The tools require authentication (bot token), server (guild name), and channel details in order to send/retrieve messages.

Here are some references to help you establish those details:

  • Creating a Bot Account, and another reference
  • Adding a Bot to a server
  • Bot Permissions you will need:
    • General Permissions: View Channels
    • Text Permissions: Send Messages, Read Message History, Use Slash Commands
  • Server/Guild Name - Right-click the Server > Server Settings > Overview, see the Server Name at the top right (e.g. “My Test Server”)
  • Channel name - The text after the hash (e.g. “general”)

​
Code example

# Tools are available in the autogen.tools namespace
from autogen import ConversableAgent, LLMConfig
from autogen.tools.experimental import DiscordRetrieveTool, DiscordSendTool

# For running the code in Jupyter, use nest_asyncio to allow nested event loops
#import nest_asyncio
#nest_asyncio.apply()

llm_config = LLMConfig(model="gpt-4o-mini", api_type="openai")

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

# Our discord agent, who will construct messages and recommend the tool calls
with llm_config:
    discord_agent = ConversableAgent(name="discord_agent")

_bot_token = "MTMyOTI..."  # Discord bot token
_guild_name = "My Test Server"  # Name of the server
_channel_name = "general"  # Name of the channel, this is equivalent to "# general"

# Create our send tool
discord_send_tool = DiscordSendTool(bot_token=_bot_token, guild_name=_guild_name, channel_name=_channel_name)

# Register it for recommendation by our Discord agent
discord_send_tool.register_for_llm(discord_agent)

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

# And the same for our our retrieve tool
discord_retrieve_tool = DiscordRetrieveTool(bot_token=_bot_token, guild_name=_guild_name, channel_name=_channel_name)
discord_retrieve_tool.register_for_llm(discord_agent)
discord_retrieve_tool.register_for_execution(executor_agent)

# Let’s send a message to Discord, all about the wonders of Australia.
# We’ll limit it to 2 turns, allowing the Discord agent to receive the request,
# construct and recommend the send tool, and then the executor agent to execute the tool,
# sending the message to Discord.
executor_agent.initiate_chat(
    recipient=discord_agent,
    message="Let's send a message to Discord giving them a paragraph on the highlights of Australia.",
    max_turns=2,
)

Here’s the message it sent.

If you want to retrieve the last two messages from the channel:

executor_agent.initiate_chat(
    recipient=discord_agent,
    message="Tell me which countries the last two messages on my Discord channel are about and the main differences.",
    max_turns=2,
)

​
Tool execution

In AG2 the tool execution is typically handled by a separate agent that will follow the agent in the conversation (unless its 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 example code above.

Edit this page