diff --git a/docs/content/concepts/assistant.md b/docs/content/concepts/ai-apps.md similarity index 85% rename from docs/content/concepts/assistant.md rename to docs/content/concepts/ai-apps.md index 469bba966..eb5f64fff 100644 --- a/docs/content/concepts/assistant.md +++ b/docs/content/concepts/ai-apps.md @@ -1,18 +1,18 @@ --- -title: Agents & Assistants +title: AI Apps lang: en -slug: /concepts/assistant +slug: /concepts/ai-apps --- :::info This feature requires a paid plan If you don't have a paid workspace for development, you can join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. ::: -Agents and assistants comprise a new messaging experience for Slack. If you're unfamiliar with using agents and assistants within Slack, you'll want to read the [API documentation on the subject](https://api.slack.com/docs/apps/ai). Then come back here to implement them with Bolt! +AI apps comprise a new messaging experience for Slack. If you're unfamiliar with using AI apps within Slack, you'll want to read the [API documentation on the subject](https://api.slack.com/docs/apps/ai). Then come back here to implement them with Bolt! -## Configuring your app to support assistants {#configuring-your-app} +## Configuring your app to support AI features {#configuring-your-app} -1. Within [App Settings](https://api.slack.com/apps), enable the **Agents & Assistants** feature. +1. Within [App Settings](https://api.slack.com/apps), enable the **Agents & AI Apps** feature. 2. Within the App Settings **OAuth & Permissions** page, add the following scopes: * [`assistant:write`](https://api.slack.com/scopes/assistant:write) @@ -25,16 +25,16 @@ Agents and assistants comprise a new messaging experience for Slack. If you're u * [`message.im`](https://api.slack.com/events/message.im) :::info -You _could_ implement your own assistants by [listening](event-listening) for the `assistant_thread_started`, `assistant_thread_context_changed`, and `message.im` events (see implementation details below). That being said, using the `Assistant` class will streamline the process. And we already wrote this nice guide for you! +You _could_ implement your own AI app by [listening](event-listening) for the `assistant_thread_started`, `assistant_thread_context_changed`, and `message.im` events (see implementation details below). That being said, using the `Assistant` class will streamline the process. And we already wrote this nice guide for you! ::: ## The `Assistant` class instance {#assistant-class} -The `Assistant` class can be used to handle the incoming events expected from a user interacting with an assistant in Slack. A typical flow would look like: +The `Assistant` class can be used to handle the incoming events expected from a user interacting with an AI app in Slack. A typical flow would look like: 1. [The user starts a thread](#handling-a-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event. -2. [The thread context may change at any point](#handling-thread-context-changes). The Assistant class can handle any incoming [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) events. The class also provides a default context store to keep track of thread context changes as the user moves through Slack. -3. [The user responds](#handling-the-user-response). The Assistant class handles the incoming [`message.im`](https://api.slack.com/events/message.im) event. +2. [The thread context may change at any point](#handling-thread-context-changes). The `Assistant` class can handle any incoming [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) events. The class also provides a default context store to keep track of thread context changes as the user moves through Slack. +3. [The user responds](#handling-the-user-response). The `Assistant` class handles the incoming [`message.im`](https://api.slack.com/events/message.im) event. ```python @@ -97,7 +97,7 @@ def respond_in_assistant_thread( app.use(assistant) ``` -While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextStore` property — but it also provides an instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](https://api.slack.com/metadata/using) as the user interacts with the assistant. +While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextStore` property — but it also provides an instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](https://api.slack.com/metadata/using) as the user interacts with the app. If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods. @@ -107,13 +107,13 @@ Refer to the [module document](https://tools.slack.dev/bolt-python/api-docs/slac ## Handling a new thread {#handling-a-new-thread} -When the user opens a new thread with your assistant, the [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event will be sent to your app. +When the user opens a new thread with your AI app, the [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event will be sent to your app. :::tip -When a user opens an assistant thread while in a channel, the channel info is stored as the thread's `AssistantThreadContext` data. You can grab that info by using the `get_thread_context` utility, as subsequent user message event payloads won't include the channel info. +When a user opens an AI app thread while in a channel, the channel info is stored as the thread's `AssistantThreadContext` data. You can grab that info by using the `get_thread_context` utility, as subsequent user message event payloads won't include the channel info. ::: -### Block Kit interactions in the assistant thread {#block-kit-interactions} +### Block Kit interactions in the AI app thread {#block-kit-interactions} For advanced use cases, Block Kit buttons may be used instead of suggested prompts, as well as the sending of messages with structured [metadata](https://api.slack.com/metadata) to trigger subsequent interactions with the user. @@ -243,7 +243,7 @@ def respond_to_bot_messages(logger: logging.Logger, set_status: SetStatus, say: When the user switches channels, the [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) event will be sent to your app. -If you use the built-in `Assistant` middleware without any custom configuration, the updated context data is automatically saved as [message metadata](https://api.slack.com/metadata/using) of the first reply from the assistant bot. +If you use the built-in `Assistant` middleware without any custom configuration, the updated context data is automatically saved as [message metadata](https://api.slack.com/metadata/using) of the first reply from the app. As long as you use the built-in approach, you don't need to store the context data within a datastore. The downside of this default behavior is the overhead of additional calls to the Slack API. These calls include those to `conversations.history`, which are used to look up the stored message metadata that contains the thread context (via `get_thread_context`). @@ -256,9 +256,9 @@ assistant = Assistant(thread_context_store=FileAssistantThreadContextStore()) ## Handling the user response {#handling-the-user-response} -When the user messages your assistant, the [`message.im`](https://api.slack.com/events/message.im) event will be sent to your app. +When the user messages your app, the [`message.im`](https://api.slack.com/events/message.im) event will be sent to your app. -Messages sent to the assistant do not contain a [subtype](https://api.slack.com/events/message#subtypes) and must be deduced based on their shape and any provided [message metadata](https://api.slack.com/metadata/using). +Messages sent to the app do not contain a [subtype](https://api.slack.com/events/message#subtypes) and must be deduced based on their shape and any provided [message metadata](https://api.slack.com/metadata/using). There are three utilities that are particularly useful in curating the user experience: * [`say`](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/#slack_bolt.Say) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index b7a5ad096..60f3eae81 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -72,6 +72,10 @@ const config = { '/concepts/executing-steps' ], }, + { + to: '/concepts/ai-apps', + from: '/concepts/assistant' + } ], }, ], diff --git a/docs/sidebars.js b/docs/sidebars.js index cf35d83d5..752b61787 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -39,7 +39,7 @@ const sidebars = { "concepts/app-home", ], }, - "concepts/assistant", + "concepts/ai-apps", "concepts/custom-steps", { type: "category",