Skip to main content
The Discord Bot integration allows you to serve Agents or Teams via Discord, using the discord.py library to handle Discord events and send messages.

​
Setup Steps

​
Setup and Configuration

1

Prerequisites

Ensure you have the following:
  • Python 3.7+
  • A Discord account with server management permissions
  • Required Python packages (will be installed in later steps)
2

Create a Discord Application

  1. Go to Discord Developer Portal
  2. Click "New Application"
  3. Provide an application name (e.g., "My Agno Bot")
  4. Accept the Developer Terms of Service
  5. Click "Create"
3

Create a Bot User

  1. In your application settings, navigate to the "Bot" section
  2. Click "Add Bot"
  3. Confirm by clicking "Yes, do it!"
  4. Under the "Token" section, click "Copy" to copy your bot token
  5. Save this token securely (you'll need it later)
4

Configure Bot Permissions and Intents

  1. In the Bot settings, scroll down to "Privileged Gateway Intents"
  2. Enable the following intents:
    • Presence Intent (optional, for user status)
    • Server Members Intent (for member-related events)
    • Message Content Intent (required for reading message content)
  3. Under "Bot Permissions", ensure your bot has:
    • Send Messages
    • Read Message History
    • Create Public Threads
    • Use Slash Commands (optional)
5

Setup Environment Variables

Create a .envrc file in your project root with the following content, replacing the placeholder with your actual bot token:
export DISCORD_BOT_TOKEN="your_bot_token_here"
Find your bot token in the Discord Developer Portal under "Bot" > "Token".Ensure this file is sourced by your shell (e.g., by using direnv allow).
6

Install Required Packages

Install the necessary Python packages:
pip install discord.py agno
7

Invite Bot to Your Discord Server

  1. In your application settings, go to "OAuth2" > "URL Generator"
  2. Under "Scopes", select:
    • bot
    • applications.commands (if using slash commands)
  3. Under "Bot Permissions", select the permissions your bot needs:
    • Send Messages
    • Create Public Threads
    • Read Message History
    • Attach Files
    • Embed Links
    • Use External Emojis (optional)
  4. Copy the generated URL, navigate to it in your browser, and select the server where you want to add the bot
8

Test Your Bot

  1. Start your bot application
  2. Go to your Discord server
  3. Send a message in any channel where your bot has access
  4. Your bot should automatically create a thread and respond
  5. If using a media bot, try uploading an image or file to test media processing

​
Example Usage

Create an agent, wrap it with DiscordClient, and run it: 
from agno.agent import Agent
from agno.app.discord import DiscordClient
from agno.models.openai import OpenAIChat

basic_agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-4o"), 
    add_history_to_messages=True,
    num_history_responses=3,
    add_datetime_to_instructions=True,
)

discord_agent = DiscordClient(basic_agent)
if __name__ == "__main__":
    discord_agent.serve()

​
Core Components

  • DiscordClient: Wraps Agno agents/teams for Discord integration using discord.py.
  • DiscordClient.serve: Starts the Discord bot client with the provided token.

​
DiscordClient Class

Main entry point for Agno Discord bot applications.

​
Initialization Parameters

ParameterTypeDefaultDescription
agentOptional[Agent]NoneAgno Agent instance.
teamOptional[Team]NoneAgno Team instance.
Provide agent or team, not both.

​
Event Handling

The Discord bot automatically handles various Discord events:

​
Message Events

  • Description: Processes all incoming messages from users
  • Media Support: Handles images, videos, audio files, and documents
  • Threading: Automatically creates threads for conversations
  • Features:
    • Automatic thread creation for each conversation
    • Media processing and forwarding to agents
    • Message splitting for responses longer than 1500 characters
    • Support for reasoning content display
    • Context enrichment with username and message URL

​
Supported Media Types

  • Images: Direct URL processing for image analysis
  • Videos: Downloads and processes video content
  • Audio: URL-based audio processing
  • Files: Downloads and processes document attachments

​
Environment Variables

Ensure the following environment variable is set: 
export DISCORD_BOT_TOKEN="your-discord-bot-token"

​
Message Processing

The bot processes messages with the following workflow:
  1. Message Reception: Receives messages from Discord channels
  2. Media Processing: Downloads and processes any attached media
  3. Thread Management: Creates or uses existing threads for conversations
  4. Agent/Team Execution: Forwards the message and media to the configured agent or team
  5. Response Handling: Sends the response back to Discord, splitting long messages if necessary
  6. Reasoning Display: Shows reasoning content in italics if available

​
Features

​
Automatic Thread Creation

  • Creates a new thread for each user’s first message
  • Maintains conversation context within threads
  • Uses the format: {username}'s thread

​
Media Support

  • Images: Passed as Image objects with URLs
  • Videos: Downloaded and passed as Video objects with content
  • Audio: Passed as Audio objects with URLs
  • Files: Downloaded and passed as File objects with content

​
Message Formatting

  • Long messages (>1500 characters) are automatically split
  • Reasoning content is displayed in italics
  • Batch numbering for split messages: [1/3] message content

​
Testing the Integration

  1. Set up your Discord bot token: export DISCORD_BOT_TOKEN="your-token"
  2. Run your application: python your_discord_bot.py
  3. Invite the bot to your Discord server
  4. Send a message in any channel where the bot has access
  5. The bot will automatically create a thread and respond