Slack#
How to let your team ask the OSPREY agent questions from Slack, and get answers, plots, and files back in the same thread.
Before you start
A project whose build profile has a
dispatch:block — see Event Dispatch.Docker or Podman, for the container path.
A Slack workspace in which you may create and install an app (some workspaces need an administrator to approve it).
Overview#
Someone mentions the app in a channel, or messages it directly; the bridge hands the question to the event dispatch pipeline and posts the answer back in the thread.
The bridge uses Slack’s Socket Mode: it opens a connection to Slack and Slack pushes events down it. Every connection is outbound, so the bridge opens no port and needs no public address.
Like every bridge, it remembers each question and conversation. It also writes each event to disk before telling Slack it has it, so a question already received survives a crash or restart.
Create the Slack App#
1. Create the app from a manifest. At api.slack.com/apps, choose Create New App → From a manifest, pick your workspace, and paste (newer Slack UIs call the option Paste a manifest):
display_information:
name: OSPREY agent
features:
app_home:
home_tab_enabled: false
messages_tab_enabled: true
messages_tab_read_only_enabled: false # lets people message the app
bot_user:
display_name: osprey
always_online: true
oauth_config:
scopes:
bot:
- app_mentions:read
- chat:write
- channels:history
- groups:history
- im:history
- mpim:history
- channels:read
- groups:read
- im:read
- mpim:read
- users:read
- files:read
- files:write
settings:
event_subscriptions:
bot_events:
- app_mention
- message.im
- message.mpim
interactivity:
is_enabled: false
org_deploy_enabled: false
socket_mode_enabled: true
token_rotation_enabled: false
The display name is what your team sees replying, so make it obvious. Leave token rotation off: with it on, the tokens expire every 12 hours.
What each scope is for — an administrator approving the app will ask:
Scope |
Why the bridge needs it |
|---|---|
|
Receive messages that mention the app in a channel. |
|
Post the acknowledgement, the answer and status notices. |
|
Read the message a thread started from, so a reply in a thread arrives with its context (public and private channels). |
|
Receive direct and group direct messages, and read their threads. |
|
List who is in a conversation, so the agent knows who it is talking to. |
|
Look up those people’s names. |
|
Download files someone attaches to a question. |
|
Upload the plots and files a run produces into the thread. |
2. Create the app-level token. Under Basic Information → App-Level
Tokens, generate a token with the scope connections:write. It starts with
xapp- and is what the bridge opens its Socket Mode connection with. This
token cannot be declared in the manifest.
3. Install the app. Under Install App, install it to the workspace (or
request approval). Copy the Bot User OAuth Token, which starts with
xoxb-.
4. Invite the app to channels. It only sees channels it is a member of:
/invite @OSPREY agent in each one. Direct messages need no setup.
Warning
One bridge per app, one app per deployment. Slack spreads an app’s events across every open Socket Mode connection. A second bridge running with the same app token — a staging stack, a forgotten container, another facility reusing the app — does not get its own copy of each message. It silently splits them: each bridge answers only what it received, and nothing logs an error. Create a separate app for every deployment.
Enable It in a Profile#
Add a slack_bridge: block next to your dispatch: block. The trigger
decides what the agent may do with a Slack question; mentions decides
whether it may @mention people:
slack_bridge:
trigger: slack-question # default; must exist in your triggers file
mentions: true # default; false posts @mentions as plain text
dispatch:
triggers: my_triggers.yml # the file that trigger must be declared in
worker_count: 1
env:
required:
- SLACK_BOT_TOKEN
- SLACK_APP_TOKEN
Note
The bridge and the dispatch pair must sit on the same network. When the
workers go on the host’s network (Network attachment: bridge or host), add
services.slack_bridge.network: host to your profile’s config: block.
osprey build refuses a split pair and names the key to change.
The two tokens are secrets, not profile settings. Listing them under
env.required documents them in .env.example; put the values in the
profile’s .env, from which the build derives the project’s .env
(mode 0600).
Declaring the bridge without a dispatch: block, or naming a trigger your
triggers file does not declare, fails the build with a message naming the
problem. A minimal trigger; list the tools the agent may use, or it can only
answer from what it knows:
triggers:
- name: slack-question
source: webhook
action:
prompt: >-
A colleague asked you this question in Slack. Answer it in the
thread; plots and files you save are posted there too.
allowed_tools:
- mcp__python__execute
- mcp__osprey_workspace__create_static_plot
Runtime settings#
Variable |
Meaning |
|---|---|
|
The bot token ( |
|
The app-level token ( |
Neither is generated for you. A missing token stops the bridge at startup with the variable named; a refused one stops it with Slack’s reason.
Settings that are filled in for you, or safe to leave alone
Variable |
Meaning |
|---|---|
|
The trigger to fire. Comes from the profile block. |
|
Whether @mentions are on. Comes from the profile block. |
|
The shared secrets for the dispatcher and the worker, generated for you when unset — see Authentication. |
|
Where the dispatcher and worker are. Filled in when they run in the same stack; required when they run elsewhere. |
|
How long the worker may spend on one run, from your project configuration. |
|
How long the bridge waits for an answer. Defaults to 30 seconds more than the worker’s limit, and may never be less. |
|
Seconds between checks on an answer (default 2) and between retries of questions not yet handed off (default 60). |
|
When a failed hand-off is retried (20 minutes), abandoned (48 hours), and dropped whatever its state (7 days). |
|
Set to |
|
Longest earlier answer, in characters, sent back in full with a
follow-up (default 3000; |
|
Where to file an issue when a question is given up on. Leave unset to file nothing. |
|
Release label shown with each acknowledgement. Defaults to the installed OSPREY version. |
|
Where the bridge keeps the questions it has answered, under |
|
Timezone, from your project configuration. |
Behind a Web Proxy#
If the host reaches the internet only through a proxy, set BRIDGE_TRUST_ENV=1
and the usual HTTPS_PROXY variables. The proxy must allow CONNECT to:
slack.com— the Web API;wss.slack.com(and itswss-*.slack.comvariants) — the Socket Mode connection;files.slack.comandfiles-edge.slack.com— file downloads and uploads.
Calls to the dispatcher and worker never use the proxy.
Bring It Up#
1. Fill in the environment file. In the profile’s .env:
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
2. Build and start. The bridge is registered in deployed_services, so
it starts with everything else:
osprey up # add --dev to bake in a local osprey checkout
Then mention the app in a channel it was invited to, or message it directly. It acknowledges with “On it — working on this now.” and replies in the thread. If nothing happens, check the service’s logs.
Important
The bridge keeps what it remembers — which questions it has answered, the
events it has received but not yet handled, and the recent conversation — in
a named volume mounted at /data. Do not remove that volume.
Who Is in the Channel, and @Mentions#
Each question reaches the agent with who asked it and who is in the conversation: the people Slack lists as members (up to 200), named by their display name, else their real name. Bots and deactivated accounts are left out. A one-to-one direct message has no member list.
The agent may @mention a member of the same conversation only when someone asks
it to pass something on or notify someone. Set mentions: false in the
profile block to post every mention as plain text.
When the Bridge Is Down#
Slack redelivers an event the bridge did not acknowledge only for a few minutes. A question posted while the bridge is down for longer than that is never answered, and nothing in Slack shows it was missed. Restart or upgrade the bridge at quiet times, and ask people to repeat a question that got no acknowledgement.