If you need an agent to send messages to your Discord community and/or retrieve Discord messages to action, DiscordAgent can help you.

Installation#

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

pip install ag2[openai,commsagent-discord]

Capabilities#

DiscordAgent 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. - 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.

It will also automatically append Discord's messaging requirements to the system message:

• 2,000 character limit
• Markdown
• bold/italic/code
• use emojis

This is on by default, but you can turn these off by setting has_writing_instructions to False when creating the agent.

In-built Tools#

The DiscordAgent has two in-built tools that it will call upon as it needs:

• DiscordSendTool
• DiscordRetrieveTool

Find out more about these tools and how you can add them to your own AG2 agents in the Discord Tools documentation.

Platform configuration#

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

DiscordAgent requires 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#

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.

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.