このガイドでは、Discourse AI プラグイン内でカスタム AI ツールを作成、設定、統合して、管理者がユーザー定義の JavaScript 関数でボットの機能を拡張する方法について説明します。
必要なユーザーレベル: 管理者
ツールとは、AI ボットが単なるテキストベースの応答以外に特定のタスクを実行したり、情報を取得したりするために使用できるプログラム可能な機能です。これらのツールは、ボットが外部 API と対話し、データを操作したり、追加の関数を実行したりして、その機能を拡張できるようにするスクリプトまたは統合です。
要約
このドキュメントでは、以下の内容を扱います。
- 新しいカスタム AI ツールの作成
- ツールパラメーターとスクリプトの設定
- ツールスクリプトで利用可能な API
- カスタムツールと AI ペルソナの統合
- カスタムツールのテストとトラブルシューティング
新しいカスタム AI ツールの作成
新しい AI ツールを作成するには:
- 管理パネル > プラグイン > Discourse AI > ツールに移動します
- 「新しいツール」をクリックします (既存のプリセットを使用してオプションについて学習することもできます)
- 次のフィールドに入力します。
- 名前: LLM に提示されるツールの名前
- 説明: LLM に提示されるツールの説明
- サマリー: ユーザーを支援するためにツールが何をするかの要約 (詳細に表示されます)
- パラメータ: LLM に提示されるツールが必要とする入力を定義します
- スクリプト: ツールを動作させる JavaScript コード
- 「保存」をクリックします
ツールスクリプトの設定
利用可能な API
ツールスクリプトからは、次の API にアクセスできます。
HTTP リクエスト:
http.get(url, options) http.post(url, options) http.put(url, options) http.patch(url, options) http.delete(url, options)これらを使用して、外部サービスと対話します。
optionsを使用して、HTTP ヘッダーと本文を指定できます。http.get(url, { headers: { "Authorization": "Bearer key" } }) http.post(url, { headers: { "Content-Type": "application/json" }, body: { key: "value" } }) http.patch(url, { headers: { "Authorization": "Bearer key" }, body: "some body" }) http.delete(url, { headers: { "Authorization": "Bearer key" } }) http.put(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })すべての HTTP メソッドは
{ status: number, body: string }を返します。LLM (言語モデル) 統合:
llm.truncate(text, length)設定された LLM のトークナイザーに基づいて、テキストを指定されたトークン長に切り詰めます。
llm.generate(prompt, options)設定された LLM を使用してテキストを生成します。プロンプトは、単純な文字列または
{ messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }のような構造化オブジェクトにできます。オプションには、JSON 出力を要求して自動解析するためのjson: trueのほか、temperature、top_p、max_tokens、stop_sequencesが含まれます。カスタムアップロード統合 (RAG)
index.search(query, { filenames: ["file.pdf"], limit: 10 })このツールに関連付けられているインデックス化された RAG ドキュメントフラグメントを検索します。関連性の順に並べられた
Array<{ fragment: string, metadata: string | null }>を返します。デフォルトの制限は 10、最大は 200 です。index.getFile(filename)アップロードされた RAG ファイルの正確なファイル名を使用して、その全文を取得します。完全なテキスト、またはファイルが見つからない場合は
nullを返します。アップロードサポート
upload.create(filename, base_64_content)新しいアップロードを作成します。
{ id: number, url: string, short_url: string }を返します。upload.getUrl(shortUrl)ショート URL (例:
upload://12345) が与えられると、完全な CDN 対応 URL を返します。upload.getBase64(uploadIdOrShortUrl, maxPixels)既存のアップロードの base64 エンコードされたコンテンツを取得します。アップロード ID (数値) またはショート URL (文字列) を受け入れます。オプションの
maxPixelsパラメータは、画像の自動サイズ変更に使用されます (デフォルト: 10,000,000)。実行チェーン制御
chain.setCustomRaw(raw)ボットの投稿の最終的な生の内容を設定し、ツール実行チェーンを停止します。完全な応答を直接生成するツール (例: 画像生成ツール) に役立ちます。
シークレット管理
secrets.get(alias)指定されたエイリアスにバインドされている資格情報値を返します。エイリアスは、ツールのシークレット契約設定で定義され、管理パネルの AI シークレットにバインドされます。エイリアスが宣言されていない、バインドされていない、または資格情報が存在しない場合、エラーがスローされます。
const apiKey = secrets.get("my_api_key");Discourse 統合
ツールは Discourse データと直接対話できます。
discourse.baseUrl // サイトのベース URL discourse.search(params) // Discourse 検索の実行 discourse.getPost(post_id) // 投稿の詳細の取得 (生コンテンツを含む) discourse.getTopic(topic_id) // トピックの詳細の取得 (タグ、カテゴリなど) discourse.getUser(id_or_username) // ユーザー詳細の取得 discourse.createTopic(params) // 新しいトピックの作成 discourse.createPost(params) // 新しい投稿/返信の作成 discourse.editPost(post_id, raw, options) // 投稿コンテンツの編集 discourse.editTopic(topic_id, updates, options) // トピックプロパティの編集 (タグ、カテゴリ、可視性) discourse.createChatMessage(params) // チャットメッセージの送信 discourse.createStagedUser(params) // ステージングされたユーザーの作成 discourse.getAgent(name) // 他の AI エージェントの取得 (respondTo メソッド付き) discourse.updateAgent(name, updates) // AI エージェントの設定の更新 discourse.getCustomField(type, id, key) // 投稿/トピック/ユーザーのカスタムフィールドの読み取り discourse.setCustomField(type, id, key, value) // 投稿/トピック/ユーザーのカスタムフィールドの設定コンテキストオブジェクト
contextオブジェクトは、ツールが実行されている場所に関する情報を提供します。
- ボット会話コンテキスト:
context.post_id、context.topic_id、context.private_message、context.participants、context.username、context.user_id- チャットコンテキスト:
context.message_id、context.channel_id、context.username- 自動化コンテキスト:
context.post_id、context.topic_id、context.username、context.user_id、context.feature_name、context.feature_context- 共通プロパティ:
context.site_url、context.site_title、context.site_description必須関数
スクリプトは以下を実装する必要があります。
invoke(params): ツールが呼び出されたときに実行されるメイン関数オプションで以下を実装できます。
details(): ツールが実行されたことを説明する文字列 (基本的な HTML を含むことができます) を返し、チャットインターフェイスに表示されますcustomSystemMessage(): プロンプトの組み立て中 (ツールの呼び出し中ではありません) に呼び出されます。システムプロンプトに追加される文字列を返します。null/undefinedを返すとスキップされます。context、discourse、indexオブジェクトにアクセスできます。スクリプトの例:
function invoke(params) { let result = http.get("https://api.example.com/data?query=" + params.query); return JSON.parse(result.body); } function details() { return "Fetched data from Example API"; }制限事項とセキュリティ
- 実行タイムアウト: スクリプト処理時間のデフォルトタイムアウトは 2000ms です。タイマーは外部 HTTP リクエスト (
http.*) および LLM 呼び出し (llm.generate) 中に一時停止するため、スクリプト自体の処理時間のみがカウントされます。- メモリ: 最大 V8 ヒープ制限は 10MB
- HTTP リクエスト: ツール実行ごとに最大 20 リクエスト
- サンドボックス化された環境: スクリプトは、制限された V8 JavaScript 環境 (MiniRacer 経由) で実行されます。ブラウザのグローバルオブジェクト、ホストファイルシステム、またはサーバーサイドライブラリへのアクセスはありません。ネットワークリクエストは Discourse バックエンドを経由してプロキシされます。
ツールのテスト
LLM に提供される結果が期待どおりであることを確認するために、ビルドしたすべてのツールをテストする必要があります。
AI ペルソナとのツールの統合
カスタムツールを AI ペルソナに追加するには:
- 管理パネル > プラグイン > Discourse AI > ペルソナに移動します
- 既存のペルソナを編集するか、新しいペルソナを作成します
- 「ツール」セクションで、カスタムツールが組み込みツールと並んで一覧表示されます
- カスタムツールを選択して、ペルソナに追加します
動作中のカスタムツール
カスタムツールを LLM に提供すると、会話を強化するためにそれを使用できます。
トラブルシューティング
ツールが期待どおりに動作しない場合は、次の手順を実行してください。
- テストインターフェイスを使用して、入力に対して意図したとおりに動作するかどうかを確認します。
- グループが
ai_bot_debugging_allowed_groupsに含まれていることを確認します。このグループのメンバーはボットのトランスクリプトに完全にアクセスでき、そこで AI ログを表示できます。- 予期しない動作が発生する場合は、
https://SITENAME/logsにアクセスしてエラーを確認してください。追加リソース
「いいね！」 14