カスタムツールと関数呼び出し

カスタムツール(関数とも呼びます)を使うと、AIがチャットの途中で小さな処理を実行できます。処理の内容は、決まった文章を返す、Webアドレスを呼び出す、サーバー上で短いスクリプトを動かす、のいずれかです。AIに推測させるのではなく、何かを調べさせたり計算させたりしたいときに使います。

関数呼び出しとは、AIがアプリに処理の実行を頼み、その結果を返信に使う仕組みです。Marinaraには、ダイスロール、ロアブック検索、ゲーム状態の更新といった組み込みツールが最初から入っています。カスタムツールは、これらと並んで動きます。カスタムツールはキャラクターカードには紐づきません。チャットでオンにするか、エージェント(チャットと並行して動く補助役)に紐づけて使います。

Note: ツールには、ツールに対応した接続が必要です。ClaudeとGrokのサブスクリプションの接続はツール定義を無視するため、Chat Settings(チャット設定)には案内が表示され、それらの接続ではツールの操作が無効になります。テキストコマンドとダイスタグは引き続き使えます。

ツールを作る

始める前に、上部バーからPresets(プリセット)パネルを開いてください。ツールは、そのFunctions(関数)セクション(レンチのアイコン)にあります。別のデバイスからMarinaraを開いている場合は、先にSettings → Advanced → Admin Access(設定 → 詳細設定 → 管理者アクセス)で管理者用のシークレットを保存してください。この値はサーバーのADMIN_SECRETと一致している必要があります。サーバー設定リファレンスを参照してください。

最初に試すなら、Static Resultを選んでください。ほかには何も必要ありません。

ツールの作成

  1. Presetsを開き、Functionsを探します。
  2. Create function(関数の作成、プラスのアイコン)をクリックします。空のツールエディターが開きます。
  3. check_weatherのように、小文字のsnake_caseで名前を入力します。これは、AIがツールを呼び出すときにそのまま使う名前です。名前は小文字で始まり、以降は小文字、数字、アンダースコアを使います。
  4. Description(説明)を入力します。AIはこの文章を読んで、いつツールを呼ぶかを判断するため、AIへの指示として書いてください。例: Get the current weather for a city the user names.
  5. ツールに必要なパラメーターを追加します(パラメーターの追加を参照)。
  6. Execution Type(実行タイプ)を選びます。Static Result、Webhook、Scriptのいずれかです。
  7. そのタイプの欄を入力します(実行タイプの選択を参照)。
  8. Save(保存)をクリックします。ボタンの近くに緑色のSavedが一瞬表示されます。

名前と説明の決まりは次のとおりです。

Functionsの見出しには、3つのアイコンボタンがあります。

一覧の各ツールには、次のものが表示されます。

ハンドルをつかんでドラッグすると、一覧の並び順を変えられます。並び順は表示上のものだけです。ツールが1つもないときは、一覧にNo functions yetと表示されます。

パラメーターの追加

パラメーターは、AIがツールを呼び出すときに送る入力値です。パラメーターごとに、名前、型、必須かどうか、説明があります。

  1. Parameters(パラメーター)グループでAdd Parameter(パラメーターの追加)をクリックします。
  2. cityのように名前を入力します。
  3. 型をstring、number、boolean、array、objectから選びます。
  4. AIが必ずこの値を送る必要がある場合は、Required(必須)をオンにします。
  5. The city name to look up, such as Tokyo.のように、その値が何を意味するのかをAIに伝える説明を書きます。

Add Parameterで行を増やすか、行のマイナスボタンで行を削除します。名前が空の行は、保存時に削除されます。

インポートしたツールをAIがまったく呼ばないように見える場合は、パラメーターが不正なのかもしれません。その場合、アプリは何も知らせずにそのツールを飛ばします。パラメーターを削除し、手作業で追加し直してください。

実行タイプの選択

Static Result

Static Resultツールは、毎回同じ文章を返します。外部サービスは不要です。カードにはReturns a fixed string when called.と表示されます。

欄はStatic Resultの1つだけで、複数行の入力欄です。空のままにすると、ツールはOKを返します。

例: パラメーターなしのstore_hoursという名前のツールで、Static Resultに次の文章を入れます。

We are open Monday to Friday, 9am to 5pm. We are closed on weekends.

AIはstore_hoursを呼び出すと、ツール名と送った引数とともにこの文章を受け取り、営業時間をユーザーに伝えられます。

Webhook

Webhookツールは、呼び出しをWebアドレスへ送り、そのサービスからの応答をAIに返します。Webhookとは、データを受け取ってデータを返すアドレスのことです。カードにはSends a POST request to an external URL.と表示されます。

欄はWebhook URLの1つだけです。アプリはPOSTリクエストを送ります。POSTリクエストとは、Webサービスにデータを送る方法の1つです。本文は、構造化データを表すプレーンテキスト形式のJSONで、次のような形になります。

{ "tool": "your_tool_name", "arguments": { ... } }

Include hidden chat context(隠しチャットコンテキストを含める)をオンにすると、本文にはcontextの値も入ります。サービスはJSONまたはプレーンテキストで応答し、その応答がAIに返ります。

例: cityという必須のstring型パラメーターを1つ持つcheck_weatherという名前のツールで、Webhook URLに次のアドレスを設定します。

https://api.example.com/weather

AIがcityにTokyoを入れて呼び出すと、サービスが天気を調べて応答し、AIはその応答をメッセージに使います。

制限は次のとおりです。

うまくいかなかった場合: アドレスがhttps://で始まり、接続できる状態か確認してください。ローカルアドレスは、管理者が許可しない限り遮断されたままです。応答の遅いサービスは、60秒の制限時間に達することがあります。

Script

Scriptツールは、サーバー上で短いJavaScriptを実行し、その結果を返します。JavaScriptは広く使われているプログラミング言語です。カードにはRuns a JavaScript expression server-side.と表示されます。

スクリプトツールはデフォルトでオフです。サーバーでオンにしていない場合、Scriptのカードはグレー表示になり、琥珀色のScript disabledラベルが表示されます。オンにするには、サーバー管理者がサーバーの.envファイルに次の行を加え、Marinaraを再起動します。

CUSTOM_TOOL_SCRIPT_ENABLED=true

欄はScript Bodyの1つだけです。スクリプトはargs(AIが送った値)を読み取り、結果を必ずreturnします。JSON、Math、Dateを使えます。

例: xとyという必須のnumber型パラメーターを2つ持つadd_numbersという名前のツールで、Script Bodyに次のように入力します。

const result = args.x + args.y;
return { sum: result };

AIがxに2、yに3を入れて呼び出すと、ツールは合計の5を返します。スクリプトがエラーを投げた場合、AIにはエラーの結果が返ります。

スクリプトは、サーバー上で実際のコードを実行します。実行はサンドボックス(コードにできることを制限する隔離された領域)の中で行われます。

サンドボックスは、オペレーティングシステムレベルの完全な隔離ではありません。ツールを作成できる人であれば、CPUやメモリーを浪費するスクリプトを書くことはできます。スクリプトツールをオンにするのは信頼できるサーバーだけにし、他の人が書いたスクリプトには注意してください。

うまくいかなかった場合: Scriptのカードがグレー表示になっているときは、管理者にCUSTOM_TOOL_SCRIPT_ENABLED=trueを設定して再起動するよう依頼してください。

隠しチャットコンテキストを含める

WebhookツールとScriptツールは、AIにはツールの入力値として見えない、追加のチャットデータを受け取れます。ツールエディターでInclude hidden chat context(隠しチャットコンテキストを含める)をオンにしてください(デフォルトはオフです)。すると、ツールはcontextの値を受け取ります。そこには次のものが入ることがあります。

これで、AIがすべてのデータを渡さなくても、ツール側で結果を状況に合わせられます。

チャットでツールをオンにする

ツールを作っただけでは、AIはそれを使いません。チャットでもツールの使用をオンにします。

  1. チャットを開き、Chat Settings(チャット設定)を開きます。
  2. Function Calling(関数呼び出し)セクション(レンチのアイコン)を開きます。
  3. Enable Tool Use(ツールの使用を有効にする)をオンにします。説明にはAllow AI to call functions (dice rolls, game state, etc.)と表示されます。新しいチャットではデフォルトでオフです。
  4. 動作を確認します。store_hoursの例なら「営業時間は?」のように、ツールが答えられることをAIに尋ねます。返信にはツールの文章が使われるはずです。

Enable Tool Useがオンで、その下に何も追加していない場合、そのチャットは、対応している全体で有効なツールをすべて使えます。組み込みツールと、Functionsでスイッチがオンになっている各カスタムツールです。Gameチャットでsearch_lorebookを使うには、Let the GM search lore(GMによるロア検索を許可)も必要です。

チャットで使うツールを限定するには、次の手順に従います。

  1. Add Functions(関数の追加)をクリックします。検索欄の付いた選択画面が開きます。検索欄が照合するのはツール名だけです。
  2. 使いたいツールにチェックを入れます。一覧には組み込みツールとカスタムツールが混在しています。
  3. Add Selected(選択したものを追加)をクリックします。

ツールを1つでも追加すると、そのチャットでは追加したツールだけが動きます。選択画面のNew Custom Function(新しいカスタム関数)をクリックすると、ツールエディターへ移動します。

Gameチャットでは、ツール計画用に別の接続を使えます。費用と動作については、任意のツール計画とロア検索を参照してください。

うまくいかなかった場合: Enable Tool Useがオンになっていること、特定のツールを追加した場合はそのツールがチャットの一覧に入っていること、Functionsでそのツールのスイッチがオンになっていることを確認してください。Descriptionとパラメーターの説明をより明確に書くと、AIがいつツールを呼ぶかを判断しやすくなります。

エージェントにツールを紐づける

ツールはチャットではなく、エージェントに持たせることもできます。

  1. Agents(エージェント)パネルを開き、エージェントを1つ開きます。
  2. そのTools / Function Callingグループを開きます。
  3. そのエージェントが使ってよいツールをオンにします。

この場合も、チャットのFunction Calling(関数呼び出し)セクションでEnable Tool Use(ツールの使用を有効にする)をオンにする必要があります。エージェントエディターの下部にも、そのことが書かれています。エージェント全般については、カスタムエージェントの作成を参照してください。

ツールのエクスポートとインポート

インポートしたWebhookツールとScriptツールは、ファイル側でどちらかを求めていても、常にオフの状態で、Include hidden chat context(隠しチャットコンテキストを含める)もオフにして保存されます。そのうえでMarinaraは、種類、Webhookのアドレス、ファイルが求めた権限を表示します。インポートしたツールを1つずつ開いて内容を確認し、信頼できる場合にだけオンにしてください。Staticツールは、インポート元のオン/オフの状態を引き継ぎます。

既存のツールや組み込みツールと名前が重なるツールは、インポート時に飛ばされます。エージェントのパッケージにカスタムツールは含まれません。カスタムツールは別途エクスポートして確認し、エージェントをインポートした後で紐づけてください。

関連ガイド