AIボット - カスタムツール

ドキュメント サイト管理
, ,
1

:bookmark: このガイドでは、Discourse AI プラグイン内でカスタム AI ツールを作成、設定、統合して、管理者がユーザー定義の JavaScript 関数でボットの機能を拡張する方法について説明します。

:person_raising_hand: 必要なユーザーレベル: 管理者

ツールとは、AI ボットが単なるテキストベースの応答以外に特定のタスクを実行したり、情報を取得したりするために使用できるプログラム可能な機能です。これらのツールは、ボットが外部 API と対話し、データを操作したり、追加の関数を実行したりして、その機能を拡張できるようにするスクリプトまたは統合です。

要約

このドキュメントでは、以下の内容を扱います。

  • 新しいカスタム AI ツールの作成
  • ツールパラメーターとスクリプトの設定
  • ツールスクリプトで利用可能な API
  • カスタムツールと AI ペルソナの統合
  • カスタムツールのテストとトラブルシューティング

新しいカスタム AI ツールの作成

新しい AI ツールを作成するには:

  1. 管理パネル > プラグイン > Discourse AI > ツールに移動します
  2. 「新しいツール」をクリックします (既存のプリセットを使用してオプションについて学習することもできます)
  3. 次のフィールドに入力します。
    • 名前: LLM に提示されるツールの名前
    • 説明: LLM に提示されるツールの説明
    • サマリー: ユーザーを支援するためにツールが何をするかの要約 (詳細に表示されます)
    • パラメータ: LLM に提示されるツールが必要とする入力を定義します
    • スクリプト: ツールを動作させる JavaScript コード
  4. 「保存」をクリックします

New AI Tool Interface
New AI Tool Interface924×296 15.7 KB

This image shows a user interface window with various options, including a selected preset titled "Stock quote (AlphaVantage)" and other tools like browsing the web using jina.ai, exchange rate, and starting from a blank state. (Captioned by AI)
This image shows a user interface window with various options, including a selected preset titled "Stock quote (AlphaVantage)" and other tools like browsing the web using jina.ai, exchange rate, and starting from a blank state. (Captioned by AI)490×404 24.5 KB

The image shows a script interface titled "stock_quote" that retrieves real-time stock quote information using the AlphaVantage API, with parameters for entering a stock symbol and displaying the code for making the API call and handling the response data. (Captioned by AI)
The image shows a script interface titled "stock_quote" that retrieves real-time stock quote information using the AlphaVantage API, with parameters for entering a stock symbol and displaying the code for making the API call and handling the response data. (Captioned by AI)826×1326 122 KB

ツールスクリプトの設定

利用可能な API

ツールスクリプトからは、次の API にアクセスできます。

  1. 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 } を返します。

  2. 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 が含まれます。

  3. カスタムアップロード統合 (RAG)

    index.search(query, { filenames: ["file.pdf"], limit: 10 })

    このツールに関連付けられているインデックス化された RAG ドキュメントフラグメントを検索します。関連性の順に並べられた Array<{ fragment: string, metadata: string | null }> を返します。デフォルトの制限は 10、最大は 200 です。

    index.getFile(filename)

    アップロードされた RAG ファイルの正確なファイル名を使用して、その全文を取得します。完全なテキスト、またはファイルが見つからない場合は null を返します。

  4. アップロードサポート

    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)。

  5. 実行チェーン制御

    chain.setCustomRaw(raw)

    ボットの投稿の最終的な生の内容を設定し、ツール実行チェーンを停止します。完全な応答を直接生成するツール (例: 画像生成ツール) に役立ちます。

  6. シークレット管理

    secrets.get(alias)

    指定されたエイリアスにバインドされている資格情報値を返します。エイリアスは、ツールのシークレット契約設定で定義され、管理パネルの AI シークレットにバインドされます。エイリアスが宣言されていない、バインドされていない、または資格情報が存在しない場合、エラーがスローされます。

    const apiKey = secrets.get("my_api_key");

  7. 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) // 投稿/トピック/ユーザーのカスタムフィールドの設定

  8. コンテキストオブジェクト

    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 に提供される結果が期待どおりであることを確認するために、ビルドしたすべてのツールをテストする必要があります。

Testing Interface
Testing Interface761×566 36.1 KB

AI ペルソナとのツールの統合

カスタムツールを AI ペルソナに追加するには:

  1. 管理パネル > プラグイン > Discourse AI > ペルソナに移動します
  2. 既存のペルソナを編集するか、新しいペルソナを作成します
  3. 「ツール」セクションで、カスタムツールが組み込みツールと並んで一覧表示されます
  4. カスタムツールを選択して、ペルソナに追加します

This image shows a list of enabled tools or plugins in an interface, including options like JavaScript Evaluator, GitHub Search Code, Tags, Image, Dall-E, Google, and a custom tool named "Stock_quote". (Captioned by AI)
This image shows a list of enabled tools or plugins in an interface, including options like JavaScript Evaluator, GitHub Search Code, Tags, Image, Dall-E, Google, and a custom tool named "Stock_quote". (Captioned by AI)650×464 23 KB

動作中のカスタムツール

カスタムツールを LLM に提供すると、会話を強化するためにそれを使用できます。

image
image936×1194 86.7 KB

トラブルシューティング

ツールが期待どおりに動作しない場合は、次の手順を実行してください。

  1. テストインターフェイスを使用して、入力に対して意図したとおりに動作するかどうかを確認します。
  2. グループが ai_bot_debugging_allowed_groups に含まれていることを確認します。このグループのメンバーはボットのトランスクリプトに完全にアクセスでき、そこで AI ログを表示できます。
  3. 予期しない動作が発生する場合は、https://SITENAME/logs にアクセスしてエラーを確認してください。

追加リソース

Discourse AI - AI bot

AI bot - Agents

「いいね！」 14
Weekly Summary of AI topics
A Plug-In to convert Discourse Forum Discussions into Clear Proposal Revisions with Community-Sourced Justifications
Error in any AI Tool with no parameters, e.g. "tags"
Error in any AI Tool with no parameters, e.g. "tags"
Experiments with AI based moderation on Discourse Meta
AI bot - Agents
Managing AI credentials
Provide topic count via Discourse AI tool API `discourse.getUser` function
Discourse AI - AI triage using Agent
Is it possible to have a multi-line/longer text field in the signup form?
AI Bot – Bring Your Own MCP Server
4

Discourse の AI ペルソナ向けのツール構築を始めたばかりです。これは、非常に多くの有用で公開されている API があるため、非常に役立つように思えます！

例えば、以下のような結果が得られています。

ポーカー戦略を通じた意思決定の理解 AI

maiki:

ゼルダの伝説 ブレス オブ ザ ワイルドのインフォカードを作成してください。

gpt-4o:

「ゼルダの伝説 ブレス オブ ザ ワイルド」の情報カードを以下に示します。

タイトル: ゼルダの伝説 ブレス オブ ザ ワイルド
開発: 任天堂
発売: 任天堂
発売日: 2017年3月3日
プラットフォーム: Nintendo Switch、Wii U
ジャンル: アクションアドベンチャー
モード: シングルプレイヤー

あらすじ:
広大なオープンワールドを舞台に、プレイヤーは深い眠りから目覚めたリンクを操作し、厄災ガノンを倒してハイラル王国を救います。没入感のある環境、プレイヤーが世界やそのシステムを自由に探索・操作できる点が賞賛されています。

受賞歴:
革新的なデザイン、広大な世界、魅力的なゲームプレイにより、数々の年間ゲーム大賞を含む多くの賞を受賞しています。

詳細情報: Wikidata エントリ

「ブレス オブ ザ ワイルド」は、オープンワールドゲームの再定義と、探索と発見を促す魅力的な体験を提供することで知られています。

maiki:

あつまれ どうぶつの森についても同様にお願いします。

gpt-4o:

「あつまれ どうぶつの森」の情報カードを以下に示します。

タイトル: あつまれ どうぶつの森
開発: 任天堂
発売: 任天堂
発売日: 2020年3月20日
プラットフォーム: Nintendo Switch
ジャンル: ソーシャルシミュレーション
モード: シングルプレイヤー、マルチプレイヤー

あらすじ:
この魅力的なソーシャルシミュレーションゲームでは、プレイヤーはたぬきちからパッケージを購入した後、無人島に移住するカスタマイズ可能なキャラクターを演じます。リアルタイムの探索、資源収集、クラフト、カスタマイズが可能で、コミュニティ的でリラックスできるゲーム体験を促進します。

受賞歴:
創造的な自由度と発売時期が評価され、年間ゲーム大賞や、世界的なパンデミック中のソーシャルゲームへの貢献で賞を受賞しました。

詳細情報: Wikidata エントリ

「あつまれ どうぶつの森」は、困難な時期における魅力的なソーシャル機能とストレス解消ゲームプレイで称賛され、文化的な現象となりました。

maiki:

シカゴから遠く離れて

gpt-4o:

「シカゴから遠く離れて」という本の情報カードを以下に示します。

タイトル: シカゴから遠く離れて
著者: リチャード・ペック
出版年: 1998年
ジャンル: 歴史フィクション、ヤングアダルト
ISBN: 978-0141303529

あらすじ:
ニューベリー名誉賞を受賞したこの小説は、1920年代後半から1930年代にかけて、シカゴからイリノイ州の田舎町へ、ジョーイと妹のメアリー・アリスが風変わりな祖母ドデルのもとへ毎年夏に旅行する様子を描いた短編小説集です。各章には、大恐慌を背景に人生の教訓を伝える、面白くて感動的なエピソードが含まれています。

受賞歴:
1999年にニューベリー名誉賞を受賞し、ユーモア、深み、20世紀初頭のアメリカ田舎の描写で称賛されています。

詳細情報: Wikidata エントリ

この本は、家族の絆とシンプルな時代の本質を捉えた、ノスタルジックで心温まる物語として高く評価されています。

maiki:

ベットで考える

gpt-4o:

以前、「ベットで考える」の Wikidata エントリを見つけましたが、現時点では Wikidata から直接詳細情報を取得できません。しかし、利用可能な情報に基づいた簡単なカードを以下に示します。

タイトル: ベットで考える：すべての情報がない場合に賢い意思決定を下す方法
著者: アニー・デューク
出版年: 2018年
ジャンル: ノンフィクション、意思決定、心理学
ISBN: 978-0735216358

あらすじ:
この本は、ポーカーからの洞察を活用して、不確実性下での意思決定を理解するのに役立ちます。プロのポーカープレイヤーおよび認知心理学者としての経験を融合させたアニー・デュークは、より賢明な意思決定を行い、結果を評価し、確率的思考を採用するためのフレームワークを提供します。

詳細情報: Wikidata エントリ

詳細については、書籍の出版に関する追加のリソースやデータベースを確認することをお勧めします。

それは問題ありませんが、この説明に気づきました…

…そして疑問に思いました。効率的な使用のために、これらのツールに直接言及してプロンプトを作成すべきでしょうか？

私のプロンプト作成の一般的なアプローチは、時間をかけて洗練し、AIツーリングに採用させたい行動パターンに焦点を当てることです。しかし、例えば、いつ Wikidata エンティティを検索するか、いつ特定のエンティティのすべてのクレームをリストするか（2つの異なる API）など、具体的な指示を追加できるのであれば、ワークフロー全体を意図したとおりに流れるように洗練できると感じています… :star_struck:

「いいね！」 4
5

Indeed clearly explaining the tool and providing examples in the system prompt is beneficial.

「いいね！」 2
6

カスタムツールでAPIキーとOpenAIプロジェクトを管理設定から挿入することは可能ですか？

「いいね！」 1
7

カスタムツールからREST呼び出しを行い、すべてのヘッダーを指定できます。

「いいね！」 2
8

今気づいたよ、笑…　ぼんやりしててごめん

「いいね！」 1
9

ドキュメントをペルソナにアップロードし、埋め込みを生成して、それらに対してセマンティック検索を実行できるようになりました。しかし、場合によってはセマンティック検索が理想的ではないため、ハイブリッド検索で強化したいと考えています。つまり、既存のものを維持し、キーワード検索を追加したいのです。現時点では、それを実行するにはカスタムツールを作成する必要がありますよね？

ドキュメントをトピックとして公開すれば、ネイティブのDiscourse検索でそのまま機能することはわかっていますが、現在はそれが選択肢ではありません。

10

カスタムツールに配列パラメーターを追加しようとすると、ツールスキーマエラーが発生します。会話開始時のエラーは次のとおりです。

{
“error”: {
“code”: 400,
“message”: “* GenerateContentRequest.tools[0].function_declarations[3].parameters.properties[properties].items: missing field.\\n”,
“status”: “INVALID_ARGUMENT”
}
}

試したこと：

  • properties という名前で型が array のパラメーターを持つカスタムツールを作成しました。
  • パラメーターリストの UI では items を指定できません。
  • properties に対して items: { type: “string” } を含む完全なツール JSON をエクスポート/インポートしました。
  • インポート後、ツールがペルソナに対して有効になるとすぐにエラーが持続します。ツールを削除すると、ボットは動作します。

期待される動作：

パラメーターリストの UI で配列のアイテム型を定義できるか、インポートが items を尊重してスキーマが検証される必要があります。

誰かこれを見たことがありますか？配列パラメーターを定義するための既知の制限事項や必要な UI パスはありますか？

「いいね！」 1