Lark
前提条件
1. Larkオープンプラットフォームの設定
-
Larkオープンプラットフォームにアクセスします
-
企業自社開発アプリを作成します（または既存のアプリを使用します）
-
アプリの認証情報を取得します：
- APP ID
- APP Secret
2. ボットの設定
- Larkオープンプラットフォーム → アプリ機能を追加 → 機能別に追加 → ボットを追加
3. リダイレクトURLの設定
- Larkオープンプラットフォーム → セキュリティ設定 → リダイレクトURL → 追加
http://your-domain/agent/api/lark-oauth/callback
ローカルでテストする場合、リダイレクトURLは次のとおりです：http://localhost:3000/api/lark-oauth/callback
4. イベントとコールバック
- サブスクリプション方式：Lark Developer Consoleの「Events & Callbacks」で、イベントとコールバックのどちらもロングコネクションでの受信を選択します。公開ネットワークのCallback URLを入力する必要はありません。イベント設定には
im.message.receive_v1を追加し、コールバック設定にはcard.action.triggerを追加します。これはAskUserQuestionフォームの送信、無視、続行に使用します。アプリの権限には、im:resource（ユーザーの画像/ファイルのダウンロードと生成ファイルのアップロード）とcardkit:card:write（インタラクティブカードの作成、ストリーミング更新、置き換え）を必ず含めてください。im:resourceがない場合、テキストメッセージは正常に処理されることがありますが、画像の読み取りと生成ファイルの送信は失敗します。権限、イベント、コールバックを変更した後は、必ず新しいバージョンを作成して公開し、アプリがターゲットユーザーに利用可能になっていることを確認してください。
5. アプリの権限設定
- Larkオープンプラットフォーム → 権限管理 → 「権限を有効化」をクリック → 「アプリアイデンティティの権限」で次の権限を有効にします：
| im:message | シングルチャットとグループのメッセージの取得と送信 |
|---|---|
| im:message.group_at_msg.include_bot:readonly | グループ内で他のボットやユーザーが現在のボットを@メンションしたメッセージの取得 |
| im:message.group_at_msg:readonly | グループ内でユーザーがボットを@メンションしたメッセージの取得 |
| im:message.group_msg | グループ内のすべてのメッセージの取得 |
| im:message.p2p_msg:readonly | ユーザーがボットに送信したシングルチャットメッセージの読み取り |
| im:message:readonly | シングルチャットとグループのメッセージの取得 |
| im:message:send_as_bot | アプリとしてメッセージを送信 |
| im:resource | 画像またはファイルリソースの取得とアップロード |
| cardkit:card:write | カードの作成と更新 |
グループチャットのメッセージ振り分けのために追加を推奨する権限：tenant:tenant:readonly（Read tenant information）。この権限があると、システム管理でチャネルを検証した直後にテナントを識別し、チャットスペースを表示できます。この権限がなくても認証情報の検証やメッセージの送受信には影響しませんが、チャットスペースは、対象グループでBotを@メンションしたメッセージが初めて届いた後に検出されます。権限を追加したら、アプリのバージョンを再度公開し、チャンネル管理で「再検証」をクリックしてください。
- 「ユーザーアイデンティティの権限」で次の権限を有効にします：
- contact:user.base:readonly（ユーザーの基本情報の取得）
- 「権限の有効化を確認」をクリックします
6. アプリを公開する
- Larkオープンプラットフォーム → バージョン管理とリリース → アプリの表示範囲を設定してアプリを公開します
Agentの設定
システム管理で設定します：
-
システムにログインし、「システム管理」→「エージェント 管理者」→「チャンネル管理」に進みます
-
「新規チャンネル」をクリックし、「Lark」タイプを選択します
-
設定情報を入力します：
- チャンネル名：任意の名前（例：Larkボット）
- APP ID、APP Secret
-
「保存」をクリックします
-
チャネルを有効にします（「有効」スイッチがオンになっていることを確認します）
注意：
- 設定情報はデータベースに暗号化して保存されるため、安全性が高まります
- アプリの起動時に、有効なすべてのLarkチャネルに自動的に接続します（WebSocketのロングコネクション経由）
- 設定を変更した後、サービスを再起動する必要はなく、すぐに反映されます
使い方の流れ
ユーザーの連携手順
- ユーザーがシステムにログインします
- 左下のユーザーアバターをクリックしてメニューを開きます
- 「チャネル連携」を選択し、「Lark」の下で連携するチャネルインスタンスを見つけて、「連携」ボタンをクリックします
- Larkの認証ページに移動します
- ユーザーが認証を確認します
- 自動的にシステムに戻り、「連携完了」ページが表示されます
- 認証ウィンドウを閉じて元のページを更新すると、メニューに「連携済み」ステータスが表示されます
ユーザーの連携解除手順
- 左下のユーザーアバターをクリックしてメニューを開きます
- 「チャネル連携」を選択し、「Lark」の下で連携済みのチャネルインスタンスを見つけて、「連携解除」ボタンをクリックします
- 連携解除の操作を確認します
- 連携が解除され、メニューに「未連携」ステータスが表示されます
使用マニュアル
カスタムコマンド
Larkボットは次のコマンドに対応しています（すべてのコマンドは/で始まります）：
| コマンド | 説明 | 例 |
|---|---|---|
| /new | 新しい会話を開始し、現在の会話履歴をクリアする | /newを送信 |
| /agent <名前> <メッセージ> | 指定した名前のAgentにメッセージを送信 | /agent rhea こんにちは |
| /agent <メッセージ> | システムのデフォルトAgentにメッセージを送信 | /agent こんにちは |
補足：
/で始まらないメッセージは、システムのデフォルトAgentに直接送信されます- Agent名は、ユーザーがアクセス権限を持つAgentである必要があります
- コマンドの引数は大文字と小文字が区別されます
グループチャットのメッセージ振り分け
グループチャットのメッセージ振り分けを使用すると、同じLark Botがルールに従って、さまざまな質問をそれぞれ異なるAgentまたはTeamに渡すことができます。1つの「チャットスペース」は現在のLarkテナントに対応し、設定はそのテナント内でこのBotを使用しているグループチャットに適用されます。Agentic Engineアカウントを連携済みで、グループ内でBotを明示的に@メンションしたメンバーのみがタスクを開始できます。
管理者による設定
- チャネルが有効になっていること、アプリが公開されていること、
im.message.receive_v1とcard.action.triggerをサブスクライブしていることを確認します。tenant:tenant:readonlyの追加を推奨します。追加すると、チャネルの検証時にシステムがテナントを識別できます。追加していない場合は、まず対象グループでBotを@メンションしてメッセージを1件送信しないと、システムがそのチャットスペースを検出できません。 - 「システム管理 → エージェント 管理者 → チャンネル管理」に進み、対象のLarkチャネルで「メッセージ振り分け」を開きます。チャットスペースが複数ある場合は、まず設定するスペースを選択します。
- 「既定の Agent/Team」を選択します。グループチャット振り分けを有効にする前に、既定の対象を設定する必要があります。通常のメッセージが他のルールに一致しない場合は、この対象が処理します。
- 必要に応じて最大19件のルールを追加します。各ルールでAgent/Teamを1つ選択し、必須の「呼び出しコマンド」を入力します。キーワードも最大10個まで入力できます。その後、そのルールの有効化スイッチをオンにします。
- 保存後、グループで
@Bot /helpを送信して動作を確認し、一覧に現在のユーザーが使用でき、かつ現在実行可能なAgent/Teamのみが表示されることを確認します。
| 構成項目 | ルール |
|---|---|
| 既定の Agent/Team | 設定しないと有効にできません。呼び出しコマンドが指定されておらず、キーワードにも一致しない場合に使用されます。 |
| 呼び出しコマンド | 必須、1～32文字。英字、数字、-、_ を使用できます。システムの予約コマンドは使用できません。大文字・小文字や全角・半角の違いは、別のコマンドとして扱われません。 |
| キーワード | 入力は任意です。各ルール最大10個、1個あたり2～32文字。複数のキーワードが同時に一致した場合は、長いキーワードが優先されます。同じ長さのルールで一意に判断できない場合は、既定の Agent/Team に戻ります。 |
| 選択可能な範囲 | 有効かつ実行可能なシステム/企業Agent、および現在の企業のTeamを選択できます。個人Agentはグループチャット振り分けの候補に表示されません。 |
グループチャットでの使い方
| 用途 | 例 | 説明 |
|---|---|---|
| 利用可能な機能を確認 | @Bot /help@Bot 能力清单 | 既定の対象、呼び出しコマンド、キーワードを一覧表示します。権限がない機能や現在実行できない機能は表示されません。 |
| Agent/Teamを指定 | @Bot /analysis 分析本周数据 | analysisは管理者が設定した呼び出しコマンドです。@Bot @analysis 分析本周数据と送信することもできます。 |
| キーワードで振り分け | @Bot 帮我检查埋点方案 | 本文があるルールのキーワードに一致した場合は、対応するAgent/Teamに渡します。一致しない場合は既定の対象を使用します。 |
| タスクを取消 | @Bot /cancel | メッセージ全体をこのとおり正確に送信する必要があります。タスクがすでに出力した本文は残り、取消の確認メッセージが別途届きます。 |
| 旧形式との互換 | @Bot /agent analysis 分析本周数据 | 引き続き使用できますが、新しいドキュメントでは/analysisを直接使用することを推奨します。 |
コマンドの範囲：グループチャット振り分けでは/newは使用できません。プライベートチャットでは引き続き/new、/agent、/cancelを使用できます。グループチャットでの通常の新規タスクは、まずBotを@メンションする必要があります。既存のタスクが回答を待っている場合に限り、Botの案内に従って元のスレッドまたはインタラクティブカードで返信を続けることができます。
公開コンテキストと個人データ：システムが参考にするのは、最近Botを明示的に@メンションし、実際に処理されたグループチャットの公開ターンのみです。Botを@メンションしていない通常のグループメッセージ、他のグループ、プライベートチャット、ユーザーメモリが混ざることはありません。履歴の内容は信頼できない参考情報としてのみ扱われ、現在のメッセージがこのターンの指示となります。
トラブルシューティング
1. コールバックURLのエラー
エラーメッセージ：リダイレクトURLが正しくありません。アプリの管理者に連絡してください。
解決方法：
- Larkオープンプラットフォームで設定したコールバックURLが正しいか確認します
- プロトコル、ドメイン、ポート、パスが完全に一致していることを確認します
- ローカル開発ではポート番号に注意します（例：3000 vs 8686）
NEXT_PUBLIC_BASE_PATHを使用している場合は、コールバックURLにそのパスを含める必要があります
2. Feishuチャネルが未設定
エラーメッセージ：Lark チャネルが未設定か無効です
解決方法：
- 「システム管理」→「エージェント 管理者」→「チャンネル管理」に進み、Larkチャネルが存在するか確認します
- チャネルの「有効」スイッチがオンになっていることを確認します
- App IDとApp Secretが正しく入力されているか確認します
- アプリの種類が企業自社開発アプリであることを確認します
3. App Access Tokenが無効
エラーメッセージ：The app access token passed is invalid
解決方法：
- チャンネル管理の
App IDとApp Secretが正しいか確認します - アプリの種類（企業自社開発アプリ）を確認します
- アプリが有効になっているか確認します
4. 権限不足
エラーメッセージ：権限が不足しているか、権限の検証に失敗しました
解決方法：
- Larkオープンプラットフォームで必要な権限を申請します
- 管理者による権限の承認を待ちます
- 権限が有効になっていることを確認します
5. 連携の失敗
エラーメッセージ：この Lark アカウントは他ユーザーに紐付いています
解決方法：
- 1つのLarkアカウントは、1人のシステムユーザーにのみ連携できます
- 連携先を変更する場合は、先に元のアカウントで連携を解除します
関連ドキュメント
関連ページと次のステップ
- 他のプラットフォームの接続手順を確認する：チャンネル管理。
- チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
- 使用するAgentを設定する：Agent。
- プラットフォーム内での会話の使い方を確認する：会話。