クイックスタート

基本設定

1. 01

   デプロイメントパッケージを入手する

   bashコピー

   git clone https://github.com/AgentBull/ankole.git
   cd ankole/tools/deploy/docker-compose
   cp .env.example .env
   chmod 600 .env

2. 02

   3 つの独立した secret を生成する

   このコマンドをコピーして実行してください。その完全な出力を .env に貼り付けます。

   bashコピー

   printf '%s\n' \
     '# PostgreSQL database password' \
     "POSTGRES_PASSWORD=$(openssl rand -hex 32)" \
     '' \
     '# ANKOLE master encryption key' \
     "ANKOLE_SECRET_BASE=$(openssl rand -hex 32)" \
     '' \
     '# Authentication key shared by the ANKOLE control plane and Agent Workers' \
     "ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY=$(openssl rand -hex 32)"

3. 03

   公開ホストを設定する

   ANKOLE_HOST に、このホストを指す DNS 名を設定してください。ACME_EMAIL には、証明書の通知を受信できるアドレスを設定してください。

   ANKOLE_HOST

   ankole.example.com

   ユーザーと provider の callback が使用する HTTPS ホスト。

   ACME_EMAIL

   ops@example.com

   Caddy の証明書管理用の連絡先アドレス。

4. 04

   スタックを起動して確認する

   Compose は PostgreSQL を待ち、migration を実行し、Worker key を保存した後、control plane、Worker、Caddy を起動します。

   bashコピー

   docker compose pull
   docker compose up -d
   docker compose ps

5. 05

   初回のセットアップを開く

   https://<ANKOLE_HOST>/setup を開き、activation code を入力してください。

   bashコピー

   docker compose logs control-plane | grep "SETUP ACTIVATION CODE"

基本設定

1. 01

   Ankole から callback URL をコピーする

   https://<ANKOLE_HOST>/setup を開き、activation code を入力してください。プラグインページで Slack Adapter を選択し、選択を保存してから Slack を選択してください。

   Configuration ID（Provider ID）は slack-main のままにしてください。Copy を使ってログイン callback URL をコピーしてください。この URL を手で入力したり変更したりしないでください。

2. 02

   Slack app を作成する

   Slack API の Your Apps を開き、Create New App → From scratch を選択してください。アプリ名を入力し、社員が所属するワークスペースを選択してください。

   Basic Information → App Credentials を開いてください。Client ID と Client Secret をコピーしてください。

   Slack Your Apps を開く
3. 03

   ログイン callback を登録する

   OAuth & Permissions → Redirect URLs を開いてください。Add New Redirect URL を選択し、Ankole の完全な URL を貼り付けて保存してください。

   Ankole はデフォルトで openid、profile、email のサインイン scope を要求します。それらを chat bot の scope に置き換えないでください。

   Slack サインインガイド
4. 04

   ディレクトリアクセスを許可して Bot Token を取得する

   OAuth & Permissions で、下記の 3 つの scope を Bot Token Scopes に追加してください。その後、Install to Workspace を選択してインストールを承認してください。

   • users:read

     メンバープロファイルを読み取ります

     コピー
   • users:read.email

     メンバーのメールアドレスを読み取ります

     コピー
   • usergroups:read

     ユーザーグループとそのメンバーを読み取ります

     コピー

   インストール後に Bot User OAuth Token をコピーしてください。xoxb- で始まる必要があります。scope を変更するたびにアプリを再インストールしてください。

5. 05

   App Token を取得して Socket Mode を有効にする

   Basic Information → App-Level Tokens を開いてください。Generate Token and Scopes を選択し、下記の scope を追加して、生成された xapp- token をコピーしてください。その後、Socket Mode を開き、Enable Socket Mode をオンにしてください。

   • connections:write

     App Token が Socket Mode 接続を開けるようにします

     コピー
6. 06

   ディレクトリイベントを購読する

   Event Subscriptions を開いてイベントを有効にしてください。Subscribe to bot events で、下記の 5 つのイベントをすべて追加してください。

   • team_join

     メンバーがワークスペースに参加します

     コピー
   • user_change

     メンバーのプロファイルが変更されます

     コピー
   • subteam_created

     ユーザーグループが作成されます

     コピー
   • subteam_updated

     ユーザーグループが変更されます

     コピー
   • subteam_members_changed

     ユーザーグループのメンバーシップが変更されます

     コピー

   Slack Socket Mode ガイド
7. 07

   Slack の値を Ankole に入力する

   Sync directory と Sync directory changes をオンにしたままにしてください。Validate configuration を選択してサインインしてください。その後、Slack の認可を完了してください。

   • Client ID: Basic Information の Client ID
   • Client Secret: 同じページの Client Secret
   • Workspace ID: 任意。Slack の Web URL の /client/ の後に続く T… の値を入力すると、サインインするワークスペースを事前選択できます。ディレクトリ同期は制限されません
   • Bot User OAuth Token: xoxb- token
   • App-Level Token: xapp- token
8. 08

   サインインと最初の同期を確認する

   Slack が Ankole に戻ると、このユーザーが最初の root administrator になります。Console → Identity Providers を開き、slack-main を選択して Run full sync を選択してください。

   同期が終わったら、Console → Principals と Principal groups で、ワークスペースのメンバーと Slack のユーザーグループを確認してください。

基本設定

1. 01

   アプリを作成して Socket Mode を有効にする

   Slack app をゼロから作成してください。Basic Information で App-Level Token を作成し、下記の scope を追加してから Socket Mode を有効にしてください。

   • connections:write

     App Token が Socket Mode 接続を開けるようにします

     コピー
2. 02

   チャットとチャンネル状態のイベントを購読する

   Event Subscriptions → Subscribe to bot events を開いてください。下記の各イベントを追加してください。このセットは、Slack アダプタが実装するメッセージ、リアクション、チャンネル状態の機能に一致します。

   • app_mention

     チャンネルの @ メンションを受信します

     コピー
   • message.channels

     パブリックチャンネルのメッセージを受信します

     コピー
   • message.groups

     プライベートチャンネルのメッセージを受信します

     コピー
   • message.im

     ダイレクトメッセージを受信します

     コピー
   • message.mpim

     複数人ダイレクトメッセージを受信します

     コピー
   • reaction_added

     追加されたリアクションを受信します

     コピー
   • reaction_removed

     削除されたリアクションを受信します

     コピー
   • member_joined_channel

     チャンネルに参加したメンバーを同期します

     コピー
   • member_left_channel

     チャンネルを離れたメンバーを同期します

     コピー
   • channel_rename

     チャンネルの名称変更を同期します

     コピー
   • group_rename

     プライベートチャンネルの名称変更を同期します

     コピー
   • channel_deleted

     チャンネルの削除を同期します

     コピー
   • channel_archive

     チャンネルのアーカイブを同期します

     コピー
3. 03

   ダイレクトメッセージを有効にする

   App Home → Show Tabs を開いてください。Display Messages tab をオンにし、Allow users to send Slash commands and messages from the messages tab を選択してください。Messages タブだけでは表示領域が現れるだけで、ユーザーは Agent にダイレクトメッセージを送れません。

4. 04

   Slack ネイティブの対話性を有効にする

   Interactivity & Shortcuts を開き、Interactivity を有効にしてください。Socket Mode は既存の WebSocket 経由で Block Kit のボタンアクションを配信するため、公開の Request URL は不要です。

5. 05

   完全なチャット scope を付与してアプリをインストールする

   OAuth & Permissions → Bot Token Scopes で、下記の各 scope を追加してください。このセットは Ankole が呼び出す Slack API のみをカバーします。未使用の assistant、workflow、document、meeting の scope は付与しないでください。

   • app_mentions:read

     bot に言及したメッセージを読み取ります

     コピー
   • channels:read

     パブリックチャンネルとそのメンバーを同期します

     コピー
   • channels:history

     パブリックチャンネルのメッセージを読み取り、返信を調整します

     コピー
   • groups:read

     プライベートチャンネルとそのメンバーを同期します

     コピー
   • groups:history

     プライベートチャンネルのメッセージを読み取り、返信を調整します

     コピー
   • im:read

     ダイレクトメッセージの会話を同期します

     コピー
   • im:history

     ダイレクトメッセージを読み取り、返信を調整します

     コピー
   • mpim:read

     複数人ダイレクトメッセージとそのメンバーを同期します

     コピー
   • mpim:history

     複数人ダイレクトメッセージを読み取り、返信を調整します

     コピー
   • chat:write

     bot メッセージを送信、更新、削除します

     コピー
   • reactions:read

     リアクションの変更を受信します

     コピー
   • reactions:write

     リアクションを追加および削除します

     コピー
   • files:read

     メッセージに添付されたファイルを読み取ります

     コピー
   • files:write

     Agent が送信するファイルをアップロードします

     コピー
   • users:read

     チャンネルメンバーを特定し、bot アカウントを除外します

     コピー

   scope を変更した後は、アプリをワークスペースに再インストールし、新しい Bot Token を Ankole に書き込んでください。

6. 06

   Console のフィールドを収集する

   botToken

   xoxb-…

   Bot User OAuth Token。xoxb- プレフィックスが必要です。

   appToken

   xapp-…

   Socket Mode 用の App-Level Token。xapp- プレフィックスが必要です。