|
1 | 1 | # Slack Cookbook |
2 | 2 |
|
3 | | -Examples for `interfaces/slack` in AgentOS. |
4 | | - |
5 | | -## Files |
6 | | -- `agent_with_user_memory.py` — Agent With User Memory. |
7 | | -- `basic.py` — Basic. |
8 | | -- `basic_workflow.py` — Basic Workflow. |
9 | | -- `channel_summarizer.py` — Channel Summarizer. |
10 | | -- `file_analyst.py` — File Analyst. |
11 | | -- `multiple_instances.py` — Multiple Instances. |
12 | | -- `reasoning_agent.py` — Reasoning Agent. |
13 | | -- `research_assistant.py` — Research Assistant. |
14 | | -- `support_team.py` — Support Team. |
15 | | - |
16 | | -## Prerequisites |
17 | | -- Load environment variables with `direnv allow` (requires `.envrc`). |
18 | | -- Run examples with `.venvs/demo/bin/python <path-to-file>.py`. |
19 | | -- Some examples require local services (for example Postgres, Redis, Slack, or MCP servers). |
| 3 | +Examples for connecting Agno agents, teams, and workflows to Slack using the |
| 4 | +`Slack` interface in AgentOS. Supports both standard request/response and |
| 5 | +real-time streaming via Slack's `chat_stream` API. |
| 6 | + |
| 7 | +**Requirements:** `slack_sdk >= 3.40.0` (streaming with plan-mode task cards). |
| 8 | +Install or upgrade with `pip install "slack_sdk>=3.40.0"`. |
| 9 | + |
| 10 | +## Slack App Setup |
| 11 | + |
| 12 | +Follow these steps to create and configure a Slack app for use with Agno. |
| 13 | + |
| 14 | +### 1. Create the App |
| 15 | + |
| 16 | +1. Go to https://api.slack.com/apps and click **Create New App**. |
| 17 | +2. Choose **From scratch**, give it a name, and select your workspace. |
| 18 | +3. On the **Basic Information** page, copy the **Signing Secret** — you'll need it later. |
| 19 | + |
| 20 | +### 2. Enable Agents & AI Apps (required for streaming) |
| 21 | + |
| 22 | +1. In the sidebar, click **Agents & AI Apps**. |
| 23 | +2. Toggle **Agent or Assistant** to **On**. |
| 24 | +3. Under **Suggested Prompts**, select **Dynamic** (lets the server set prompts via API). |
| 25 | +4. Click **Save**. |
| 26 | + |
| 27 | +> Enabling this automatically adds the `assistant:write` scope. |
| 28 | +
|
| 29 | +### 3. Add OAuth Scopes |
| 30 | + |
| 31 | +1. In the sidebar, click **OAuth & Permissions**. |
| 32 | +2. Scroll to **Scopes > Bot Token Scopes** and add: |
| 33 | + |
| 34 | +| Scope | Purpose | |
| 35 | +|-------|---------| |
| 36 | +| `app_mentions:read` | Receive @mention events | |
| 37 | +| `assistant:write` | Streaming (startStream/appendStream/stopStream) | |
| 38 | +| `chat:write` | Send messages and stream responses | |
| 39 | +| `im:history` | Read DM history for thread context | |
| 40 | +| `channels:history` | Read public channel history | |
| 41 | +| `groups:history` | Read private channel history | |
| 42 | +| `files:read` | Download files users send to the bot | |
| 43 | +| `files:write` | Upload response files (images, docs) | |
| 44 | +| `users:read` | Look up user info (for channel_summarizer, etc.) | |
| 45 | +| `search:read` | Search workspace messages (research_assistant, support_team, etc.) | |
| 46 | + |
| 47 | +Not all scopes are needed for every example — `app_mentions:read`, `assistant:write`, |
| 48 | +`chat:write`, and `im:history` are the minimum for streaming. Each cookbook's docstring |
| 49 | +lists the exact scopes it requires. |
| 50 | + |
| 51 | +3. Scroll up and click **Install to Workspace** (or **Reinstall** if updating scopes). |
| 52 | +4. Copy the **Bot User OAuth Token** (`xoxb-...`). |
| 53 | + |
| 54 | +### 4. Subscribe to Events |
| 55 | + |
| 56 | +1. In the sidebar, click **Event Subscriptions**. |
| 57 | +2. Toggle **Enable Events** to **On**. |
| 58 | +3. Set **Request URL** to your tunnel URL + `/slack/events`: |
| 59 | + ``` |
| 60 | + https://<your-tunnel>/slack/events |
| 61 | + ``` |
| 62 | + Slack will send a challenge request — the server must be running to verify. |
| 63 | +4. Under **Subscribe to bot events**, add: |
| 64 | + |
| 65 | +| Event | Purpose | |
| 66 | +|-------|---------| |
| 67 | +| `app_mention` | Respond to @mentions in channels | |
| 68 | +| `message.im` | Respond to direct messages | |
| 69 | +| `message.channels` | Respond to messages in public channels | |
| 70 | +| `message.groups` | Respond to messages in private channels | |
| 71 | +| `assistant_thread_started` | Set suggested prompts when a thread opens | |
| 72 | +| `assistant_thread_context_changed` | Update context when thread is moved | |
| 73 | + |
| 74 | +5. Click **Save Changes**. |
| 75 | +6. Go to **Install App** and click **Reinstall to Workspace** to apply the new events. |
| 76 | + |
| 77 | +### 5. Set Environment Variables |
| 78 | + |
| 79 | +```bash |
| 80 | +export SLACK_TOKEN="xoxb-..." # Bot User OAuth Token from step 3 |
| 81 | +export SLACK_SIGNING_SECRET="..." # Signing Secret from step 1 |
| 82 | +export OPENAI_API_KEY="sk-..." # Or whichever model provider you use |
| 83 | +``` |
| 84 | + |
| 85 | +### 6. Start a Tunnel |
| 86 | + |
| 87 | +Slack needs a public URL to deliver events. Use [ngrok](https://ngrok.com/) |
| 88 | +or [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/): |
| 89 | + |
| 90 | +```bash |
| 91 | +ngrok http 7777 |
| 92 | +# or: cloudflared tunnel --url http://localhost:7777 |
| 93 | +``` |
| 94 | + |
| 95 | +Copy the public HTTPS URL and paste it into the Event Subscriptions Request URL |
| 96 | +(step 4.3). The free ngrok tier gives you a random subdomain that changes on |
| 97 | +restart — update the Request URL each time. |
| 98 | + |
| 99 | +### 7. Run an Example |
| 100 | + |
| 101 | +```bash |
| 102 | +.venvs/demo/bin/python cookbook/05_agent_os/interfaces/slack/basic.py |
| 103 | +``` |
| 104 | + |
| 105 | +DM the bot or @mention it in a channel to test. |
| 106 | + |
| 107 | +## Examples |
| 108 | + |
| 109 | +### Getting Started |
| 110 | + |
| 111 | +- `basic.py` — Minimal agent that responds to @mentions with session history. |
| 112 | +- `basic_workflow.py` — Two-step research-then-write workflow. |
| 113 | + |
| 114 | +### Streaming |
| 115 | + |
| 116 | +Streaming is enabled by default. Tokens arrive in real-time and tool calls |
| 117 | +render as progress cards in Slack's plan display. |
| 118 | + |
| 119 | +- `streaming_deep_research.py` — Deep research agent with 7 toolkits. |
| 120 | +- `reasoning_agent.py` — Agent with step-by-step reasoning display. |
| 121 | + |
| 122 | +### Teams and Workflows |
| 123 | + |
| 124 | +- `support_team.py` — Support team routing to Technical Support or Documentation Specialist. |
| 125 | +- `multimodal_team.py` — Team with GPT-4o vision input and DALL-E image output. |
| 126 | +- `multimodal_workflow.py` — Parallel visual analysis + web research, then creative synthesis. |
| 127 | + |
| 128 | +### Tools and Features |
| 129 | + |
| 130 | +- `agent_with_user_memory.py` — Agent with MemoryManager that learns about users. |
| 131 | +- `channel_summarizer.py` — Agent that reads channel history and summarizes threads. |
| 132 | +- `file_analyst.py` — Agent that downloads, analyzes, and uploads files. |
| 133 | +- `research_assistant.py` — Agent combining Slack search with web search. |
| 134 | +- `multi_bot.py` — Multiple bots with different models in one server. |
| 135 | +- `multiple_instances.py` — Two bots on one server with separate credentials. |
| 136 | + |
| 137 | +## Troubleshooting |
| 138 | + |
| 139 | +| Symptom | Cause | Fix | |
| 140 | +|---------|-------|-----| |
| 141 | +| Bot doesn't respond | Event URL not set or server not running | Check Event Subscriptions shows "Verified" | |
| 142 | +| `internal_error` on `chat.appendStream` | "Agents & AI Apps" not enabled, or missing `assistant:write` scope, or app not reinstalled after config changes | 1. Enable "Agents & AI Apps" (step 2). 2. Add `assistant:write` scope (step 3). 3. Reinstall the app to the workspace. | |
| 143 | +| Blank streaming bubble | Wrong `recipient_user_id` | Ensure you're using the human user's ID, not the bot's | |
| 144 | +| No plan-mode task cards | `slack_sdk` older than 3.40.0 | Run `pip install "slack_sdk>=3.40.0"` | |
| 145 | +| No suggested prompts | `assistant_thread_started` event missing | Add it in Event Subscriptions (step 4) | |
| 146 | +| Bot only responds to DMs, not channels | Missing `message.channels` event | Add channel events in Event Subscriptions | |
| 147 | +| `SLACK_SIGNING_SECRET is not set` | Missing env var | Export `SLACK_SIGNING_SECRET` before running | |
| 148 | +| 403 on event webhook | Invalid signing secret | Check the secret matches Basic Information page | |
| 149 | +| URL verification fails | Server not running or wrong signing secret | Start the server (step 7) before setting the Request URL | |
0 commit comments