Space Monkey makes it easy to deploy your Slide agents as Slack agents. In this guide, you’ll learn how to create a Slack agent that can respond to messages, handle events, and interact with your workspace.

​
Prerequisites

Before starting, you’ll need:
  1. A Slack workspace where you can install apps
  2. Slack app credentials (we’ll create these)

​
Quick start

​
Step 1: Install Space Monkey

uv add slide-space-monkey

​
Step 2: Create Your Agent

import asyncio
from space_monkey import SlackApp
from tyler import Agent
from narrator import ThreadStore, FileStore
from lye import WEB_TOOLS

# Set environment variables first:
# export SLACK_BOT_TOKEN=xoxb-your-bot-token
# export SLACK_APP_TOKEN=xapp-your-app-token

async def main():
    # Initialize storage
    thread_store = await ThreadStore.create()
    file_store = await FileStore.create()
    
    # Create your agent
    agent = Agent(
        name="slack-assistant",
        model_name="gpt-4",
        purpose="To help Slack users with their questions",
        tools=WEB_TOOLS
    )
    
    # Create Slack app
    app = SlackApp(
        agent=agent,
        thread_store=thread_store,
        file_store=file_store
    )
    
    # Start the app
    await app.start(port=3000)

# Run the app
if __name__ == "__main__":
    asyncio.run(main())

​
Setting Up Slack App

​
1. Create a Slack App

  1. Go to api.slack.com/apps
  2. Click “Create New App” → “From scratch”
  3. Name your app and select your workspace

​
2. Configure Agent User

  1. Go to “OAuth & Permissions”
  2. Add these Bot Token Scopes:
    • app_mentions:read - Read mentions
    • chat:write - Send messages
    • channels:history - Read channel messages
    • groups:history - Read private channel messages
    • im:history - Read direct messages
    • mpim:history - Read group DMs
    • files:read - Read files (if using file tools)
    • files:write - Upload files (if creating files)

​
3. Install to Workspace

  1. Click “Install to Workspace”
  2. Authorize the app
  3. Copy the Bot User OAuth Token (starts with xoxb-)

​
4. Enable Socket Mode

  1. Go to “Socket Mode” in the sidebar
  2. Enable Socket Mode
  3. Create an app-level token with connections:write scope
  4. Copy the token (starts with xapp-)

​
5. Enable Events

  1. Go to “Event Subscriptions”
  2. Turn on “Enable Events”
  3. Subscribe to agent events:
    • app_mention
    • message.channels
    • message.groups
    • message.im
    • message.mpim

​
6. Set Environment Variables

Set these environment variables before running your agent: 
export SLACK_BOT_TOKEN=xoxb-your-bot-token
export SLACK_APP_TOKEN=xapp-your-app-token
export OPENAI_API_KEY=sk-your-openai-key

​
Advanced Agent Features

​
Conversation Persistence

Give your agent persistence across conversations: 
from narrator import ThreadStore, FileStore, Thread, Message

async def create_bot_with_persistence():
    # Set up persistent storage
    thread_store = await ThreadStore.create("postgresql://localhost/slackbot")
    file_store = await FileStore.create("./slack_files")
    
    # Create agent with persistence
    agent = Agent(
        name="persistent-agent",
        model_name="gpt-4",
        purpose="To be a helpful Slack assistant with conversation history",
        thread_store=thread_store,
        file_store=file_store,
        tools=WEB_TOOLS
    )
    
    return SlackApp(
        agent=agent,
        thread_store=thread_store,
        file_store=file_store
    )

app = await create_bot_with_persistence()

@app.event("app_mention")
async def handle_mention_with_persistence(event, say):
    # Use channel ID as thread ID for conversation continuity
    thread_id = f"slack-{event['channel']}"
    
    try:
        thread = await app.agent.thread_store.get_thread(thread_id)
    except:
        thread = Thread(id=thread_id)
    
    # Add user message
    user_text = event["text"].replace(f"<@{event['user']}>", "").strip()
    message = Message(
        role="user",
        content=user_text,
        metadata={"slack_user": event["user"]}
    )
    thread.add_message(message)
    
    # Process and save
    result = await app.agent.go(thread)
    await app.agent.thread_store.save_thread(result.thread)
    
    # Respond
    await say(result.new_messages[-1].content)

​
Message Routing

SlackApp automatically handles:
  • Direct messages
  • App mentions in channels
  • Thread replies
  • File uploads
  • Intelligent routing based on context
The agent will respond to:
  1. All direct messages
  2. Messages where the agent is @mentioned
  3. Replies in threads where the agent has participated
  4. Messages matching the configured response_topics

​
File Handling

SlackApp automatically processes files shared in Slack when the agent has file tools: 
from lye import IMAGE_TOOLS, FILES_TOOLS

agent = Agent(
    name="file-processor",
    model_name="gpt-4",
    purpose="To help analyze files and images",
    tools=[*IMAGE_TOOLS, *FILES_TOOLS]
)

app = SlackApp(
    agent=agent,
    thread_store=thread_store,
    file_store=file_store
)
Users can share files directly with the agent, and it will automatically download and process them.

​
Production Deployment

​
Environment Variables

# .env file
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
OPENAI_API_KEY=sk-your-openai-key
DATABASE_URL=postgresql://user:pass@localhost/slackbot

​
Docker Deployment

Space Monkey includes Docker support for easy deployment: 
# Clone your agent code
cd your-slack-agent/

# Build the Docker image
docker build -t my-slack-agent .

# Run with environment variables
docker run -d \
  --name slack-agent \
  -p 8000:8000 \
  -e SLACK_BOT_TOKEN=$SLACK_BOT_TOKEN \
  -e SLACK_APP_TOKEN=$SLACK_APP_TOKEN \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  my-slack-agent

​
Using Docker Compose

For easier local development: 
# Copy the example environment file
cp .env.example .env
# Edit .env with your credentials

# Start the agent
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the agent
docker-compose down
To use PostgreSQL for persistence: 
# Start with PostgreSQL
docker-compose --profile with-postgres up -d

​
Health Checks

SlackApp includes built-in health monitoring: 
# Set environment variables for health monitoring
export HEALTH_CHECK_URL=http://healthcheck:8000/ping-receiver
export HEALTH_PING_INTERVAL_SECONDS=120

# The app will automatically ping the health check URL
The app also provides a built-in health endpoint at /health.

​
Real-World Example: Team Assistant Agent

import os
import asyncio
from space_monkey import SlackApp
from tyler import Agent
from narrator import ThreadStore, FileStore
from lye import WEB_TOOLS, FILES_TOOLS, IMAGE_TOOLS

async def create_team_assistant():
    # Initialize storage
    thread_store = await ThreadStore.create(
        os.getenv("DATABASE_URL", "sqlite+aiosqlite:///slack_bot.db")
    )
    file_store = await FileStore.create("./team_files")
    
    # Create agent
    agent = Agent(
        name="team-assistant",
        model_name="gpt-4",
        purpose="""To be a helpful team assistant that can:
        - Answer questions about any topic
        - Research information
        - Analyze images and files
        - Remember context within channels
        """,
        tools=[*WEB_TOOLS, *FILES_TOOLS, *IMAGE_TOOLS],
        thread_store=thread_store,
        file_store=file_store
    )
    
    # Create Slack app
    app = SlackApp(
        agent=agent,
        thread_store=thread_store,
        file_store=file_store,
        response_topics="technical questions, research requests, and team productivity"
    )
    
    return app

# Run the agent
async def main():
    app = await create_team_assistant()
    await app.start(port=3000)

if __name__ == "__main__":
    asyncio.run(main())

​
Monitoring and Logging

SlackApp includes built-in logging. To configure logging levels: 
import logging

# Set logging level for space_monkey
logging.getLogger("space_monkey").setLevel(logging.INFO)
For production monitoring, you can also set up Weave tracing: 
# Set environment variables
export WANDB_API_KEY=your-wandb-key
export WANDB_PROJECT=slack-agent-prod

​
Troubleshooting

​
Next steps

Space Monkey Docs

Deep dive into Space Monkey

Examples

More Slack agent examples