Slack Integration

Polos has a built-in Slack integration that posts rich notifications to Slack when agents suspend for approval or user input. You can also trigger agents directly from Slack by @mentioning your bot.

Prerequisites

A Polos project with a running orchestrator
Admin access to a Slack workspace

Step 1: Create a Slack App

Create the app

Go to api.slack.com/apps and click Create New App > From scratch. Name it (e.g., “polos”) and select your workspace.

Add bot token scopes

Go to OAuth & Permissions > Bot Token Scopes and add:

chat:write - Send messages
app_mentions:read - Receive @mentions
channels:history - Read channel messages
groups:history - Read messages from private channels

Install to workspace

Click Install to Workspace and authorize. Copy the Bot User OAuth Token (xoxb-...) - this is your SLACK_BOT_TOKEN.

Invite the bot to your channel

In your target Slack channel, type /invite @polos (or whatever you named the bot).

One Slack app serves all your agents. Different agents route to different Slack channels via configuration, not separate apps. You only need a second app if your agents span multiple Slack workspaces.

Step 2: Configure environment variables

The Slack credentials are split between the orchestrator and the worker. Orchestrator — add to ~/.polos/.env:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret

Worker — add to your project’s .env:

POLOS_PROJECT_ID=your-project-id
POLOS_API_URL=http://localhost:8080
POLOS_API_KEY=your-api-key
SLACK_BOT_TOKEN=xoxb-your-bot-token

Step 3: Add SlackChannel to your worker

Pass a SlackChannel to your Polos instance:

import 'dotenv/config';
import { Polos, SlackChannel, defineAgent } from '@polos/sdk';

const slack = new SlackChannel({
  botToken: process.env.SLACK_BOT_TOKEN!
});

const agent = defineAgent({
  id: 'my-agent',
  model: 'anthropic:claude-sonnet-4-20250514',
  systemPrompt: 'You are a helpful assistant.',
});

const polos = new Polos({
  deploymentId: 'slack-example',
  channels: [slack],
});

await polos.serve();

import os
from dotenv import load_dotenv
from polos import Polos, Agent
from polos.channels.slack import SlackChannel, SlackChannelConfig

load_dotenv()

slack = SlackChannel(SlackChannelConfig(
    bot_token=os.environ["SLACK_BOT_TOKEN"]
))

agent = Agent(
    id="my-agent",
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    system_prompt="You are a helpful assistant.",
)

polos = Polos(deployment_id="slack-example", channels=[slack])
await polos.serve()

When any agent suspends (via tool approval, or ctx.step.suspend()), an approval message is posted to the slack channel from where the request originated or the slack channel configured for the tool approval.

Trigger agents from Slack

You can @mention your bot in Slack to trigger an agent. The agent’s output streams back to the originating Slack thread.

Set up event subscriptions

Enable events

In your Slack app settings, go to Event Subscriptions and enable events.

Set the request URL

Set the Request URL to:

https://<your-orchestrator-host>/slack/v1/events

Subscribe to bot events

Add app_mention.

Register your Slack app with the orchestrator

Link your Slack app to your Polos project so the orchestrator knows how to route incoming messages:

curl -X POST https://<your-orchestrator-host>/api/v1/slack/apps \
  -H "Content-Type: application/json" \
  -H "X-Project-ID: <your-project-id>" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{"api_app_id": "<your-slack-app-id>"}'

You can find your Slack App ID on your app’s Basic Information page.

Interact with the bot

Once configured, @mention the bot in any channel it’s been invited to:

@polos @assistant_agent Send an email to alice@example.com about the Q1 report

@assistant_agent is the name of the agent in Polos that you’re triggering from Slack. The agent streams output back to the same Slack thread. If the agent suspends (e.g., for tool approval), you’ll see the Slack message in the thread to approve/reject the request.

Environment variables

Variable	Where	Required	Description
`SLACK_BOT_TOKEN`	Orchestrator (`~/.polos/.env`) and Worker (`.env`)	Yes	Bot User OAuth Token (`xoxb-...`) from your Slack app
`SLACK_SIGNING_SECRET`	Orchestrator (`~/.polos/.env`)	Yes	Signing Secret from your Slack app’s Basic Information page

Per-tool channel routing

You might need admin approvals for specific tools irrespective of who triggered the agent. In such cases, you can route specific tool approvals to different Slack channels. For example, send authorize_payment to #ops-approvals:

import { SlackChannel, defineTool } from '@polos/sdk';
import { z } from 'zod';

const slack = (channel: string) =>
  new SlackChannel({
    botToken: process.env.SLACK_BOT_TOKEN!,
    defaultChannel: channel,
  });

const authorizePaymentTool = defineTool(
  {
    id: 'authorize_payment',
    description: 'Authorize payment to a recipient.',
    inputSchema: z.object({
      subject: z.string(),
      amount: z.number(),
      details: z.string(),
    }),
    approval: 'always',
    channels: [slack('#ops-approvals')], // Override: approvals go here
  },
  async (input) => {
    return { subject: input.subject, amount: input.amount };
  },
);

from polos import Tool
from polos.channels.slack import SlackChannel, SlackChannelConfig
from pydantic import BaseModel

def slack(channel: str) -> SlackChannel:
    return SlackChannel(SlackChannelConfig(
        bot_token=os.environ["SLACK_BOT_TOKEN"],
        default_channel=channel,
    ))

class AuthorizePaymentInput(BaseModel):
    subject: str
    amount: float
    details: str

authorize_payment_tool = Tool(
    id="authorize_payment",
    description="Authorize payment to a recipient.",
    input_schema=AuthorizePaymentInput,
    approval="always",
    channels=[slack("#ops-approvals")],  # Override: approvals go here
)

The channel set on a tool takes precedence over the worker-level channel. If a tool has no channels configured, it inherits from the worker.

Introduction

Getting Started

Fundamentals

Agents

Workflows

Observability

Guides and Examples

Community

Prerequisites

Step 1: Create a Slack App

Step 2: Configure environment variables

Step 3: Add SlackChannel to your worker

Trigger agents from Slack

Set up event subscriptions

Register your Slack app with the orchestrator

Interact with the bot

Environment variables

Per-tool channel routing

​Prerequisites

​Step 1: Create a Slack App

​Step 2: Configure environment variables

​Step 3: Add SlackChannel to your worker

​Trigger agents from Slack

​Set up event subscriptions

​Register your Slack app with the orchestrator

​Interact with the bot

​Environment variables

​Per-tool channel routing

Prerequisites

Step 1: Create a Slack App

Step 2: Configure environment variables

Step 3: Add SlackChannel to your worker

Trigger agents from Slack

Set up event subscriptions

Register your Slack app with the orchestrator

Interact with the bot

Environment variables

Per-tool channel routing