diff --git a/agent-os/interfaces/discord/introduction.mdx b/agent-os/interfaces/discord/introduction.mdx new file mode 100644 index 00000000..2399aedb --- /dev/null +++ b/agent-os/interfaces/discord/introduction.mdx @@ -0,0 +1,172 @@ +--- +title: Discord +sidebarTitle: "Discord" +description: Host agents as Discord bots with slash commands and @mention support. +--- + +Use the Discord interface to serve Agents, Teams, or Workflows on Discord. It supports two concurrent transports: HTTP webhook for slash commands and Gateway WebSocket for @mentions and DMs. + +## Setup Steps + +Follow the Discord setup guide in the [production docs](/production/interfaces/discord). + +Required configuration: + +- `DISCORD_BOT_TOKEN` (Bot token from the Developer Portal) +- `DISCORD_PUBLIC_KEY` (Application public key for signature verification) +- `DISCORD_APPLICATION_ID` (Application ID for webhook API calls) +- A registered `/ask` slash command +- An ngrok tunnel (for local development) with the Interactions Endpoint URL pointing to `/discord/interactions` + +## Example Usage + +Create an agent, expose it with the `Discord` interface, and serve via `AgentOS`: + +```python basic.py +from agno.agent import Agent +from agno.models.openai import OpenAIChat +from agno.os import AgentOS +from agno.os.interfaces.discord import Discord + +basic_agent = Agent( + name="Basic Agent", + model=OpenAIChat(id="gpt-4o-mini"), + add_history_to_context=True, + num_history_runs=3, + add_datetime_to_context=True, +) + +agent_os = AgentOS( + agents=[basic_agent], + interfaces=[Discord(agent=basic_agent, stream=True)], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="basic:app", port=7777, reload=True) +``` + +## Core Components + +- `Discord` (interface): Wraps an Agno `Agent`, `Team`, or `Workflow` for Discord integration via FastAPI. +- `AgentOS.serve`: Serves the FastAPI app using Uvicorn. + +## `Discord` Interface + +Main entry point for Agno Discord applications. + +### Initialization Parameters + +| Parameter | Type | Default | Description | +| --- | --- | --- | --- | +| `agent` | `Optional[Agent]` | `None` | Agno `Agent` instance. | +| `team` | `Optional[Team]` | `None` | Agno `Team` instance. | +| `workflow` | `Optional[Workflow]` | `None` | Agno `Workflow` instance. | +| `prefix` | `str` | `"/discord"` | Custom FastAPI route prefix. | +| `tags` | `Optional[List[str]]` | `None` | FastAPI route tags. Defaults to `["Discord"]`. | +| `stream` | `bool` | `False` | Enable streaming responses that progressively update the message. Only works for Agent and Team. | +| `show_reasoning` | `bool` | `True` | Show reasoning content (wrapped in italics) before the final answer. | +| `max_message_chars` | `int` | `1900` | Maximum characters per message. Discord's limit is 2000; 1900 leaves room for the `[1/N]` prefix on multi-part messages. | +| `allowed_guild_ids` | `Optional[List[str]]` | `None` | Restrict the bot to specific guild (server) IDs. | +| `allowed_channel_ids` | `Optional[List[str]]` | `None` | Restrict the bot to specific channel IDs. | +| `discord_bot_token` | `Optional[str]` | `None` | Bot token. Falls back to `DISCORD_BOT_TOKEN` env var. | +| `reply_in_thread` | `bool` | `True` | Create a new thread for each @mention conversation in guild channels. | + +Provide exactly one of `agent`, `team`, or `workflow`. + +### Key Method + +| Method | Return Type | Description | +| --- | --- | --- | +| `get_router` | `APIRouter` | Returns the FastAPI router with Discord endpoints attached. | +| `get_lifespan` | `Optional[Any]` | Returns a FastAPI lifespan that manages the Gateway WebSocket and HTTP session cleanup. | + +## Transports + +### HTTP Webhook (Slash Commands) + +Always available. Handles the `/ask` slash command via Discord's Interactions API. + +**Flow:** +1. User runs `/ask message:Hello` +2. Discord sends a signed POST to `/discord/interactions` +3. Bot verifies the Ed25519 signature and responds with a deferred message +4. Background task processes the request and edits the response + +**Endpoint:** `POST /discord/interactions` + +- Handles PING verification and APPLICATION_COMMAND interactions +- Verifies Ed25519 signatures using `DISCORD_PUBLIC_KEY` +- Includes replay protection (rejects requests older than 5 minutes) + +### Gateway WebSocket (@Mentions and DMs) + +Auto-activates when `discord.py` is installed and a bot token is available. Falls back to HTTP-only otherwise. + +**Flow:** +1. User @mentions the bot or sends a DM +2. Bot receives the message via WebSocket +3. Bot creates a thread (if `reply_in_thread=True`) and processes the message +4. Response is sent to the thread/channel + +**Features:** +- Typing indicator shown while processing +- Auto-thread creation for guild @mentions +- Replies in-place for existing threads and DMs + +## Streaming Mode + +When `stream=True`, the bot progressively updates the response message as content is generated: + +1. Sends an initial message with the first content chunk +2. Edits the message every ~1 second as more content arrives +3. Final edit with the complete response when generation finishes +4. Overflow content (beyond 2000 chars) is sent as follow-up messages + +Streaming works for both HTTP webhook and Gateway transports. It is only supported for Agent and Team — Workflows and Remote entities fall back to non-streaming mode. + +## Session ID Scheme + +Session IDs use a `dc:` prefix to namespace Discord sessions: + +| Format | Context | +| --- | --- | +| `dc:dm:{channel_id}` | Direct messages | +| `dc:thread:{channel_id}` | Thread channels (including auto-created threads) | +| `dc:channel:{channel_id}:user:{user_id}` | Guild channels (scoped per user) | + +## Media Support + +### Inbound (User to Bot) + +The bot accepts attachments on the `/ask` slash command and on @mention messages. Files are classified by content type: + +| Content Type | Agno Media Type | +| --- | --- | +| `image/*` | `Image` | +| `video/*` | `Video` | +| `audio/*` | `Audio` | +| Everything else | `File` | + +Attachments larger than 25 MB are skipped. + +### Outbound (Bot to User) + +Tool-generated media (e.g., DALL-E images, ElevenLabs audio) is sent as Discord file attachments. + +## Testing the Integration + +1. Start the server: `python my_bot.py` +2. Start ngrok: `ngrok http 7777` +3. Set the Interactions Endpoint URL in the Developer Portal +4. Test slash commands: `/ask message:Hello` +5. Test @mentions: `@YourBot What is quantum computing?` +6. Test DMs: Send a direct message to the bot + +## Troubleshooting + +- **403 Invalid signature** — Verify `DISCORD_PUBLIC_KEY` is set correctly +- **Bot not responding to @mentions** — Ensure the Gateway is connected (check logs for "Discord Gateway connected as ...") +- **Slash command not appearing** — Register commands via the API (see setup guide) and wait a few minutes for propagation +- **Thread creation fails** — Bot needs `Manage Threads` permission in the channel +- **"This interaction failed"** — Check that your server is reachable via ngrok and the Interactions Endpoint URL is correct diff --git a/agent-os/interfaces/overview.mdx b/agent-os/interfaces/overview.mdx index b457881e..fc61405f 100644 --- a/agent-os/interfaces/overview.mdx +++ b/agent-os/interfaces/overview.mdx @@ -2,7 +2,7 @@ title: "Interfaces" sidebarTitle: "Overview" description: "Expose Agno agents through various communication protocols and platforms" -keywords: [interfaces, a2a, ag-ui, slack, whatsapp, protocols, integration] +keywords: [interfaces, a2a, ag-ui, slack, discord, whatsapp, telegram, protocols, integration] --- Interfaces enable exposing Agno agents, teams, and workflows through various communication protocols and platforms. Each interface provides a standardized way to connect Agno agents to external systems, messaging platforms, and frontend applications. @@ -24,6 +24,13 @@ Interfaces enable exposing Agno agents, teams, and workflows through various com > Deploy agents as Slack applications for team collaboration + + Run agents as Discord bots with slash commands, @mentions, and streaming + - Run agents as Discord bots for support, moderation, or custom commands. + Deploy agents as Discord bots with slash commands, @mentions, and streaming. Connect agents to WhatsApp Business for customer interactions. diff --git a/deploy/interfaces/discord/overview.mdx b/deploy/interfaces/discord/overview.mdx index 83e03154..53bb1673 100644 --- a/deploy/interfaces/discord/overview.mdx +++ b/deploy/interfaces/discord/overview.mdx @@ -1,115 +1,45 @@ --- -title: "Discord Bot" -description: "Create a Discord bot powered by Agno agents for community support, moderation, or custom commands." +title: "Overview" +description: "Deploy Agno agents as Discord bots." --- -Agno makes it easy to deploy your agents on Discord with just 2 extra lines of code. +The Discord interface lets you serve Agno agents, teams, and workflows as Discord bots. It supports two concurrent transports: HTTP webhook (slash commands) and Gateway WebSocket (@mentions and DMs). -This example creates a simple Agno agent for answering questions in your Discord server: +## Key Features + +- **Dual transport** - Slash commands via HTTP webhook and @mentions/DMs via Gateway WebSocket +- **Streaming responses** - Progressively updates messages as content is generated (Agent and Team) +- **Thread support** - Auto-creates threads for each conversation, keeping channels clean +- **Full media support** - Handles image, video, audio, and file attachments in both directions +- **Works with Agent, Team, and Workflow** - Any Agno entity can power a Discord bot + +## Quick Start ```python from agno.agent import Agent from agno.models.openai import OpenAIChat -from agno.integrations.discord import DiscordClient - -basic_agent = Agent( - name="Basic Agent", - model=OpenAIChat(id="gpt-5.2"), - add_history_to_context=True, - num_history_runs=3, - add_datetime_to_context=True, -) - -discord_agent = DiscordClient(basic_agent) -if __name__ == "__main__": - discord_agent.serve() -``` - - - - -The Discord bot automatically creates threads for conversations and maintains context within each thread. - - -## Setup and Configuration +from agno.os import AgentOS +from agno.os.interfaces.discord import Discord - +agent = Agent(name="Bot", model=OpenAIChat(id="gpt-4o-mini")) - -Ensure you have the following: -- Python 3.7+ -- A Discord account with server management permissions -- Install the Discord library: `pip install discord.py` - - - -1. Go to [Discord Developer Portal](https://discord.com/developers/applications) -2. Click "New Application" -3. Provide an application name (e.g., "My Agno Bot") -4. Accept the Developer Terms of Service -5. Click "Create" - - - -1. In your application settings, navigate to the "Bot" section -2. Click "Add Bot" -3. Confirm by clicking "Yes, do it!" -4. In the "Token" section, click "Copy" to copy your bot token -5. Save this token securely - - - -1. In the Bot settings, scroll down to "Privileged Gateway Intents" -2. Enable the following intents: - - **Server Members Intent** (for member-related events) - - **Message Content Intent** (required for reading message content) -3. Set "Bot Permissions" to ensure your bot has permission to: - - Send Messages - - Read Message History - - Create Public Threads - - Attach Files - - Embed Links - - - - -Find your bot token in the Discord Developer Portal under "Bot" > "Token". - -Create a `.env` file in your project root with the following content, replacing the placeholder with your actual bot token: -```bash -DISCORD_BOT_TOKEN="your_bot_token_here" +agent_os = AgentOS( + agents=[agent], + interfaces=[Discord(agent=agent, stream=True)], +) +app = agent_os.get_app() ``` - - - -1. In your application settings, go to "OAuth2" > "URL Generator" -2. Under "Scopes", select: - - `bot` -3. Under "Bot Permissions", select the permissions your bot needs: - - **Send Messages** - - **Create Public Threads** - - **Read Message History** - - **Attach Files** - - **Embed Links** -4. Copy the generated URL, navigate to it in your browser, and select the server where you want to add the bot - - - -1. Run your bot: `python discord_bot.py` -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 - - - +## Required Configuration - -Unlike Slack and WhatsApp bots, Discord bots don't require webhooks or ngrok. They connect directly to Discord's Gateway API. You can deploy them on any service that supports continuous Python runtime (Railway, Render, AWS EC2, etc.). See [deployment tutorials](/production/templates/overview) for production setup. - +| Variable | Description | +| -------- | ----------- | +| `DISCORD_BOT_TOKEN` | Bot token from the [Discord Developer Portal](https://discord.com/developers/applications) | +| `DISCORD_PUBLIC_KEY` | Application public key for webhook signature verification | +| `DISCORD_APPLICATION_ID` | Application ID for webhook API calls | -## Developer Resources +## Resources -- [Discord Integration](/integrations/discord/overview) -- [Deployment Templates](/production/templates/overview) -- [Discord](https://agno.link/discord) +- [Setup Guide](/production/interfaces/discord) - Step-by-step bot creation, permissions, and webhook setup +- [Technical Reference](/agent-os/interfaces/discord/introduction) - Parameters, endpoints, transports, and session handling +- [Cookbook Examples](https://github.com/agno-agi/agno/tree/main/cookbook/05_agent_os/interfaces/discord) - Ready-to-run examples diff --git a/docs.json b/docs.json index 63a6aa13..1b79e269 100644 --- a/docs.json +++ b/docs.json @@ -2873,7 +2873,8 @@ "agent-os/interfaces/whatsapp/introduction", "agent-os/interfaces/a2a/introduction", "agent-os/interfaces/ag-ui/introduction", - "agent-os/interfaces/slack/introduction" + "agent-os/interfaces/slack/introduction", + "agent-os/interfaces/discord/introduction" ] }, { diff --git a/production/interfaces/discord.mdx b/production/interfaces/discord.mdx index 83e03154..973c9682 100644 --- a/production/interfaces/discord.mdx +++ b/production/interfaces/discord.mdx @@ -1,34 +1,43 @@ --- title: "Discord Bot" -description: "Create a Discord bot powered by Agno agents for community support, moderation, or custom commands." +description: "Build a Discord bot that responds to messages, handles media, and supports streaming responses using agents." --- -Agno makes it easy to deploy your agents on Discord with just 2 extra lines of code. +Agno and AgentOS make it easy to deploy your agents on Discord with just 2 extra lines of code. -This example creates a simple Agno agent for answering questions in your Discord server: +This example creates a simple agent for answering questions: ```python from agno.agent import Agent from agno.models.openai import OpenAIChat -from agno.integrations.discord import DiscordClient +from agno.os import AgentOS +from agno.os.interfaces.discord import Discord -basic_agent = Agent( - name="Basic Agent", - model=OpenAIChat(id="gpt-5.2"), +discord_agent = Agent( + name="Discord Bot", + model=OpenAIChat(id="gpt-4o-mini"), add_history_to_context=True, num_history_runs=3, add_datetime_to_context=True, + markdown=True, ) -discord_agent = DiscordClient(basic_agent) +agent_os = AgentOS( + agents=[discord_agent], + interfaces=[Discord(agent=discord_agent, stream=True)], +) +app = agent_os.get_app() + if __name__ == "__main__": - discord_agent.serve() + agent_os.serve(app="discord_bot:app", port=7777, reload=True) ``` - + +Install Discord dependencies: `pip install 'agno[discord]'` + -The Discord bot automatically creates threads for conversations and maintains context within each thread. +The bot automatically creates threads for each @mention conversation and uses per-thread session tracking to maintain context. In DMs, each channel gets its own session. ## Setup and Configuration @@ -37,79 +46,108 @@ The Discord bot automatically creates threads for conversations and maintains co Ensure you have the following: +- A Discord account +- ngrok (for development) - Python 3.7+ -- A Discord account with server management permissions -- Install the Discord library: `pip install discord.py` -1. Go to [Discord Developer Portal](https://discord.com/developers/applications) +1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) 2. Click "New Application" 3. Provide an application name (e.g., "My Agno Bot") -4. Accept the Developer Terms of Service -5. Click "Create" +4. Accept the Developer Terms of Service and click "Create" +5. Note the **Application ID** and **Public Key** from the "General Information" page 1. In your application settings, navigate to the "Bot" section -2. Click "Add Bot" -3. Confirm by clicking "Yes, do it!" -4. In the "Token" section, click "Copy" to copy your bot token -5. Save this token securely +2. Click "Reset Token" to generate a new bot token +3. Copy and save this token securely — you won't be able to see it again - -1. In the Bot settings, scroll down to "Privileged Gateway Intents" -2. Enable the following intents: - - **Server Members Intent** (for member-related events) - - **Message Content Intent** (required for reading message content) -3. Set "Bot Permissions" to ensure your bot has permission to: - - Send Messages - - Read Message History - - Create Public Threads - - Attach Files - - Embed Links + +In the Bot settings, ensure your bot has these permissions: +- Send Messages +- Read Message History +- Create Public Threads +- Send Messages in Threads +- Manage Threads +- Attach Files +- Embed Links - - -Find your bot token in the Discord Developer Portal under "Bot" > "Token". + +1. In your application settings, go to "OAuth2" > "URL Generator" +2. Under "Scopes", select `bot` and `applications.commands` +3. Under "Bot Permissions", select the permissions listed above +4. Copy the generated URL, open it in your browser, and select your server + -Create a `.env` file in your project root with the following content, replacing the placeholder with your actual bot token: + +Create a `.env` file in your project root: ```bash -DISCORD_BOT_TOKEN="your_bot_token_here" +DISCORD_BOT_TOKEN="your-bot-token" +DISCORD_PUBLIC_KEY="your-public-key" +DISCORD_APPLICATION_ID="your-application-id" ``` + + +Register the `/ask` slash command with Discord: +```bash +curl -X PUT \ + -H "Authorization: Bot $DISCORD_BOT_TOKEN" \ + -H "Content-Type: application/json" \ + "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \ + -d '[{ + "name": "ask", + "description": "Send a message to the bot", + "type": 1, + "options": [ + {"name": "message", "description": "Your message", "type": 3, "required": true}, + {"name": "file", "description": "Optional file attachment", "type": 11, "required": false} + ] + }]' +``` - -1. In your application settings, go to "OAuth2" > "URL Generator" -2. Under "Scopes", select: - - `bot` -3. Under "Bot Permissions", select the permissions your bot needs: - - **Send Messages** - - **Create Public Threads** - - **Read Message History** - - **Attach Files** - - **Embed Links** -4. Copy the generated URL, navigate to it in your browser, and select the server where you want to add the bot + +1. Run ngrok to expose your local server: + ```bash + ngrok http 7777 + ``` +2. Copy the `https://` URL provided by ngrok +3. Set the interactions endpoint in the Discord Developer Portal: + - Go to "General Information" + - Set "Interactions Endpoint URL" to `https:///discord/interactions` + - Discord will send a verification PING — your server must be running - -1. Run your bot: `python discord_bot.py` -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 + +For production deployments: +1. Replace the ngrok URL with your production domain +2. Update the Interactions Endpoint URL in the Developer Portal to `https:///discord/interactions` -Unlike Slack and WhatsApp bots, Discord bots don't require webhooks or ngrok. They connect directly to Discord's Gateway API. You can deploy them on any service that supports continuous Python runtime (Railway, Render, AWS EC2, etc.). See [deployment tutorials](/production/templates/overview) for production setup. +ngrok is used only for local development and testing. For production deployments, see the [deployment tutorials](/production/templates/overview). +## How It Works + +The Discord interface uses two concurrent transports: + +1. **HTTP Webhook** - Handles `/ask` slash commands via Discord's Interactions API. The bot responds with a deferred message, processes the request in the background, and edits the response. + +2. **Gateway WebSocket** - Listens for @mentions and DMs via a persistent WebSocket connection. Auto-activates when `discord.py` is installed and `DISCORD_BOT_TOKEN` is set. + +Both transports share the same processing core, so your agent logic is written once. + ## Developer Resources -- [Discord Integration](/integrations/discord/overview) +- [Discord Interface](/agent-os/interfaces/discord/introduction) - [Deployment Templates](/production/templates/overview) +- [Agent reference](/reference/agents/agent) - [Discord](https://agno.link/discord) diff --git a/production/interfaces/overview.mdx b/production/interfaces/overview.mdx index e9a1dd53..26df3d9a 100644 --- a/production/interfaces/overview.mdx +++ b/production/interfaces/overview.mdx @@ -15,7 +15,7 @@ Expose your agents where your users are. Interfaces connect AgentOS to a platfor Deploy agents as Slack apps that respond to messages and commands. - Run agents as Discord bots for support, moderation, or custom commands. + Deploy agents as Discord bots with slash commands, @mentions, and streaming.