Skip to content

Commit 37c2990

Browse files
seratchseratch
committed
Add Agents & Assistants document page
1 parent 0aaa9d2 commit 37c2990

File tree

3 files changed

+316
-0
lines changed

3 files changed

+316
-0
lines changed

‎docs/content/guides/assistants.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
lang: en
3+
---
4+
5+
# Agents & Assistants
6+
7+
This guide page focuses on how to implement Agents & Assistants using Bolt framework. For general information about the feature, please refer to [this document page](https://api.slack.com/docs/apps/ai).
8+
9+
## Slack App Configuration
10+
11+
To get started, you'll need to enable the **Agents & Assistants** feature on [the app configuration page](https://api.slack.com/apps). Then, add [assistant:write](https://api.slack.com/scopes/assistant:write), [chat:write](https://api.slack.com/scopes/chat:write), and [im:history](https://api.slack.com/scopes/im:history) to the **bot** scopes on the **OAuth & Permissions** page. Also, make sure to subscribe to [assistant_thread_started](https://api.slack.com/events/assistant_thread_started), [assistant_thread_context_changed](https://api.slack.com/events/assistant_thread_context_changed), and [message.im](https://api.slack.com/events/message.im) events on the **Event Subscriptions** page.
12+
13+
Please note that 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.
14+
15+
## Examples
16+
17+
To handle assistant thread interactions with humans, although you can implement your agents using `app.event(...)` listeners for `assistant_thread_started`, `assistant_thread_context_changed`, and `message` events, Bolt offers a simpler approach. You just need to create an `Assistant` instance, attach the needed event handlers to it, and then add the assistant to your `App` instance.
18+
19+
```java
20+
App app = new App();
21+
Assistant assistant = new Assistant(app.executorService());
22+
23+
assistant.threadStarted((req, ctx) -> {
24+
try {
25+
ctx.say(r -> r.text("Hi, how can I help you today?"));
26+
ctx.setSuggestedPrompts(Collections.singletonList(
27+
SuggestedPrompt.create("What does SLACK stand for?")
28+
));
29+
} catch (Exception e) {
30+
ctx.logger.error("Failed to handle assistant thread started event: {e}", e);
31+
}
32+
});
33+
34+
assistant.userMessage((req, ctx) -> {
35+
try {
36+
ctx.setStatus("is typing...");
37+
Thread.sleep(500L);
38+
if (ctx.getThreadContext() != null) {
39+
String contextChannel = ctx.getThreadContext().getChannelId();
40+
ctx.say(r -> r.text("I am ware of the channel context: <#" + contextChannel + ">"));
41+
} else {
42+
ctx.say(r -> r.text("Here you are!"));
43+
}
44+
} catch (Exception e) {
45+
ctx.logger.error("Failed to handle assistant thread started event: {e}", e);
46+
try {
47+
ctx.say(r -> r.text(":warning: Sorry, something went wrong during processing your request!"));
48+
} catch (Exception ee) {
49+
ctx.logger.error("Failed to inform the error to the end-user: {ee}", ee);
50+
}
51+
}
52+
});
53+
54+
app.assistant(assistant);
55+
```
56+
57+
When an end-user opens an assistant thread next to a channel, the channel information is stored as the thread's `AssistantThreadContext` data, and you can access this information by using `context.getThreadContextService().findCurrentContext(channelId, threadTs)` utility.
58+
59+
When the user switches the channel, the `assistant_thread_context_changed` event will be sent to your app. If you use the built-in `Assistant` middleware without any custom configuration (like the above code snippet does), the updated context data is automatically saved as message metadata of the first reply from the assistant bot. This means that, as long as you go with this built-in approach, you don't need to store the context data within any datastore. The only downside of this default module is the runtime overhead of additional Slack API calls. More specifically, it calls `conversations.history` API to look up the stored message metadata when you execute `context.getThreadContextService().findCurrentContext(channelId, threadTs)`.
60+
61+
If you prefer storing this data elsewhere, you can pass your own `AssistantThreadContextService` implementation to the `Assistant` instance:
62+
63+
```java
64+
Assistant assistant = new Assistant(new YourOwnAssistantThreadContextService());
65+
```
66+
67+
<details>
68+
69+
<summary>
70+
Block Kit interactions in the assistant thread
71+
</summary>
72+
73+
For advanced use cases, you might want to use Block Kit buttons instead of the suggested prompts. Additionally, consider sending a message with structured metadata to trigger subsequent interactions with the user.
74+
75+
For example, your app can display a button like "Summarize the referring channel" in the initial reply. When an end-user clicks the button and submits detailed information (such as the number of messages, days to check, the purpose of the summary, etc.), your app can handle the received information and post a bot message describing the request with structured metadata.
76+
77+
By default, your app can't respond to its own bot messages (Bolt prevents infinite loops by default). However, if you set `ignoringSelfAssistantMessageEventsEnabled` to false and add a `botMessage` listener to your `Assistant` middleware, your app can continue processing the request as shown below:
78+
79+
```java
80+
App app = new App(AppConfig.builder()
81+
.singleTeamBotToken(System.getenv("SLACK_BOT_TOKEN"))
82+
.ignoringSelfAssistantMessageEventsEnabled(false)
83+
.build());
84+
85+
Assistant assistant = new Assistant(app.executorService());
86+
87+
assistant.threadStarted((req, ctx) -> {
88+
try {
89+
ctx.say(r -> r
90+
.text("Hi, how can I help you today?")
91+
.blocks(Arrays.asList(
92+
section(s -> s.text(plainText("Hi, how I can I help you today?"))),
93+
actions(a -> a.elements(Collections.singletonList(
94+
button(b -> b.actionId("assistant-generate-numbers").text(plainText("Generate numbers")))
95+
)))
96+
))
97+
);
98+
} catch (Exception e) {
99+
ctx.logger.error("Failed to handle assistant thread started event: {e}", e);
100+
}
101+
});
102+
103+
app.blockAction("assistant-generate-numbers", (req, ctx) -> {
104+
app.executorService().submit(() -> {
105+
Map<String, Object> eventPayload = new HashMap<>();
106+
eventPayload.put("num", 20);
107+
try {
108+
ctx.client().chatPostMessage(r -> r
109+
.channel(req.getPayload().getChannel().getId())
110+
.threadTs(req.getPayload().getMessage().getThreadTs())
111+
.text("OK, I will generate numbers for you!")
112+
.metadata(new Message.Metadata("assistant-generate-numbers", eventPayload))
113+
);
114+
} catch (Exception e) {
115+
ctx.logger.error("Failed to post a bot message: {e}", e);
116+
}
117+
});
118+
return ctx.ack();
119+
});
120+
121+
assistant.botMessage((req, ctx) -> {
122+
if (req.getEvent().getMetadata() != null
123+
&& req.getEvent().getMetadata().getEventType().equals("assistant-generate-numbers")) {
124+
try {
125+
ctx.setStatus("is typing...");
126+
Double num = (Double) req.getEvent().getMetadata().getEventPayload().get("num");
127+
Set<String> numbers = new HashSet<>();
128+
SecureRandom random = new SecureRandom();
129+
while (numbers.size() < num) {
130+
numbers.add(String.valueOf(random.nextInt(100)));
131+
}
132+
Thread.sleep(1000L);
133+
ctx.say(r -> r.text("Her you are: " + String.join(", ", numbers)));
134+
} catch (Exception e) {
135+
ctx.logger.error("Failed to handle assistant bot message event: {e}", e);
136+
}
137+
}
138+
});
139+
140+
assistant.userMessage((req, ctx) -> {
141+
try {
142+
ctx.setStatus("is typing...");
143+
ctx.say(r -> r.text("Sorry, I couldn't understand your comment."));
144+
} catch (Exception e) {
145+
ctx.logger.error("Failed to handle assistant user message event: {e}", e);
146+
try {
147+
ctx.say(r -> r.text(":warning: Sorry, something went wrong during processing your request!"));
148+
} catch (Exception ee) {
149+
ctx.logger.error("Failed to inform the error to the end-user: {ee}", ee);
150+
}
151+
}
152+
});
153+
154+
app.assistant(assistant);
155+
```
156+
157+
</details>

‎docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/guides/assistants.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
lang: en
3+
---
4+
5+
# エージェント・アシスタント
6+
7+
このページは、Bolt を使ってエージェント・アシスタントを実装するための方法を紹介します。この機能に関する一般的な情報については、[こちらのドキュメントページ（英語）](https://api.slack.com/docs/apps/ai)を参照してください。
8+
9+
## Slack App Configuration
10+
11+
この機能を実装するためには、まず[アプリの設定画面](https://api.slack.com/apps)で **Agents & Assistants** 機能を有効にし.
12+
**OAuth & Permissions** のページで [assistant:write](https://api.slack.com/scopes/assistant:write)、[chat:write](https://api.slack.com/scopes/chat:write)、[im:history](https://api.slack.com/scopes/im:history) を**ボットの**スコープに追加し、**Event Subscriptions** のページで [assistant_thread_started](https://api.slack.com/events/assistant_thread_started)、[assistant_thread_context_changed](https://api.slack.com/events/assistant_thread_context_changed)、[message.im](https://api.slack.com/events/message.im) イベントを有効にしてください。
13+
14+
また、この機能は Slack の有料プランでのみ利用可能です。もし開発用の有料プランのワークスペースをお持ちでない場合は、[Developer Program](https://api.slack.com/developer-program) に参加し、全ての有料プラン向け機能を利用可能なサンドボックス環境をつくることができます。
15+
16+
## Examples
17+
18+
ユーザーとのアシスタントスレッド内でのやりとりを処理するには、`assistant_thread_started`、`assistant_thread_context_changed`、`message` イベントの `app.event(...)` リスナーを使うことも可能ですが、Bolt はよりシンプルなアプローチを提供しています。`Assistant` インスタンスを作り、それに必要なイベントリスナーを追加し、最後にこのアシスタント設定を `App` インスタンスに渡すだけで良いのです。
19+
20+
```java
21+
App app = new App();
22+
Assistant assistant = new Assistant(app.executorService());
23+
24+
assistant.threadStarted((req, ctx) -> {
25+
try {
26+
ctx.say(r -> r.text("Hi, how can I help you today?"));
27+
ctx.setSuggestedPrompts(Collections.singletonList(
28+
SuggestedPrompt.create("What does SLACK stand for?")
29+
));
30+
} catch (Exception e) {
31+
ctx.logger.error("Failed to handle assistant thread started event: {e}", e);
32+
}
33+
});
34+
35+
assistant.userMessage((req, ctx) -> {
36+
try {
37+
ctx.setStatus("is typing...");
38+
Thread.sleep(500L);
39+
if (ctx.getThreadContext() != null) {
40+
String contextChannel = ctx.getThreadContext().getChannelId();
41+
ctx.say(r -> r.text("I am ware of the channel context: <#" + contextChannel + ">"));
42+
} else {
43+
ctx.say(r -> r.text("Here you are!"));
44+
}
45+
} catch (Exception e) {
46+
ctx.logger.error("Failed to handle assistant thread started event: {e}", e);
47+
try {
48+
ctx.say(r -> r.text(":warning: Sorry, something went wrong during processing your request!"));
49+
} catch (Exception ee) {
50+
ctx.logger.error("Failed to inform the error to the end-user: {ee}", ee);
51+
}
52+
}
53+
});
54+
55+
app.assistant(assistant);
56+
```
57+
58+
ユーザーがチャンネルの横でアシスタンスレッドを開いた場合、そのチャンネルの情報はそのスレッドの `AssistantThreadContext` データとして保持され、 `context.getThreadContextService().findCurrentContext(channelId, threadTs)` ユーティリティを使ってアクセスすることができます。
59+
60+
そのユーザーがチャンネルを切り替えた場合、`assistant_thread_context_changed` イベントがあなたのアプリに送信されます。（上記のコード例のように）組み込みの `Assistant` ミドルウェアをカスタム設定なしで利用している場合、この更新されたチャンネル情報は、自動的にこのアシスタントボットからの最初の返信のメッセージメタデータとして保存されます。これは、組み込みの仕組みを使う場合は、このコンテキスト情報を自前で用意したデータストアに保存する必要はないということです。この組み込みの仕組みの唯一の短所は、追加の Slack API 呼び出しによる処理時間のオーバーヘッドです。具体的には `context.getThreadContextService().findCurrentContext(channelId, threadTs)` を実行したときに、この保存されたメッセージメタデータにアクセスするために `conversations.history` API が呼び出されます。
61+
62+
このデータを別の場所に保存したい場合、自前の `AssistantThreadContextService` 実装を `Assistant` のコンストラクターに渡すことができます。
63+
64+
```java
65+
Assistant assistant = new Assistant(new YourOwnAssistantThreadContextService());
66+
```
67+
68+
<details>
69+
70+
<summary>
71+
アシスタントスレッドでの Block Kit インタラクション
72+
</summary>
73+
74+
より高度なユースケースでは、上のようなプロンプト例の提案ではなく Block Kit のボタンなどを使いたいという場合があるかもしれません。そして、後続の処理のために構造化されたメッセージメタデータを含むメッセージを送信したいという場合もあるでしょう。
75+
76+
例えば、アプリが最初の返信で「参照しているチャンネルを要約」のようなボタンを表示し、ユーザーがそれをクリックして、より詳細な情報（例：要約するメッセージ数・日数、要約の目的など）を送信、アプリがそれを構造化されたメータデータに整理した上でリクエスト内容をボットのメッセージとして送信するようなシナリオです。
77+
78+
デフォルトでは、アプリはそのアプリ自身から送信したボットメッセージに応答することはできません（Bolt にはあらかじめ無限ループを防止する制御が入っているため）。`ignoringSelfAssistantMessageEventsEnabled` を false に設定し、`botMessage` リスナーを `Assistant` ミドルウェアに追加すると、上記の例のようなリクエストを伝えるボットメッセージを使って処理を継続することができるようになります。
79+
80+
```java
81+
App app = new App(AppConfig.builder()
82+
.singleTeamBotToken(System.getenv("SLACK_BOT_TOKEN"))
83+
.ignoringSelfAssistantMessageEventsEnabled(false)
84+
.build());
85+
86+
Assistant assistant = new Assistant(app.executorService());
87+
88+
assistant.threadStarted((req, ctx) -> {
89+
try {
90+
ctx.say(r -> r
91+
.text("Hi, how can I help you today?")
92+
.blocks(Arrays.asList(
93+
section(s -> s.text(plainText("Hi, how I can I help you today?"))),
94+
actions(a -> a.elements(Collections.singletonList(
95+
button(b -> b.actionId("assistant-generate-numbers").text(plainText("Generate numbers")))
96+
)))
97+
))
98+
);
99+
} catch (Exception e) {
100+
ctx.logger.error("Failed to handle assistant thread started event: {e}", e);
101+
}
102+
});
103+
104+
app.blockAction("assistant-generate-numbers", (req, ctx) -> {
105+
app.executorService().submit(() -> {
106+
Map<String, Object> eventPayload = new HashMap<>();
107+
eventPayload.put("num", 20);
108+
try {
109+
ctx.client().chatPostMessage(r -> r
110+
.channel(req.getPayload().getChannel().getId())
111+
.threadTs(req.getPayload().getMessage().getThreadTs())
112+
.text("OK, I will generate numbers for you!")
113+
.metadata(new Message.Metadata("assistant-generate-numbers", eventPayload))
114+
);
115+
} catch (Exception e) {
116+
ctx.logger.error("Failed to post a bot message: {e}", e);
117+
}
118+
});
119+
return ctx.ack();
120+
});
121+
122+
assistant.botMessage((req, ctx) -> {
123+
if (req.getEvent().getMetadata() != null
124+
&& req.getEvent().getMetadata().getEventType().equals("assistant-generate-numbers")) {
125+
try {
126+
ctx.setStatus("is typing...");
127+
Double num = (Double) req.getEvent().getMetadata().getEventPayload().get("num");
128+
Set<String> numbers = new HashSet<>();
129+
SecureRandom random = new SecureRandom();
130+
while (numbers.size() < num) {
131+
numbers.add(String.valueOf(random.nextInt(100)));
132+
}
133+
Thread.sleep(1000L);
134+
ctx.say(r -> r.text("Her you are: " + String.join(", ", numbers)));
135+
} catch (Exception e) {
136+
ctx.logger.error("Failed to handle assistant bot message event: {e}", e);
137+
}
138+
}
139+
});
140+
141+
assistant.userMessage((req, ctx) -> {
142+
try {
143+
ctx.setStatus("is typing...");
144+
ctx.say(r -> r.text("Sorry, I couldn't understand your comment."));
145+
} catch (Exception e) {
146+
ctx.logger.error("Failed to handle assistant user message event: {e}", e);
147+
try {
148+
ctx.say(r -> r.text(":warning: Sorry, something went wrong during processing your request!"));
149+
} catch (Exception ee) {
150+
ctx.logger.error("Failed to inform the error to the end-user: {ee}", ee);
151+
}
152+
}
153+
});
154+
155+
app.assistant(assistant);
156+
```
157+
158+
</details>

‎docs/sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ const sidebars = {
3131
items: [
3232
'guides/bolt-basics',
3333
'guides/socket-mode',
34+
'guides/assistants',
3435
'guides/shortcuts',
3536
'guides/interactive-components',
3637
'guides/modals',

0 commit comments

Comments
 (0)