Custom SQL tools ================ SQLツールは、エージェントが名前で呼び出すことができる保存されたパラメーター化クエリです。これを使用して、Rustを書いたり、ネイティブAIDBファンクションを公開したりせずに、エージェントに独自のテーブルとビジネスロジックへのアクセスを許可します。 .. code:: sql 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 ); .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `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()`` は、パラメーターをとらないツールを宣言します。 他の方法と同じようにエージェントにツールを登録します。 .. code:: sql SELECT aidb.create_agent(sales_helper, Answer questions about customer orders., my_gpt, tools => ARRAY[orders_by_customer]); ネーミング ---------- ツールの名前は、すべてのツールタイプで一意である必要があります。ビルトイン :ref:`Native tools ` または :ref:`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`` のままになっているツールは、 :ref:`読み取り専用モード <読み取り専用モード>` で実行されているエージェントでも使用できます。 ``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を直接検査する人のためのドキュメントとしてです。 ツールの削除 ------------ .. code:: sql SELECT aidb.delete_tool(orders_by_customer); ``aidb.delete_tool()`` は、渡した名前がSQLツールではなくに属している場合、 :ref:`MCP tools ` も削除しますが、ビルトインネイティブツールは削除できません。