feat: showcase text generation and thinking steps with tool calls from suggested prompts (#43)

Co-authored-by: Michael Brooks <michael@michaelbrooks.ca>
Co-authored-by: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com>
Co-authored-by: Ale Mercado <maria.mercado@salesforce.com>
Co-authored-by: Michael Brooks <mbrooks@slack-corp.com>

Author: 4 people

.env.sample

@@ -1,5 +1,9 @@
-SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN
-SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN
+# Optional, uncomment and set when running without the Slack CLI (python3 app.py).
+# SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN
+# SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN
+
+# Optional, uncomment and set when using a custom Slack instance.
 # SLACK_API_URL=YOUR_SLACK_API_URL
-# This template uses OpenAI, but you can use any other provider!
+
+# Required, set your OpenAI API key.
 OPENAI_API_KEY=YOUR_OPENAI_API_KEY

README.md

@@ -1,8 +1,15 @@
 # AI Agent App Template (Bolt for Python)
 
-This Bolt for Python template demonstrates how to build [AI Apps](https://docs.slack.dev/ai/) in Slack.
+This Bolt for Python template demonstrates how to build [AI Apps](https://docs.slack.dev/ai/) in Slack, using models from [OpenAI](https://openai.com).
 
-Models from [OpenAI](https://openai.com) are used and can be customized for prompts of all kinds.
+## App overview
+
+Setting up this app can provide you with an AI agent that enables the following flow:
+
+* Users open the assistant side panel in Slack and see suggested prompts.
+* The app calls OpenAI's API when a user selects a prompt or sends a message.
+* The app streams in its response, which can be a combination of text and tasks.
+* Users provide feedback via buttons.
 
 ## Setup
 
@@ -16,7 +23,7 @@ Join the [Slack Developer Program](https://api.slack.com/developer-program) for
 
 Add this app to your workspace using either the Slack CLI or other development tooling, then read ahead to configuring LLM responses in the **[Providers](#providers)** section.
 
-### Using Slack CLI
+<details><summary><strong>Using Slack CLI</strong></summary>
 
 Install the latest version of the Slack CLI for your operating system:
 
@@ -46,7 +53,11 @@ slack install
 
 After the Slack app has been created you're all set to configure the LLM provider!
 
-### Using Terminal
+</details>
+
+<details><summary><strong>Using Terminal</strong></summary>
+
+#### Create Your Slack App
 
 1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and choose "From an app manifest"
 2. Choose the workspace you want to install the application to
@@ -91,6 +102,8 @@ source .venv/bin/activate  # for Windows OS, .\.venv\Scripts\Activate instead sh
 pip install -r requirements.txt
 ```
 
+</details>
+
 ## Providers
 
 ### OpenAI Setup
@@ -150,9 +163,11 @@ Configures the new Slack Assistant features, providing a dedicated side panel UI
 - The `assistant_thread_started.py` file, which responds to new app threads with a list of suggested prompts.
 - The `message.py` file, which responds to user messages sent to app threads or from the **Chat** and **History** tab with an LLM generated response.
 
-### `/ai`
+### `/agent`
+
+The `llm_caller.py` file calls the OpenAI API and streams the generated response into a Slack conversation.
 
-The `llm_caller.py` file, which handles OpenAI API integration and message formatting. It includes the `call_llm()` function that sends conversation threads to OpenAI's models.
+The `tools` directory contains app-specific functions for the LLM to call.
 
 ## App Distribution / OAuth
 

agent/llm_caller.py

@@ -0,0 +1,101 @@
+import json
+import os
+
+import openai
+from openai.types.responses import ResponseInputParam
+from slack_sdk.models.messages.chunk import TaskUpdateChunk
+from slack_sdk.web.chat_stream import ChatStream
+
+from agent.tools.dice import roll_dice, roll_dice_definition
+
+
+def call_llm(
+    streamer: ChatStream,
+    prompts: ResponseInputParam,
+):
+    """
+    Stream an LLM response to prompts with an example dice rolling function
+
+    https://docs.slack.dev/tools/python-slack-sdk/web#sending-streaming-messages
+    https://platform.openai.com/docs/guides/text
+    https://platform.openai.com/docs/guides/streaming-responses
+    https://platform.openai.com/docs/guides/function-calling
+    """
+    llm = openai.OpenAI(
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+    tool_calls = []
+    response = llm.responses.create(
+        model="gpt-4o-mini",
+        input=prompts,
+        tools=[
+            roll_dice_definition,
+        ],
+        stream=True,
+    )
+    for event in response:
+        # Markdown text from the LLM response is streamed in chat as it arrives
+        if event.type == "response.output_text.delta":
+            streamer.append(markdown_text=f"{event.delta}")
+
+        # Function calls are saved for later computation and a new task is shown
+        if event.type == "response.output_item.done":
+            if event.item.type == "function_call":
+                tool_calls.append(event.item)
+                if event.item.name == "roll_dice":
+                    args = json.loads(event.item.arguments)
+                    streamer.append(
+                        chunks=[
+                            TaskUpdateChunk(
+                                id=f"{event.item.call_id}",
+                                title=f"Rolling a {args['count']}d{args['sides']}...",
+                                status="in_progress",
+                            ),
+                        ],
+                    )
+
+    # Tool calls are performed and tasks are marked as completed in Slack
+    if tool_calls:
+        for call in tool_calls:
+            if call.name == "roll_dice":
+                args = json.loads(call.arguments)
+                prompts.append(
+                    {
+                        "id": call.id,
+                        "call_id": call.call_id,
+                        "type": "function_call",
+                        "name": "roll_dice",
+                        "arguments": call.arguments,
+                    }
+                )
+                result = roll_dice(**args)
+                prompts.append(
+                    {
+                        "type": "function_call_output",
+                        "call_id": call.call_id,
+                        "output": json.dumps(result),
+                    }
+                )
+                if result.get("error") is not None:
+                    streamer.append(
+                        chunks=[
+                            TaskUpdateChunk(
+                                id=f"{call.call_id}",
+                                title=f"{result['error']}",
+                                status="error",
+                            ),
+                        ],
+                    )
+                else:
+                    streamer.append(
+                        chunks=[
+                            TaskUpdateChunk(
+                                id=f"{call.call_id}",
+                                title=f"{result['description']}",
+                                status="complete",
+                            ),
+                        ],
+                    )
+
+        # Complete the LLM response after making tool calls
+        call_llm(streamer, prompts)

agent/tools/__init__.py

@@ -0,0 +1,56 @@
+import random
+
+from openai.types.responses import FunctionToolParam
+
+
+def roll_dice(sides: int = 6, count: int = 1) -> dict:
+    if sides < 2:
+        return {
+            "error": "A die must have at least 2 sides",
+            "rolls": [],
+            "total": 0,
+        }
+
+    if count < 1:
+        return {
+            "error": "Must roll at least 1 die",
+            "rolls": [],
+            "total": 0,
+        }
+
+    # Roll the dice and calculate the total
+    rolls = [random.randint(1, sides) for _ in range(count)]
+    total = sum(rolls)
+
+    return {
+        "rolls": rolls,
+        "total": total,
+        "description": f"Rolled a {count}d{sides} to total {total}",
+    }
+
+
+# Tool definition for OpenAI API
+#
+# https://platform.openai.com/docs/guides/function-calling
+roll_dice_definition: FunctionToolParam = {
+    "type": "function",
+    "name": "roll_dice",
+    "description": "Roll one or more dice with a specified number of sides. Use this when the user wants to roll dice or generate random numbers within a range.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "sides": {
+                "type": "integer",
+                "description": "The number of sides on the die (e.g., 6 for a standard die, 20 for a d20)",
+                "default": 6,
+            },
+            "count": {
+                "type": "integer",
+                "description": "The number of dice to roll",
+                "default": 1,
+            },
+        },
+        "required": ["sides", "count"],
+    },
+    "strict": False,
+}

agent/tools/dice.py

@@ -2,7 +2,6 @@
 import os
 
 from dotenv import load_dotenv
-
 from slack_bolt import App
 from slack_bolt.adapter.socket_mode import SocketModeHandler
 from slack_sdk import WebClient
@@ -22,6 +21,7 @@
         token=os.environ.get("SLACK_BOT_TOKEN"),
     ),
 )
+
 # Register Listeners
 register_listeners(app)
 

ai/llm_caller.py

@@ -1,5 +1,4 @@
 from logging import Logger
-from typing import Dict, List
 
 from slack_bolt import Say, SetSuggestedPrompts
 
@@ -18,24 +17,19 @@ def assistant_thread_started(
         logger: Logger instance for error tracking
     """
     try:
-        say("How can I help you?")
-
-        prompts: List[Dict[str, str]] = [
-            {
-                "title": "What does Slack stand for?",
-                "message": "Slack, a business communication service, was named after an acronym. Can you guess what it stands for?",
-            },
-            {
-                "title": "Write a draft announcement",
-                "message": "Can you write a draft announcement about a new feature my team just released? It must include how impactful it is.",
-            },
-            {
-                "title": "Suggest names for my Slack app",
-                "message": "Can you suggest a few names for my Slack app? The app helps my teammates better organize information and plan priorities and action items.",
-            },
-        ]
-
-        set_suggested_prompts(prompts=prompts)
+        say("What would you like to do today?")
+        set_suggested_prompts(
+            prompts=[
+                {
+                    "title": "Prompt a task with thinking steps",
+                    "message": "Wonder a few deep thoughts.",
+                },
+                {
+                    "title": "Roll dice for a random number",
+                    "message": "Roll two 12-sided dice and three 6-sided dice for a pseudo-random score.",
+                },
+            ]
+        )
     except Exception as e:
         logger.exception(f"Failed to handle an assistant_thread_started event: {e}", e)
         say(f":warning: Something went wrong! ({e})")