> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Build a Slack deep research agent
description: Trigger a fully automated multi-step research pipeline from a Slack message and post the findings back to the channel, no human approval required.
tags: ["Slack", "Agents", "Webhooks", "Long-running"]
date: 2026-06-12
last_verified: 2026-06-12
audience: both
---

Mention your bot in Slack with a topic and it runs a full research pipeline and replies with a report — no approval, no polling.

<Mermaid title="How the bot works" code={`flowchart TD
    A["Slack mention: ResearchBot quantum computing breakthroughs 2025"]
    A --> B["AGNT5 starts a workflow run"]
    B --> C["ScopingAgent plans 3 to 6 subtopics"]
    C --> D["ResearchAgent fetches Wikipedia and web pages"]
    D --> E["WritingAgent writes a Slack summary"]
    E --> F["Bot posts the report as a threaded reply"]`} />

---

## What you will learn

- How to trigger a durable multi-step workflow from a Slack event.
- How to use three specialised agents in a sequential pipeline.
- How to post results back to a Slack thread from a workflow step.
- How checkpointing lets the pipeline resume after a worker restart.

## What you build

- A Slack App connected to AGNT5 via the Studio integration.
- A three-agent research pipeline (scoping, research, writing) triggered by `app_mention` and `message` events.
- A step that posts the finished report back to the originating channel thread.

---

## Prerequisites

- An AGNT5 account. Sign up at [app.agnt5.com](https://app.agnt5.com).
- Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
- An [OpenAI API key](https://platform.openai.com/api-keys) (the template uses `gpt-4o-mini`).
- A Slack workspace where you can create and install apps.

---

## Step 1: Install the CLI

Follow the [CLI install guide](/docs/install-cli.md) to install `agnt5` and authenticate. Come back here when `agnt5 auth status` confirms you are signed in.

---

## Step 2: Create the project

```bash
agnt5 create --template python/slack_deep_research my-research-bot
cd my-research-bot
uv sync
```

---

## Step 3: Configure environment variables

```bash
cp .env.example .env
```

Open `.env` and set your OpenAI key:

```bash
OPENAI_API_KEY="sk-..."
```

---

## Step 4: Set up the Slack App and Studio integration

Follow the [Slack integration guide](/docs/integrations/event-sources/slack.md) to create your Slack app and connect it to AGNT5 in Studio. When configuring the app, make sure to:

- Add bot scopes: `app_mentions:read`, `channels:history`, and `chat:write` (needed to post the report back).
- Subscribe to bot events: `app_mention` and `message.channels`.

Come back here once Studio shows the integration as active.

---

## Step 5: Deploy

```bash
agnt5 deploy
```

The CLI builds the container image, pushes it to the registry, and creates the deployment. Once it completes, your workflow is live and listening for Slack events.

---

## Step 6: Test the bot in Slack

Invite the bot to a channel, then mention it with a research topic:

```
/invite @Research Bot

@Research Bot quantum computing breakthroughs 2025
```

The research pipeline starts immediately. When it finishes (typically 30 to 90 seconds) the report arrives as a threaded reply.

Open Studio and go to **Runs** to inspect the execution. You will see the full Slack envelope, each step (`plan_research`, `conduct_research`, `write_report`) with its input and output, and the Slack post result (`posted: true`).

---

## How it works

### End-to-end flow

<Mermaid title="End-to-end flow" code={`flowchart TD
    A["Slack event: app_mention or message"]
    A --> B["AGNT5 verifies signature and starts a run"]
    B --> C["slack_deep_research workflow starts"]
    C --> D["Parse envelope: text, channel, user, thread_ts"]
    D --> E{should process}
    E -- "bot or empty" --> F["skip: workflow exits"]
    E -- "valid user message" --> G["Extract topic, strip mention prefix"]
    G --> H["plan_research: ScopingAgent"]
    H --> I["conduct_research: ResearchAgent"]
    I --> J["write_report: WritingAgent"]
    J --> K["chat.postMessage: threaded reply"]`} />

Each `ctx.step` is checkpointed in the durable journal. A worker restart at any point replays from the last completed step — the research already gathered is not re-run.

### The three-stage pipeline

| Stage | Agent | What it does |
|---|---|---|
| Plan | `ScopingAgent` | Breaks the topic into 3 to 6 subtopics with a research strategy |
| Research | `ResearchAgent` | Searches Wikipedia and fetches web pages for each subtopic |
| Write | `WritingAgent` | Synthesises findings into a Slack-formatted summary under 2000 characters |

### Bot loop guard

The workflow checks the envelope before starting the pipeline. Messages from bots or with unsupported subtypes are skipped to prevent the bot from replying to itself:

```python
def _should_process(message: dict) -> tuple[bool, str]:
    if message.get("bot_id"):
        return False, "bot message"
    if message.get("subtype"):
        return False, f"unsupported subtype: {message['subtype']}"
    if not (message.get("message") or "").strip():
        return False, "empty message"
    return True, ""
```

### Posting back to Slack

The report is posted with `chat.postMessage`. Passing `thread_ts` threads the reply under the original message so the conversation stays organised:

```python
payload = {"channel": channel, "text": report}
if thread_ts:
    payload["thread_ts"] = thread_ts
```

---

## Extend it

- **Add more sources**: give `ResearchAgent` a web search tool alongside Wikipedia for broader coverage.
- **Multi-turn conversation**: store `run_id` keyed by `thread_ts` and use `ctx.state` to carry context across follow-up mentions in the same thread.
- **Longer reports**: increase `WritingAgent`'s `max_tokens` and split the output across multiple Slack messages if it exceeds 4000 characters.
- **Different trigger**: swap `slack.app_mention` for `slack.reaction_added` to kick off research when a user reacts to a message with a specific emoji.

---

## Production checklist

- **Idempotency**: Slack retries failed deliveries. Use `event.client_msg_id` from the envelope body as an idempotency key to avoid duplicate research jobs.
- **Bot loop guard**: the `bot_id` check in `_should_process` prevents the bot from replying to its own posts. Verify it is in place before going live.
- **Rate limits**: the research agent retries Wikipedia 429s with exponential back-off. Monitor OpenAI rate limits for high-volume deployments.
- **Secrets**: never commit `.env`. Inject secrets in your deployment environment.

---

## Next steps

- [Slack integration reference](/docs/integrations/event-sources/slack.md): envelope structure, all event types, signature verification, and delivery semantics.
- [Build a deep research agent](/cookbooks/deep-research-agent.md): the same pipeline without the Slack trigger.
- [Build a durable research agent with approval and recovery](/cookbooks/durable-research-agent-approval-recovery.md): add a human approval gate before the report is posted.
- [Debug AI workflows with traces, not scattered logs](/cookbooks/workflow-native-observability.md): inspect step-level inputs, outputs, and model calls.