Discord Bot

Host agents as Discord Bots.

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

Prerequisites

Ensure you have the following:

  • Python 3.9+
  • A Discord account with server management permissions
  • Required Python packages (will be installed in later steps)

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"

Create a Bot User

New Discord applications already include a bot user. In the application's Bot settings, select Reset Token to generate the token, then copy and store it securely. Discord only shows the token at creation/reset time. See the Discord quick start.

Configure Bot Permissions and Intents

  1. In the Bot settings, scroll down to "Privileged Gateway Intents"
  2. Enable Message Content Intent for the custom client in the example below. It uses discord.Intents.default() plus message_content=True. If you omit the custom client, DiscordClient requests all intents: Presence, Server Members, and Message Content must all be enabled and approved where Discord requires approval. Requesting an unenabled privileged intent prevents the bot from connecting.
  3. Under "Bot Permissions", ensure your bot has:
    • View Channels
    • Send Messages
    • Send Messages in Threads
    • Read Message History
    • Create Public Threads
    • Use Slash Commands (optional)

Set Environment Variables

Create a .envrc file in your project root with the following content, replacing both placeholders:

export DISCORD_BOT_TOKEN="your_bot_token_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Find your bot token in the Discord Developer Portal under "Bot" > "Token". Create an OpenAI API key in the OpenAI dashboard.

Ensure this file is sourced by your shell (e.g., by using direnv allow).

Install Required Packages

Install the necessary Python packages:

pip install discord.py agno openai sqlalchemy

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:
    • View Channels
    • Send Messages
    • Send Messages in Threads
    • 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

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

Security Note: Never commit your Discord bot token to version control. Always use environment variables or secure configuration management for sensitive data.

Example Usage

Create an agent, wrap it with DiscordClient, and run it:

import discord

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.integrations.discord import DiscordClient
from agno.models.openai import OpenAIChat

basic_agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="discord.db"),
    add_history_to_context=True,
    num_history_runs=3,
    add_datetime_to_context=True,
)

intents = discord.Intents.default()
intents.message_content = True
discord_agent = DiscordClient(basic_agent, client=discord.Client(intents=intents))
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.
clientOptional[discord.Client]NoneCustom discord.py client. If omitted, a client is created with all intents enabled.

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: Examines the first attachment for supported image, video, audio, or application document content
  • Threading: Automatically creates a thread for each message posted directly in a text channel
  • Features:
    • Automatic thread creation for messages posted in text channels
    • Media processing and forwarding to agents
    • Message splitting for responses of 1500 characters or more
    • 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

The adapter checks only the first attachment. Documents must have an application/* content type; text/plain attachments are ignored, and attachments without a content type can fail in the current adapter. File bytes are forwarded without filename or MIME metadata. These are input capabilities: ordinary replies send text and reasoning, not generated media uploads. Confirmation buttons apply to Agent runs, not Team runs or every kind of paused requirement.

Environment Variables

Set the Discord bot token and the OpenAI credential used by this example:

export DISCORD_BOT_TOKEN="your-discord-bot-token"
export OPENAI_API_KEY="your-openai-api-key"

Message Processing

The bot processes messages with the following workflow:

  1. Message Reception: Receives messages from Discord channels
  2. Media Processing: Processes the first attachment when its content type is supported
  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. Confirmation Handling: For an Agent run that pauses for tool confirmation, posts Confirm/Cancel buttons in the thread and resumes the run once the user responds
  6. Reasoning Display: Shows reasoning content in italics if available
  7. Response Handling: Sends the response back to Discord, splitting long messages if necessary

Features

Automatic Thread Creation

  • Creates a new thread for each message posted directly in a text channel
  • Uses the thread ID as the session ID; the example persists history with SQLite
  • 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 or more) are automatically split
  • Reasoning content is displayed in italics
  • Batch numbering for split messages: [1/3] message content

Testing the Integration

  1. Set DISCORD_BOT_TOKEN and OPENAI_API_KEY as shown above.
  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