Custom SQL tools

SQLツールは、エージェントが名前で呼び出すことができる保存されたパラメーター化クエリです。これを使用して、Rustを書いたり、ネイティブAIDBファンクションを公開したりせずに、エージェントに独自のテーブルとビジネスロジックへのアクセスを許可します。

SELECT aidb.create_sql_tool(
    name             => orders_by_customer,
    description      => Look up recent orders for a customer by id.,
    sql_statement    => SELECT id, status, total FROM orders WHERE customer_id = ${customer_id} ORDER BY created_at DESC LIMIT ${limit},
    params           => aidb.tool_params(
        aidb.tool_param(customer_id, INT, The customers id.),
        aidb.tool_param(limit, INT, Maximum number of orders to return.)
    ),
    read_only        => true,  -- optional; enforced, not just descriptive (see below). Default: true
    return_type_hint => NULL   -- optional; documents the returned row shape, same aidb.tool_params() shape as `params`. Default: NULL
);

Parameter	Type	Default	Description
name	TEXT	Required	ツールの一意の名前。
description	TEXT	Required	ツール定義の一部としてモデルに表示されます。
sql_statement	TEXT	Required	実行するクエリー。宣言されたパラメーターごとに`${name}`プレースホルダーを使用します。
params	JSONB	Required	`aidb.tool_params()`で構築されたツールのパラメーター。
read_only	BOOLEAN	true	`true`の場合、読み取り専用であることが証明されていない限り、登録時にステートメントを拒否します。
return_type_hint	JSONB	NULL	クエリーの結果の形状を同じ`aidb.tool_params()`形状で文書化します。現在モデルには表面化されていません。

aidb.tool_param(name, type, description) は1つのパラメーターをビルドします。 aidb.tool_params(...) は、いくつかを組み合わせます。引数なしのaidb.tool_params() は、パラメーターをとらないツールを宣言します。

他の方法と同じようにエージェントにツールを登録します。

SELECT aidb.create_agent(sales_helper, Answer questions about customer orders., my_gpt,
    tools => ARRAY[orders_by_customer]);

ネーミング

ツールの名前は、すべてのツールタイプで一意である必要があります。ビルトイン Native tools または MCP tools から既にインポートされたツールと衝突してはなりません。 aidb.create_sql_tool() は、その場合に呼び出しを前もって拒否します。

パラメータープレースホルダー

sql_statement で宣言された各パラメーターを${name} として参照する — AIDBは、その呼び出しにモデルが提供した値、実際のクエリパラメーター文字列補間されていないとしてバインドされた値にそれぞれを置き換えます。ステートメントで複数回使用されるパラメーターは、1回だけ宣言する必要があります。 params は必須です。パラメーターをとらないツールの場合、引数なしでaidb.tool_params() を渡します。

読み取り専用ツール

read_only のデフォルトはtrue です。書き込む必要があるツールにread_only => false を渡します。そして、それは両方向に説明的なだけでなく適用されます。デフォルトのtrue のままでは、sql_statement が認識された書き込みパターンINSERT 、UPDATE 、DELETE などと一致する場合、登録はすぐに失敗します。誤ったラベルのツールを通過させるのではなく。デフォルトのread_only => true のままになっているツールは、 読み取り専用モード で実行されているエージェントでも使用できます。 read_only => false と明示的にマークされたツールは、未分類のネイティブまたはMCPツールと同様に、読み取り専用の実行から除外されます。

sql_statement は単一のステートメントである必要があり、 EXPLAIN やCOPY のようなユーティリティステートメントはできません。後続の空白と後続の; は、登録時に自動的に削除されます。

!!!note create_sql_tool は、 params と同じaidb.tool_params() 形状のreturn_type_hint 引数も受け入れ、クエリーが返す行の形状を説明します。これはツールとともに保存されますが、現在モデルまたはaidb.tools には表示されません。今のところ、その唯一の使用は、ailedb.sql_tool_registryを直接検査する人のためのドキュメントとしてです。

ツールの削除

SELECT aidb.delete_tool(orders_by_customer);

aidb.delete_tool() は、渡した名前がSQLツールではなくに属している場合、 MCP tools も削除しますが、ビルトインネイティブツールは削除できません。