18 エージェント・ツールについて

Oracle AI Data Platform Workbenchは、データにアクセスし、ユース・ケースに適合するように構成できるツール・テンプレートをサポートしています。

エージェントは、1つ以上のツールとインタフェースできる単一のエージェントで構成される構成をサポートします。AIデータ・プラットフォーム・ワークベンチには、ビジュアル・フローまたはコードを介して使用するように構成できる3つのツール・テンプレートが用意されています。

  • カスタム・コード:カスタム・コード・ツールを使用すると、AI開発者はPythonを使用してツールを実装できます。開発者は、ツールをZIPにパッケージ化し、ワークスペースにアップロードして、エージェントのノードとして構成します。カスタム・コード・ツールは、組込みツールが必要とする統合を提供しないケースを対象としています。
  • HTTPリクエスト: HTTPリクエスト・ツールを使用すると、開発者は、AI Data Platform Workbench APIおよびそれらが提供する機能を利用して、サポートされているREST APIコールをエージェントで使用できます。エージェントは、REST APIを使用して、ワークスペース・オブジェクトの作成、詳細の確認、リストのプル、または既存のオブジェクトの変更を行うことができます。使用可能なAPIの完全なリストは、Oracle AI Data Platform Workbench REST APIを参照してください。
  • プロンプト: プロンプト・ツールを使用すると、AI開発者は、選択したLLMに発行できるパラメータ化されたプロンプトを定義できます。プロンプト・ツールの一般的なユース・ケースには、電子メール作成タスク、翻訳タスク、スタイル変換、gitコミット・メッセージ、コードの説明などがあります。
  • RAG: RAGツールを使用すると、エージェントは、レスポンスを生成する前に関連する外部ナレッジを取得できます。AIデータ・プラットフォーム・ワークベンチでは、RAGツールがナレッジ・ベース(26ai Vector Search)を問い合せて、意味に関連するドキュメント・チャンクを取得します。これらのチャンクは、レスポンス生成のためにエージェントに渡されます。
  • SQL: SQLツールを使用すると、エージェントは、外部カタログ(Oracle Autonomous AI Lakehouse、Oracle Autonomous AI Transaction Processing、Oracle Autonomous AI Databaseなど)を介して登録された構造化データ・ソースに対してSQL問合せを実行できます。このツールは、SQL問合せが事前定義され、パラメータ化できるシナリオを対象としています。目的は、エージェントがパラメータに値を割り当てるようにすることです。このツールは、自然言語プロンプトに基づいてSQL問合せを生成するNL2SQLツールではありません。

    ノート:

    SQLツールは、外部カタログのデータに対してのみ問合せを実行します。標準カタログに格納されたデータはサポートされません。

ビジュアル・フローを使用したエージェント・フロー・ツール

ビジュアル・フローを使用してツールをエージェントに追加すると、エージェントの「ツール・テンプレート」でツールを検索できます。ツールをエージェントに追加するには、ビジュアル・フロー・キャンバスにドラッグ・アンド・ドロップします。キャンバス上でツール・ノードをドラッグすると、ノードは自動的にエージェントに接続します。


ツール・テンプレート・セクションが強調表示されたエージェント・ページと、ツールからキャンバスを指す矢印

各ツールは、「パラメータ」タブで構成でき、「テスト」タブをクリックしてエージェントとは独立してテストできます。

ノート:

システム・ツールをテストする前に、エージェントにAIコンピュートをアタッチする必要があります。コンピュートがアタッチされていない場合、「テスト」タブは無効になります。

LangGraphコードを使用したエージェント・ツール

AIDPToolConf()クラスのインスタンスを使用して、LangGraphコード化されたエージェントにツールを追加します。 

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class, conf, params)
パラメータは、ツールのビジュアル・フロー・エクスペリエンスを反映しています。ツールごとに、次のものを指定する必要があります。
  • 名前:ユーザーおよびLLMがツールの目的を理解するのに役立つわかりやすい名前。
  • 説明:ユーザーおよびLLMがツールの動作を理解するのに十分な情報を提供する完全なサマリー。
  • tool_class:サポートされているツール・タイプPromptTool、SQLTool、RAGTool、HTTPToolおよびMCPTool。
  • conf:ツール構成。この情報はLLMには表示されません。
  • params: LLMに公開されるパラメータ。

カスタム・ツール

カスタム・コード・ツールを使用すると、エージェント開発者は独自のPythonコードを使用してAIデータ・プラットフォームを拡張できます。

ツール実装をZIPファイルとしてパッケージ化し、ワークスペースにアップロードして、エージェントのカスタム・コード・ツール・ノードとして構成します。エージェントは、実行時にLLMによって提供されるパラメータを使用して、コードをツールとしてコールします。

カスタム・コード・ツールは、組込みツール(HTTP、SQL、RAG、MCP)が、ローカル計算の実行、ドメイン固有のフォーマットの解析、エージェントに単一のツール・コールとして表示される複数のステップの作成など、必要な統合に対応していないケースを対象としています。

AI Data Platform Workbenchには、カスタム・コード・ツールのPythonコードを使用してZIPファイルをアップロードする際に、次の制限があります:

制約 制限
最大ZIPサイズ 10MB
ZIP内の最大ファイル・サイズ ファイル当たり10MB
最大合計非圧縮サイズ 500MB
パス・トラバース ブロック済(../拒否)

ノート:

カスタム・コード・ツールは、エージェントにアタッチされたAIコンピュート上で実行されます。このコードは、ワークスペース・ネットワーキング構成の対象となるコンピュート環境およびアウトバウンド・ネットワーク・アクセスにアクセスできます。信頼できるソースからのコードのみをアップロードします。

カスタム・コード・ツールのパラメータ

「パラメータ」タブで、パッケージ内の各ツール・クラスの静的設定を構成します。「ツールクラス」ドロップダウンを使用すると、パッケージ内で検出されたツールを切り替えることができます。


カスタム・コード・ツール・ページが開きます。「パラメータ」タブが選択されています。「構成」ペインが左側に表示されます。「AI Tool」定義ペインが右側に表示されます。

カスタム・コード・ツールの「パラメータ」タブには、次のセクションがあります。
  • ツール・クラス:構成するツール・クラスを選択します。ドロップダウンは、tool_implementation.pyに登録されているクラスから移入されます。
  • 説明:ツールの動作の明確で簡潔な説明。この説明はエージェントに提供され、LLMがツールを呼び出すタイミングを決定するのに役立ちます。デフォルトの説明はtool_config.jsonから読み取られ、ここでオーバーライドできます。
  • 構成:ツールが実行時に必要とする静的設定。これらは、tool_config.jsonのconfオブジェクトで定義されているキーです。たとえば、timeout、base_dir、max_output_linesおよび資格証明参照があります。構成値は、{{variable}}ランタイム・パラメータ参照をサポートします。セッション変数は、現在カスタム・ツール構成に置換されていません。セッション値が必要な場合は、エージェントからランタイム・パラメータとして渡してください。
  • AIツール定義:エージェントに公開されるスキーマ(ツール名、説明、エージェントが渡すことができるランタイム・パラメータなど)。スキーマは、tool_config.jsonのスキーマ配列から自動的にレンダリングされます。

カスタムコードツールオーサリング

カスタムコードツールパッケージは、次の構造を持つZIPファイルです。 

my_tool.zip 
├── tool_implementation.py    # Required. Contains the tool class(es). 
├── tool_config.json          # Required. Tool metadata and schema. 
├── requirements.txt          # Optional. Python dependencies. 
├── utils/                    # Optional. Helper modules. 
│   ├── __init__.py 
│   └── helpers.py 
├── config/                   # Optional. Static configuration files. 
│   └── settings.yaml 
└── wheels/                   # Optional. Bundled wheel files for offline install. 
    └── humanize-4.15.0-py3-none-any.whl

ツール_実装.py

各ツール・クラスはCustomToolBaseを拡張し、@BaseTool.registerで装飾されています。クラスは、ツール構成、エージェントからのランタイム・パラメータおよびシステム・コンテキスト変数を受信する_execute_toolクラス・メソッドを実装し、dict、str、listなどの値を戻す必要があります。

次に、tool_implementation.pyの空白のサンプル・テンプレートを示します。 

"""Custom Code tool implementation.""" 
from aidputils.agents.tools.custom_tools.base import CustomToolBase 
 
 
@BaseTool.register 
class MyTool(CustomToolBase): 
    """Brief description of what the tool does.""" 
 
    @classmethod 
    def _validate_config(cls, conf, runtime_params, **context_vars): 
        """Optional. Validate configuration before execution. 
        Raise ValueError to abort the call. 
        """ 
        # Example: require an api_key in the tool configuration 
        if not conf.get("conf", {}).get("api_key"): 
            raise ValueError("api_key is required") 
 
    @classmethod 
    def _execute_tool(cls, conf, runtime_params, **context_vars): 
        """Required. Implement the tool logic. 
 
        Args: 
            conf: the AIDPToolConf dict. User configuration values 
                live under conf["conf"] when the tool is invoked from 
                a deployed agent. During a Test run the tool may 
                receive a flat conf dict; the Developer Toolkit example 
                below uses a small _get_cfg helper that tolerates both 
                shapes. 
            runtime_params: the runtime parameters passed by the 
                agent at invocation time. 
            context_vars: system context (such as datalake_id). 
 
        Returns: 
            Any value (dict, str, list, ...). It will be wrapped into 
            the MCP response by the framework. 
 
            To signal a failure, raise an exception: 
              - ValueError -> INVALID_CONFIG 
              - any other exception -> TOOL_EXECUTION_ERROR 
            Do NOT return {"error": "..."}; the framework wraps a 
            successful return in {"response": ..., "success": True}, 
            so a returned error dict is treated as a normal payload 
            and the agent will not see it as a failure. 
        """ 
        tool_conf = conf.get("conf", conf) 
        param_value = runtime_params.get("my_param", "") 
        # Tool logic here 
        return {"output": f"Processed: {param_value}"} 
 
    @classmethod 
    def _transform_response(cls, response): 
        """Optional. Transform the response before MCP formatting.""" 
        return response

ツール_構成.json

tool_config.jsonファイルには、パッケージ内のツール(表示名、説明、バージョン、ランタイム・パラメータ・スキーマおよびデフォルトの構成値)が記述されます。tool_implementation.pyに登録された各ツールには、対応するエントリがtoolsアレイ内に存在する必要があります。

次に、tool_config.jsonの空白のサンプル・テンプレートを示します。
{
   "displayName": "My Tool Package",
   "description": "Brief description of the tool package.",
   "tools": [
     {
       "toolClassName": "MyTool",
       "displayName": "My Tool",
       "description": "Clear description of when the agent should call this tool.",
       "version": "1.0.0",
       "schema": [
         {
           "name": "my_param",
           "type": "string",
           "description": "What this parameter is for."
         }
       ],
       "conf": {
         "timeout": 30
       }
     }
   ]
 }

スキーマ・フィールド・タイプ

ビジュアル・ビルダーの「パラメータ」タブには、文字列、数値およびブール値を指定できます。tool_config.jsonを手動で作成する場合、ランタイムはより広いセットを受け入れます: int、integer、float、double、number、numeric、bytes、list、array、sequence、dict、map、mapping、set、tuple、none、null、およびlist[int]のような汎用形式。これらのより広いタイプはJSONから使用できますが、UIドロップダウンには表示されません。

要件.txt

requirements.txtファイルには、ツールに必要なPythonの依存関係がリストされます。バージョン指定子やコメントなど、標準のpip構文がサポートされています。ファイルはオプションです。ツールでPython標準ライブラリまたは事前インストール済パッケージのみを使用する場合は、requirements.txtは必要ありません。

次に、requirements.txtの空白の例を示します。 

# List third-party dependencies one per line. 
# Examples: 
# humanize>=4.0 
# python-dateutil>=2.8,<3.0 
# beautifulsoup4==4.12.3

AI Data Platform Workbenchは、requirements.txtの依存関係をフィルタリングしてから、AIコンピュートにインストールし、プラットフォーム自体とのランタイム競合を防止します。フィルタリング・ルールは次のとおりです。

カテゴリ 例 アクション
プラットフォームパッケージ langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml 破棄されました(エージェント・ランタイムは中断されます)。
インストール済みパッケージ oci、リクエスト、requests-toolbelt、websockets、cryptography、certifi、pyopenssl、urlib3、pydantic、pydantic-core、pydantic-settings、numpy、oracledb、sqlalchemy、aiohttp、httpx、httpx-sse、anyio、jsonschema、orjson スキップされました(すでに使用可能であり、宣言する必要はありません)。
URLまたはVCSインストール git+https://...、-e ./local_pkg ブロック(セキュリティ)。
その他すべて ヒューマライズ、 beautifulsoup4、 jmespath インストール済みです。

ノート:

requirements.txtで宣言された依存性は、エージェントの完全デプロイメント中にインストールされます。構成パネルからの単一のテスト実行中は、依存関係はインストールされません。ツールがサード・パーティ・パッケージに依存している場合は、まずエージェントをデプロイしてから、プレイグラウンドからツールを実行します。

事前インストールされておらず、確定的、オフラインでのインストールが重要な依存関係を必要とするツールの場合、.whlファイルをZIPのルートにあるwheels/ディレクトリ内にバンドルできます。プラットフォームは、最初にローカルwheelsディレクトリからインストールされ、必要に応じてパッケージ索引にフォールバックします。これは、本番ツールに推奨される方法です。

オフラインインストール用のバンドルホイール

pip download \
  --dest wheels/ \
  --platform manylinux_2_28_x86_64 \
  --python-version 3.11 \
  --only-binary=:all: \
  -r requirements.txt

ツール・ライフサイクル・フック

カスタム・コード・ツールでは、3つのライフサイクル方法がサポートされています。_execute_toolのみが必要です。

Method 呼び出されたとき 目 的
構成の検証(_V) _execute_toolの前 構成を検証します。ValueErrorを呼び出して、実行前にコールを中止します。
ツールの実行(_E) すべてのツールの起動時 必須フィールドです。ツールの動作を実装します。任意の値(dict、str、list)を返し、失敗を示す例外を発生させます(ValueError→INVALID_CONFIG、その他の例外 →TOOL_EXECUTION_ERROR)。返される{"error": "..."} dictは通常のペイロードとして扱われるため、使用しないでください。
応答を変換(_T) _execute_toolの後 MCP形式でラップされてエージェントに戻される前に、レスポンスを変換します。
prompt_template 文字列 動的挿入のために、{{variable}}形式の変数とともにLLMで使用されるプロンプト・テンプレート

構成値とランタイム・パラメータ

カスタム・コード・ツールには、混乱しやすい2つの異なる入力ソースがあります。構成値は、「パラメータ」タブの「構成」セクションから取得され、エージェントのデプロイ時にツールにベイク処理されます。ランタイム・パラメータは起動時にエージェントから取得され、コールごとに異なります。

  • 構成値には、conf.get("conf"、 conf)を介してアクセスします。ベースURL、資格証明参照、タイムアウト、出力制限など、コール間で変更されないものに使用します。
  • ランタイム・パラメータはruntime_params.get("name")を介してアクセスします。これらは、エージェントがコール時に実際に決定する値(問合せ、ファイル・パス、リクエスト本文)に使用します。

ノート:

構成値はテンプレート置換を通過でき、数値として定義した場合でも文字列として到着する可能性があります。数値構成値は常にint(tool_conf.get("timeout", 30))のように防御的に強制します。

パッケージごとの複数のツール

1つのZIPに複数のツールクラスを含めることができます。@CustomToolBase.registerに登録された各クラスは、エージェント内の個別のツールになります。「パッケージ」タブの「ツール」パネルには、検出されたすべてのツールがリストされ、各ツールを個別に有効にできます。各ツールは、「ツール・クラス」ドロップダウンを介して「パラメータ」タブで個別に構成されます。

LangGraphコードを使用したコード・ツール

コード・ビルダーから、カスタム・コード・ツールは、アップロードされたパッケージを参照し、そのツール・クラスの1つを選択することで、aidpUtils Pythonライブラリを介して登録されます。

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
 from aidputils.agents.toolkit.configs import AIDPToolConf
 
hello_tool_conf = AIDPToolConf(
     name="hello_tool",
     description="Returns a hello world greeting.",
     tool_class="HelloTool",  # the class registered with @BaseTool.register
     conf={},                  # values from tool_config.json "conf"; supports {{variable}} substitution
     params=[
         {"name": "name", "type": "string",
          "description": "Name to greet."}
     ],
 )
 
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())

tool_classは、tool_implementation.pyの@BaseTool.registerを介して登録された正確なクラス名である必要があります。フレームワークは、BaseTool.tool_class_registry[tool_class]でクラスをルックアップします。confは、tool_config.jsonの一致するエントリのconfオブジェクトをミラー化します。

ノート:

package_pathまたはtool_class_nameは消費されないため、conf内に配置しないでください。

テストエージェントカスタムコードツール

「テスト」タブでは、エージェント全体を実行せずにツールを実行できます。構成で参照されるランタイム・パラメータおよびセッション変数の値を指定し、「実行」をクリックしてツールを起動し、レスポンスを表示します。


カスタム・コード・ツール・ページが開きます。「テスト」タブが選択されています。テスト・パラメータが左ペインに表示されます。テスト結果が右側のペインに表示されます。

ノート:

ツールがrequirements.txtで宣言されたサード・パーティ・パッケージに依存している場合、依存関係は、単一のテスト実行中ではなく、エージェントのフル・デプロイメント中にインストールされます。追加パッケージに依存するコードをテストするには、まずエージェントをデプロイしてから、プレイグラウンドからツールを起動します。

エージェントへのカスタム・ツールの追加

カスタム・ツールをエージェントに追加して、独自のPythonコードを使用してAIデータ・プラットフォームを拡張できます。

ノート:

カスタム・コード・ツールを追加する前に、エージェントにAIコンピュートをアタッチする必要があります。依存関係をインストールしてツールを実行するには、AIコンピュートが必要です。
  1. エージェントにナビゲートします。
  2. ツール・テンプレートから、カスタム・ツールをキャンバスにドラッグ・アンド・ドロップします。
  3. 「パッケージ」タブで、クリックしてカスタム・コードを含むZIPファイルを選択するか、画面にドラッグ・アンド・ドロップします。アップロードが完了するのを待ちます。

    カスタム・コード・ツール・ページが表示されます。「パッケージ」タブが選択されています。画面に「Select a file or drop one here」が表示されます。

  4. 「パッケージ」タブの「ツール」セクションで、検出されたツールのリストを確認します。tool_implementation.pyにある各ツール・クラスは、そのクラス名、説明およびバージョンとともにリストされます。

    カスタム・コード・ツール・ページが表示されます。「パッケージ」タブが選択されています。パッケージとしてadvanced_tool.zipが選択されています。「ツール」ペインに、Bashツール、ファイル・ツールおよびPythonツールの3つのツールが表示されました。すべてのツールが選択されています。

  5. 有効にするツールを選択します。無効なツールはエージェントに公開されません。
  6. オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。

リモートMCPサーバーツール

エージェント・フロー開発者は、リモートMCPサーバー・ツールを使用して、エージェント・フローをリモート・モデル・コンテキスト・プロトコル(MCP)サーバーに接続できます。

MCPツールは、ビジュアル・ビルダーとコード・ビルダーの両方のエクスペリエンスで使用できます。コード・ビルダーの経験では、MCP接続はaidpUtils Pythonライブラリを介して構成できます。この項では、ビジュアル・ビルダーとコード・ビルダーの両方のエクスペリエンスについて説明します。

ノート:

この機能では、HTTPストリーム可能トランスポート(リモートサーバー)を備えたMCPサーバーがサポートされます。ローカルなstdio-transport MCPサーバーはサポートされていません。

Oracle AI Data Platform Workbench資格証明ストアのMCP資格証明

MCPサーバーを構成するときは、リモートMCPサーバーに No Authenticationまたは Bearer tokenのどちらが必要かを選択する必要があります。MCPサーバーで認証トークンが必要な場合は、そのトークンをMCPサーバーによって参照する前に、資格証明ストアに追加する必要があります。

MCPサーバー資格証明を作成する場合は、「資格証明タイプ」に「シークレット・トークン」オプションを選択し、APIキーやトークン値などの識別子キーを指定します。詳細は、資格証明の作成(プレビュー)を参照してください。

ノート:

1つの資格証明に複数のキーを保持できます。

パブリックで使用可能なMCPサーバーは、追加の認証を必要としません。たとえば、https://mcp.deepwiki.com/mcpへの接続は次のようになります。


「カスタムMCPサーバーの追加」ダイアログが表示されます。公開されているMCPサーバーDeepWikiに関する情報が移入されます。

MCPツールをエージェントに公開する方法

リモートMCPサーバーへの接続が成功したら、エージェントに公開するサーバー上でホストされているツールの構成を開始できます。DeepWiki MCPサーバーの場合、MCPサーバー構成パネルを以下に示します。


リモートMCPサーバーツールの構成ページが表示されます。「ツール」タブが選択されています。

左側の「ツール」タブには、MCPサーバーで使用可能なツールのリストが表示されます。エージェントに公開するツールを追加する必要があります。これを行うには、「すべて追加」オプションをクリックしてすべてのツールを一度に公開するか、各ツールの「追加」オプションを個別にクリックしてツールのサブセットを選択します。


「Remote MCP server tool configuration」ページが表示されます。「Tools」タブが選択され、「Add all」および「Add」ボタンが強調表示されます。

次の例では、2つのツール(read_wiki_structure、read_wiki_structure)を追加しました。ツールを削除するには、「削除」をクリックします。


「Remote MCP server tool configuration」ページが表示されます。「ツール」タブが選択され、「追加済」でread_wiki_structureが選択されます。read_wiki_structureに「削除」ボタンが表示されます。

「ツール」タブの右側のパネルには、ツール名、ツールの説明、ツールのパラメータなど、各ツールに関するドキュメントが表示されます。次のスクリーンショットでは、GitHub MCPサーバー・ツールadd_comment_to_pending_reviewの例を示します。


「Remote MCP server tool configuration」ページが表示されます。「ツール」タブが強調表示されています。ツール名、ツールの説明、ツールの説明のオーバーライド、ツールのパラメータ、およびエージェントに公開するトグルは、テキストと赤色の矢印で示されます。

Oracle AI Data Platform Workbenchには、各ツールに対する追加のコントロールがいくつか用意されています。エージェントからパラメータを非表示にし、それらのパラメータに値を割り当てることができます。たとえば、GitHubでは、エージェントがoracle-aidp-samplesなど、事前に決定された1つのリポジトリのみにコメントするように選択できます。これを実現するには、repoパラメータを無効にし、テキストボックスにデフォルト値を割り当てます。


「Remote MCP server tool configuration」ページが表示されます。「ツール」タブが選択されています。右側のペインで、repoパラメータが強調表示され、値はoracle-aidp-samplesです。切り替えられています。

「ツール・インストラクション」フィールドで、ツールの説明を上書きしたり、追加のインストラクションを含む別の説明を提供することもできます。ほとんどのユースケースでは、MCPサーバーから提供される説明を採用することをお勧めします。


「Remote MCP server tool configuration」ページが表示されます。「ツール」タブが選択されています。右側のペインで、「ツールの指示」(オプション)フィールドが強調表示され、次のフィールドに別の指示が示されています。

LangGraphコードによるリモートMCPサーバツール

aidpUtils Pythonライブラリは、開発者がリモートMCPサーバーを選択し、そのツールのサブセットをLangGraphで構築されたエージェントに公開する機能を提供します。helpputils APIリファレンスは、Oracle AI Data Platform WorkbenchのAidp-utils APIを参照してください。

build_structured_tools_from_allowed_mcp_toolsのインスタンスを作成することで、許可されるツールのコレクションを構築できます。 

from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools

TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>, 
	server_name=<MCP_SERVER_NAME>, 
	endpoint=<MCP_ENDPOINT>, 
	transport="streamable_http", 
	auth=<MCP_AUTH>, 
	headers={} 
)
説明:
  • <MCP_SERVER_NAME>は、MCPサーバーに付与する表示名です。これはドキュメント目的で使用され、エージェントには公開されません。
  • <MCP_ENDPOINT>は、MCPサーバーのエンドポイントです(例: https://api.githubcopilot.com/mcp/)
  • <MCP_AUTH>は、キーauthTypeを持つディクショナリです。このキーには、NO_AUTHまたはBEARER_TOKENの2つの値を指定できます。BEARER_TOKENの場合、Bearerトークンの値を持つ"token"という別のキーが必要です。
  • <ALLOWED_MCP_TOOLS>は、エージェントに公開するMCPサーバーからのツールのリストです。各ツールには、MCPプロトコルに従った完全なJSONツール定義が必要です。

次に例を示します:

MCP_SERVER_NAME = "test_mcp" 
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp" 
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }

{
  "ALLOWED_TOOLS": [
    {
      "tool": {
        "name": "get_current_weather",
        "description": "Get current weather for a given city with advanced options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_historical": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "timeout": {
              "type": "integer",
              "default": 30
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    },
    {
      "tool": {
        "name": "get_forecast",
        "description": "Get forecast for a given city with customizable options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "days": {
              "type": "integer",
              "default": 5
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_alerts": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "hourly": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    }
  ]
}

MCP_HEADERS = {} 
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
	server_name=MCP_SERVER_NAME, 
	endpoint=MCP_ENDPOINT, 
	transport="streamable_http", 
	auth=MCP_AUTH, 
	headers=MCP_HEADERS,
)

TOOLSオブジェクトは、クラス・エージェント定義のsetup()メソッドでlangchain.agent create_agentを使用してエージェントのインスタンスを作成するときに使用できます。 

def setup(self):
    logger.info("Initializing TestMcpAgent")

    oci_llm = init_oci_llm(llm_conf)

    system_prompt = textwrap.dedent(
        """
        You're a weather agent. Append 12345 to every response.
        """
    ).strip()

    self.agent = create_agent(
        name="test_mcp_high_code",
        model=oci_llm,
        tools=TOOLS,
        system_prompt=system_prompt,
        debug=True,
    )

    logger.info("Agent ready.")

または、セッション変数を使用してベアラー・トークンの値を格納している場合は、以前に作成したセッション変数への参照を認証構成ディクショナリのトークン・キーに割り当てることができます。たとえば:

test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools( 		
allowed_tools=test_mcp_mcp_allowed_tools, 
	server_name="test_mcp", 
	endpoint="http://144.25.36.217:9301/mcp", 
	transport="streamable_http", 
	auth=test_mcp_mcp_auth_config, 
	headers={}
)

リモートMCPサーバーツールのコード例

AI Data Platform WorkbenchサンプルGitHubリポジトリには、複数のMCPシナリオのエンドツーエンドのコード・サンプルが用意されています。

リモートMCPサーバーツールのテスト

ツールを選択したら、通常、次のステップは、個々のツールが期待どおりに動作することを確認するためのテストです。これは、MCPツール・ノードの「テスト」タブで実行できます。


「Remote MCP server tool configuration」ページが表示されます。「テスト」タブが強調表示されます。

「ツール」タブで追加したツールの1つを選択し、パラメータ値を指定して「テスト」ボタンをクリックします。


「Remote MCP server tool configuration」ページが表示されます。「テスト」タブが選択されています。左側のペインにlist_branchesの情報が表示されます。テスト・レスポンスが右側のペインに表示されます。

ツールの出力が右側のパネルに表示されます。

「詳細」タブには、認証方法、MCPサーバーURLおよび説明に関する情報が表示されます。


「Remote MCP server tool configuration」ページが表示されます。「Details」タブが強調表示されています。

認証方法の横にある「編集」ボタンを使用して、リモートMCPツール・ノードの構成を変更します。接続の確立時に使用される表示名、説明およびベアラー・トークンを変更できます。


「カスタムMCPサーバーの編集」ダイアログが表示されます。https://api.githubcopilot.com/mcpの詳細が移入されます。

Visual BuilderからリモートMCPサーバーへのエージェントの接続

カスタムMCPサーバー・ツール・ノードをキャンバスにドラッグすることで、リモートMCPサーバーへのアクセスをエージェントに追加できます。

使用可能なカスタムMCPサーバー・ツールが表示されない場合は、既存のAIコンピュートを再起動するか、新しいAIコンピュートを作成する必要がある場合があります。

ノート:

エージェントをホストするAIコンピュートは、そのワークスペースのネットワーク設定を継承します。AIコンピュートをホストしているワークスペースに対してプライベート・ネットワーク・アクセスを有効にした場合、エージェントは選択したプライベートVCNおよびサブネットでホストされているMCPサーバーにのみ到達できます。エージェントが、パブリック・インターネットで使用可能なリモートHTTPサーバーにアクセスできない可能性があります。
  1. エージェントにナビゲートします。
  2. 「フロー」タブの「ツール・テンプレート」で、「カスタムMCPサーバー」をクリックしてキャンバスにドラッグします。
  3. MCPサーバーのサーバーURLを指定します。
  4. MCPサーバーの表示名を指定します。これは、ビジュアル・ビルダーのキャンバスに表示されるノードの名前です。
  5. オプション: MCPサーバーの説明を指定します。説明フィールドがエージェントに指定されていません。
  6. 「認証」ドロップダウン・メニューから、認証方法を選択します。
    • 認証なし: リモートMCPサーバーがパブリックに使用可能であり、認証を必要としない場合は、このオプションを使用します。
    • Bearer token: リモートMCPサーバーに認証トークンが必要な場合、このオプションを使用します。APIキーをOracle AI Data Platform Workbench資格証明ストアに格納し、資格証明ストア・エントリへの参照を指定する必要があります。
  7. 「接続」をクリックします。AI Data Platform Workbenchによって接続がテストされ、結果がレポートされます。

HTTPリクエスト・ツール

HTTPリクエスト・ツールを使用すると、エージェントは任意のHTTPS REST APIをコールできます。

メソッド、URL、ヘッダー、問合せパラメータ、リクエスト本文、認証、およびオプションでレスポンス最適化ステップを含むリクエストを構成します。その後、エージェントは実行時にエンドポイントを呼び出します。HTTPリクエスト・ツールは、ビジュアル・ビルダーとコード・ビルダーの両方で使用できます。コード・ビルダーでは、このツールはaidpUtils Pythonライブラリを介して構成されます。

ノート:

HTTPリクエスト・ツールでは、https://およびHTTP://リクエストのみがサポートされます。WebSocket接続(ws/wss)、バイナリ・ファイルのアップロードおよび自己署名証明書はサポートされていません。

ノート:

エージェントをホストするAIコンピュートは、そのワークスペースのネットワーク設定を継承します。AIコンピュートをホストしているワークスペースに対してプライベート・ネットワーク・アクセスを有効にすると、エージェントは選択したプライベートVCNおよびサブネット内のHTTPエンドポイントにのみ到達します。エージェントは、パブリック・インターネットで使用可能なエンドポイントにアクセスできません。

HTTPリクエスト・ツールを構成する場合は、次の設定を指定する必要があります。

構成 説明
HTTPメソッド 使用するHTTP動詞。サポートされているメソッドは、GET、POST、PUT、PATCHおよびDELETEです。
URL ターゲット・エンドポイントの完全なURL。URLでは、{{sessionVariables.variable_name}}セッション変数参照および{{variable}}ランタイム・パラメータ参照がサポートされます。例: https://api.example.com/users/{{user_id}}/orders。
タイムアウト ツールがリモート・エンドポイントからのレスポンスを待機する最大時間。デフォルトは30秒で、最大は300秒です。
認証タイプ エンドポイントのコール時に使用する認証メソッド。サポートされている認証方式のリストについては、後述の「認証」セクションを参照してください。

ノート:

カスタム・コード・ツールは、エージェントにアタッチされたAIコンピュート上で実行されます。このコードは、ワークスペース・ネットワーキング構成の対象となるコンピュート環境およびアウトバウンド・ネットワーク・アクセスにアクセスできます。信頼できるソースからのコードのみをアップロードします。

ヘッダー

ヘッダーは、HTTPリクエストとともに送信されるキーと値のペアです。「新規追加」ボタンをクリックすると、必要な数のヘッダーを追加できます。ヘッダー値は、{{variable_name}}構文を使用してセッション変数およびランタイム・パラメータを参照できます。

ノート:

機密ヘッダーの場合は、「認証タイプ」フィールドを使用して、資格証明が資格証明ストアから安全に注入されるようにする必要があります。認可、CookieおよびX-API-Keyは機密ヘッダーであり、「ヘッダー」セクションからは設定できません。

問合せパラメータ

問合せパラメータは、問合せ文字列としてURLに追加されます。「新規追加」ボタンをクリックすると、必要な数の問合せパラメータを追加できます。ヘッダーと同様に、問合せパラメータ値はセッション変数およびランタイム・パラメータを参照できます。

説明

descriptionフィールドは、ツールの動作、使用するタイミング、およびツールが生成する出力や効果の種類を示します。この説明はエージェントに提供され、LLMがツールを呼び出すタイミングを決定するのに役立ちます。

説明を記述する場合は、次のことに焦点を当てる必要があります。
  • • 目的:ツールが1つの明確な文で何をするように設計されているかを説明します。例: 「このツールは、ナレッジ・ベースからカスタマ・サポート・チケットを取得し、優先度レベルで要約します。」
  • 使用するタイミング:エージェントがこのツールをコールする条件と別のツールをコールする条件を説明します。
  • 入力および出力:ツールが必要とするパラメータと、ツールが返す形状を簡単に説明します。

HTTPリクエスト認証

HTTPリクエスト・ツールでは、いくつかの認証方法がサポートされています。「認証タイプ」ドロップダウンから適切なメソッドを選択します。

認証タイプ 説明
認証なし リクエストに認証は追加されません。パブリックにアクセスできるエンドポイントに使用します。
OCIリソース・主体 リクエストは、AI ComputeのOCI Resource Principalを使用して署名されます。これは、オブジェクト・ストレージやOCI生成AIサービスなどのOCIサービスをコールする場合に使用します。アクセスは、OCI IAMポリシーによって管理されます。
Basic認証 ユーザー名とパスワードは、認可ヘッダーでエンコードされて送信されます。資格証明は資格証明ストアに格納される必要があります。
Bearerトークン BearerトークンがAuthorizationヘッダーで送信されます。トークンは資格証明ストアに格納される必要があります。
ヘッダー認証 APIキーはカスタムヘッダー(X-API-Keyなど)で送信されます。ヘッダー名は構成可能で、キー値は資格証明ストアに格納される必要があります。

シークレットを必要とする認証方法を選択すると、構成パネルに資格証明ピッカーが表示されます。資格証明ピッカーをクリックして、以前に格納した資格証明を選択するか、資格証明ストアから新しい資格証明を作成します。手順については、MCPサーバーのドキュメントの「資格証明ストア」セクションにある資格証明の格納を参照してください。

セッション変数およびランタイム・パラメータ

セッション変数は、{{sessionVariables.variable_name}}構文を使用して、URL、ヘッダー値、問合せパラメータ値およびリクエスト本文で参照できます。呼出し時にエージェントによって渡されるランタイム・パラメータは、{{variable_name}}構文を使用して参照できます。

たとえば、次のURLは、リージョンのセッション変数とバケット名のランタイム・パラメータを結合します。
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

ツールが実行されると、{{sessionVariables.region}}は現在のセッションのリージョン・セッション変数の値に置き換えられ、{{bucket}}は、起動時にエージェントが渡した値に置き換えられます。

ノート:

テンプレート値は、URLまたは問合せパラメータに置換されるときに自動的にURLエンコードされます。自分でURLエンコードする必要はありません。

AIツール定義

構成パネルの右側にAIツールの定義が表示されます。これは、エージェントに公開されるスキーマであり、ツール名、説明およびツールのコール時にエージェントが渡すことができるランタイム・パラメータのリストが含まれます。AIツール定義は、「説明」フィールドおよびURL、ヘッダー、問合せパラメータおよび本文で検出された{{variable}}プレースホルダから自動的に生成されます。

AIツール定義ペインは、このドキュメントで前述したHTTPツール構成パネルの右側にあるパネルです。説明を指定し、1つ以上のランタイム・パラメータを定義するまで、AIツール定義ペインにプレースホルダ・メッセージが表示されます。説明を入力し、URL、ヘッダー、問合せパラメータまたは本文で少なくとも1つの{{variable}}を参照すると、スキーマがペインにレンダリングされます。

エージェントに対する応答の最適化

多くのAPIは、エージェントが必要としないフィールドを含む大規模なレスポンスを返します。レスポンス全体をエージェントに送信すると、トークンが消費され、エージェントの推論の品質が低下する可能性があります。HTTPリクエスト・ツールには、レスポンス・ペイロードをエージェントに返す前に減らすことができるレスポンス最適化セクションが用意されています。

次の3つの最適化戦略がサポートされています。
  • JSONフィールドの選択: JSONレスポンスからフィールドのサブセットを選択します。ドット表記法(data.resultsなど)および包含または除外するフィールドのリストを使用して、ネストされたオブジェクトへのパスを指定できます。
  • HTML CSSセレクタ: CSSセレクタ(article.contentなど)を使用して、HTMLレスポンスのサブセットを抽出します。オプションで、HTMLタグを削除してテキストのみを返します。
  • テキストの切捨て:テキスト・レスポンスが大きくなりすぎないように、最大文字数でレスポンスを大文字にします。

エラー処理およびエラー・コード

HTTPリクエストが失敗すると、ツールは構造化されたエラー・レスポンスをエージェントに返します。エラーには、エラー・コード、判読可能なメッセージ、および失敗の詳細が含まれます。エージェントはこの情報を使用して、再試行するか、別のツールにフォールバックするか、失敗をユーザーに報告するかを決定できます。

エラー・コード カテゴリ 意味 再試行可能
CONNECTION_TIMEOUT ネットワーク リモート・エンドポイントは、構成されたタイムアウト内に応答しませんでした。 ○
DNS失敗 ネットワーク URLのホスト名を解決できませんでした。 ○
CONNECTION_REFUSED ネットワーク リモート・エンドポイントが接続を拒否しました。 ○
SSL_CERTIFICATEエラー TLS リモート・エンドポイントのTLS証明書を検証できませんでした。 ×
未承認 HTTP 401 リモート・エンドポイントが資格証明を拒否しました。資格証明参照が有効であり、失効していないことを確認します。OCIリソース・プリンシパルの場合、AIコンピュートにこの環境にアクティブなリソース・プリンシパルがあることを確認します。 ×
禁止 HTTP 403 資格証明は正常に認証されましたが、リクエストされたリソースに対する権限がありません。リソースにアタッチされているAPIスコープ、権限またはIAMポリシーを確認します。 ×
見つからない(_F) HTTP 404 リモート・エンドポイントで、リクエストされたリソースが見つかりませんでした。 ×
レート限度 HTTP 429 リモート・エンドポイントがコール元をレート制限しています。Retry-Afterヘッダーで示された遅延後に再試行します。 ○
サーバーエラー HTTP 5xx リモート・エンドポイントがサーバー・エラーを返しました。多くの場合、一時的な問題です。 ○
サービスが利用できません HTTP 503 リモート・エンドポイントは一時的に使用できません。 ○
INVALID_TEMPLATE 検証 {{variable}}参照を解決できませんでした。参照されるすべてのセッション変数およびランタイム・パラメータが定義され、起動時に値が設定されていることを確認します。 ×
無効URL 検証 URLの形式が正しくないか、サポートされていないプロトコルを使用しているか、ブロックされたアドレス(プライベートIPアドレスやクラウド・メタデータ・エンドポイントなど)に解決されます。 ×
レスポンスが大きすぎます 検証 レスポンスが最大レスポンス・サイズ10MBを超えました。 ×
レート_制限_超過 プラットフォーム エージェントは、プラットフォームのエージェントごとのリクエスト率制限(60リクエスト/分)または同時実行性の制限(10同時リクエスト)を超えました。 ○

各エラー・レスポンスには、提示された次のステップを含むガイダンス・フィールドと、経過時間およびエラー固有のコンテキスト(HTTPステータス・コードなど)を含む詳細フィールドが含まれます。

LangGraphコードによるHTTPリクエスト・ツール

コード・ビルダーから、HTTPリクエスト・ツールはaidpUtils Pythonライブラリを介して構成されます。tool_classをHttpEndpointToolに設定してAIDPToolConfを定義し、confフィールドに構成ディクショナリを渡します。 

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf

weather_http_tool_def = {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "params": {
        "q": "{city}",
        "units": "metric",
        "appid": "{api_key}"
    },
    "auth_type": "NO_AUTH",
    "auth_config": {}
}

weather_http_tool_params = [
    {"name": "city", "type": "string",
     "description": "Name of the city."},
    {"name": "api_key", "type": "string",
     "description": "OpenWeather API key."}
]

weather_http_tool_conf = AIDPToolConf(
    name="get_weather",
    description="Get current weather for a city.",
    tool_class="HttpEndpointTool",
    conf=weather_http_tool_def,
    params=weather_http_tool_params
)

weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())

confディクショナリは、method、url、headers、params、body、auth_type、auth_configおよびresponse_optimizationというビジュアル・ビルダーと同じフィールドをサポートします。パラメータ・リストは、エージェントが渡すことができるランタイム・パラメータを定義します。

認証のタイプ auth_configフィールド
認証がありません {} (空)
RESOURCE_PRINCIPAL {} (空)
BASIC_AUTH ユーザー名、パスワード(またはOCI Vaultの資格証明の場合はusername_vault_id、password_vault_id)
ベアラー認証 Bearer_token (またはBearer_token_vault_id)
API_キー_認証 api_key (またはapi_key_vault_id)、header_name (デフォルトのX-API-Key)
OAUTH2_CLIENT_CREDENTIALS token_endpoint、scope、client_id、client_secret (またはclient_id_vault_id、client_secret_vault_id)

テストエージェントカスタムコードツール

「テスト」タブでは、エージェント全体を実行せずにツールを実行できます。構成で参照されるランタイム・パラメータおよびセッション変数の値を指定し、「実行」をクリックしてツールを起動し、レスポンスを表示します。

レスポンス・パネルには、HTTPステータス・コード、レスポンス・ヘッダー、レスポンス本文および経過時間(ミリ秒)が表示されます。レスポンス最適化が有効な場合、最適化されたレスポンスもRAWレスポンスとともに表示されます。

エージェントへのHTTPリクエスト・ツールの追加

HTTPリクエスト・ツールをエージェントに追加して、HTTPS REST APIをコールできます。

ノート:

カスタム・コード・ツールを追加する前に、エージェントにAIコンピュートをアタッチする必要があります。依存関係をインストールしてツールを実行するには、AIコンピュートが必要です。
  1. エージェントにナビゲートします。
  2. ツール・テンプレートから、HTTPリクエスト・ツールをキャンバスにドラッグ・アンド・ドロップします。

    HTTPリクエスト・ツールの構成ページが表示されます。「Parameters」タブが選択され、「Configuration」ペインと「AI Tool」定義ペインが表示されます。

  3. 「パラメータ」タブで、HTTPメソッドを指定します。サポートされているmoethodは、GET、POST、PUT、PATCHおよびDELETEです。
  4. 「URL」で、ターゲット・エンドポイントの完全なURLを指定します。{{sessionVariables.variable_name}}セッション変数参照および{{variable}}ランタイム・パラメータ参照を使用できます。例: https://api.example.com/users/{{user_id}}/orders。
  5. 「タイムアウト」には、ツールがリモート・エンドポイントからのレスポンスを待機する最大時間(秒)を指定します。最大タイムアウト値は300です。値が指定されていない場合、デフォルトは30秒です。
  6. 「認証」ドロップダウン・メニューから、適切な認証タイプを選択します。
  7. HTTPリクエストのヘッダーを指定します。ヘッダーを追加するには、「新規追加」をクリックします。

    HTTPリクエスト・ツールの「構成」ページが表示されます。「パラメータ」タブが選択され、「ヘッダー」フィールドが強調表示されます。

  8. HTTPリクエストの問合せパラメータを指定します。「新規追加」をクリックして、パラメータを追加します。

    HTTPリクエスト・ツールの「構成」ページが表示されます。「パラメータ」タブが選択され、「問合せパラメータ」フィールドが強調表示されます。

  9. オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。

プロンプト・ツール

プロンプト・ツールを使用すると、テンプレート化されたプロンプトを使用してAIエージェントでLLMをコールし、LLMレスポンスをエージェントに戻すことができます。

LLMに提供するプロンプトには、二重中カッコで識別されるパラメータ({{PARAMETER_NAME}}など)を含めることができます。パラメータ値は、ツールが呼び出されたときにエージェントによって割り当てられます。

プロンプト ツールを使用するタイミング

原則として、プロンプト・ツールで記述された指示は、エージェント指示に直接含めるか、エンド・ユーザーがユーザー・メッセージに直接提供できます。ただし、プロンプト・ツールがより適切なアプローチである状況があります。
  • プロンプトの長さが長く、複数の100sトークンにまたがる詳細な書式指示が必要です。
  • エージェントの指示にプロンプトを組み込むと、コンテキストの使用量が増加し、特にエージェントにSOTA LLMを採用している場合、コストが大幅に増加します。
  • コストを削減するために、エージェントに与えられた指示のサイズを最小限に抑えたいと考えています。
  • プロンプト・ツールによって定義されたタスクは、エージェントが使用した推論モデルよりも小さく高速なLLMで処理できます。通常、小規模なモデルはコスト効率が高く、場合によっては特定のモダリティまたはフォーマットでデータを生成するように特殊化できます。
  • プロンプト・ツールを使用すると、構造化された入力パラメータで出力生成を制御できます。ユース・ケースをパラメータ化し、セッションごとに生成が異なる可能性がある場合、プロンプト・ツールで生成をカプセル化することは理にかなっています。

さらに、プロンプト・ツールでの生成手順のカプセル化は、ツールの再利用性、メンテナンス性、モダリティ、出力の一貫性、スケーラビリティ、ガバナンスなど、最新のエージェント・アーキテクチャのベストプラクティスに従います。ユースケースの例を次に示します。

  • テンプレートとして使用できる事前定義済の承認済構造に従ったEメール、レポート、要約、記事などの生成
  • 複雑なJSON出力の生成
  • ドキュメントの要約、キー・センテンス抽出、説明タスク
  • 問合せの生成
  • 特定のモデル用に最適化された特定のモダリティ生成(イメージ、ビデオ、オーディオ、ポイント・クラウド・データなど)

ビジュアル・フローでのプロンプト・ツール

次に、ビジュアル・フローを介して構築されたプロンプト・ツールの例を示します。このツールでは、エージェントによって割り当てられたトピックに基づいてLLMにブログ投稿タイトルを生成するように求められます。

あなたはマスター・ブログの戦略家です。あなたの仕事は、特定のトピックに基づいて魅力的なブログ投稿のアイデアをブレーンストーミングすることです。指定された{{topic}について、5つの一意のブログ投稿タイトルを生成します。タイトルごとに、ポストが取る角度について一文の説明を含めます。出力を番号付きリストとして表示します。


キャンバスでプロンプト・ツールが選択された状態でエージェントを開く

この例では、プロンプト・ツールに次のパラメータを構成する必要があります。
  • ツール名:エージェントのガイドに役立つツールのわかりやすい名前を使用します。この例では、blog_ideasを提案します。tool123のような役に立たない名前を使用しないでください。
    「名前」フィールドが強調表示された「パラメータ」タブでエージェント・プロンプト・ツールが開きます

  • ツールの説明:ツールの動作に関する包括的な説明を提供します。ツールに制限がある場合や、ツールを使用しないシナリオがある場合は、「説明」フィールドにリストします。
    「説明」フィールドが強調表示された状態でエージェント・プロンプト・ツールが開きます

  • OCIリージョンおよび生成AIサービスLLM: OCIリージョンを選択して、そのリージョンで使用可能なLLMのリストを移入し、LLMを選択します。
    エージェント・プロンプト・ツールが開き、「リージョン」および「LLM」フィールドが強調表示された状態で構成します

  • LLMパラメータ:最大出力トークン、温度、上位pなどのパラメータは、「モデル・パラメータ」タブで構成されます。値を割り当てない場合、OCI生成AIサービスのデフォルト値が使用されます。
    「モデル・パラメータ」タブが開いたエージェント・プロンプト・ツール

  • 問合せ:ツールの目的の定義に使用されるプロンプトは、「問合せ」フィールドに定義されます。
    エージェント・プロンプト・ツール構成が開き、「問合せ」フィールドが強調表示されています

プロンプトで定義するパラメータは、「AIツール」定義パネルに自動移入されます。エージェントに、各パラメータの説明、および適用可能な場合はパラメータ・タイプとデフォルト値を指定します。


「パラメータ」タブが開いたエージェント・プロンプト・ツール。トピック・パラメータが「問合せ」フィールドで強調表示され、矢印がツール・パラメータ・フィールドが強調表示されているAIツール定義セクションを指しています。

LangGraphコードによるプロンプト・ツール

コードを使用してエージェントを構築する場合は、ビジュアル・フローの例で次のように同じプロンプト・ツールを構成できます。

prompt_config = {
  "llm": {
    "model_id" : "xai.grok-4",
    "model_provider" : "generic",
    "compartment_id" : "<your-compartment-ocid>",
    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
  }, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
  "name" : "topic",
  "type" : "string",
  "description" : "Blog topic",
  "defaultValue" : "golf"
} ]

次に、次のようにAIDPToolConfをインスタンス化します。 

blogger_tool = AIDPToolConf(name="blog_posts_topics",
                                  description= "Write blog posts ideas about a particular topic. ",
                                  tool_class = "PromptTool", conf=prompt_config params=prompt_params)

最後に、支援ユーティリティからcreate_langgraph_tool()ユーティリティ関数を使用してLangGraph互換ツールを作成します。 

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())

新しく作成したツールをReActエージェントに追加します。LangGraphでは、コードは次のようになります。

tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>, 
				     tools=tools_agent1, 
				     prompt=<system_prompt>, 
				     debug=True, checkpointer= checkpointer)

表18-1プロンプト・ツールの構成プロパティ

プロパティ 入力してください 説明
llm オブジェクト LLM接続の詳細およびパラメータ
model_id 文字列 使用するモデルの識別子(例: "xai.grok-4")
モデルプロバイダ 文字列 LLMモデルのプロバイダ名(汎用など)
compartment_id 文字列 Oracle Cloud Infrastructure (OCI)コンパートメントOCID
endpoint 文字列 モデルのエンドポイントURL
prompt_template 文字列 動的挿入のために、{{variable}}形式の変数とともにLLMで使用されるプロンプト・テンプレート

テスト・エージェント・プロンプト・ツール

エージェントとは無関係にツールをテストするには、「テスト」タブをクリックして、各パラメータの値を入力します。プロンプトが、選択したLLMに送信されます。


「テスト」タブでエージェント・プロンプト・ツールが開きます

プロンプト・ツールが適切に定義され、文書化されていることを確認して、エージェントの結果を改善します。

エージェントへのプロンプト・ツールの追加

プロンプト・ツールをエージェントに追加して、選択したLLMに発行するパラメータ化されたプロンプトを定義できます。

  1. エージェントにナビゲートします。
  2. ツール・テンプレートから、プロンプト・ツールをキャンバスにドラッグ・アンド・ドロップします。
  3. 「構成」タブで、使用するLLMを選択し、LLMのプロンプトを指定します。「コード」 「コードとして入力」ボタンをクリックして、構成をJSONコードとして指定します。
  4. レスポンスの温度を0.0から1.0の間の値として指定します。0.0は厳密に事実に基づくレスポンスを提供し、1.0は最も創造的なレスポンスを提供します。
  5. 「適用」をクリックします 適用ボタン右向き矢印
  6. 構成で設定したパラメータの定義を指定します。「コード」 「コードとして入力」ボタンをクリックして、構成をJSONコードとして指定します。
  7. 適用ボタン左向き矢印 「Apply」をクリックします。
  8. オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。

RAGツール

RAGツールは、自然言語問合せをベクトル・ストアに発行し、問合せと格納されたドキュメントのセマンティック類似性に基づいてドキュメントを取得します。

ノート:

ナレッジ・ベースは、RAGツールを作成するための前提条件です。詳細は、「ナレッジ・ベース」を参照してください。

ビジュアルフローによるRAGツール

RAGツールでは、エージェント開発者が次のパラメータの値を指定する必要があります。


キャンバスでRAGツールが選択された状態でエージェントを開く

  • エージェント対応:
    • ツール名:自分および他のユーザーがその機能を識別するのに役立つツールのわかりやすい名前。
    • ツールの説明:ツールの概要を示す簡単なサマリー。
  • ツール構成:
    • ナレッジ・ベース: Oracle AI Data Platform Workbenchカタログの1つに格納されているナレッジ・ベース。
      エージェントRAGツール構成がナレッジ・ベース選択にオープンしています

エージェントは、エンド・ユーザーとの会話に基づいて問合せフィールドの値を設定します。この問合せフィールドは、自然言語問合せを使用します。

制限は、ツールがベクトル・ストアから取得するドキュメント・チャンクの数です。この値は、エージェント自体ではなく、エージェント開発者によって設定されます。

RAGのテスト・タブをクリックして、エージェントによって発行された問合せをシミュレートすることもできます。


「Query」および「Top K」フィールドが表示されたエージェントRAGツールAIツール定義セクション

LangGraphコードによるRAGツール

コードを使用してエージェントにRAGツールを構築するには、ビジュアル・フローと同じ設定およびパラメータを構成する必要があります。たとえば、RAGパラメータを次のように設定します。

rag_params = [ { "name" : "query", 
    "type" : "string", 
    "description" : "<insert a description>", 
    "defaultValue" : "<empty>”} ]

次に、RAG構成を設定します。

rag_config = { "catalog": "<catalog>", 
		  "schema": "<schema>", 
		  "knowledgeBase": "<knowledge-base-name>", 
		  "top_k": <number-of-documents-retrieved>, 
		  "llm": { 
			    "model_id" : "<model-name>",
			    "model_provider" : "<model-provider>", 
			    "compartment_id" : "<your-compartment-OCID>", 
			    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" } 
}

最後に、支援ユーティリティからcreate_langgraph_tool()ユーティリティ関数を使用してLangGraph互換ツールを作成します。 

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "RAGTool", 
			   conf=rag_config, 
			   params=rag_params) 
rag_tool = create_langgraph_tool(rag_conf.model_dump())

表18-2 RAGツールの構成プロパティ

プロパティ 入力してください 説明
llm オブジェクト LLM接続の詳細
catalog 文字列 データ・カタログ識別子
スキーマ 文字列 カタログ内のスキーマ
ナレッジベース 文字列 検索するナレッジ・ベースの名前またはキー
上位_K 整数 取得する上位一致ドキュメントの数

テスト・エージェントRAGツール

エージェントをAIコンピュート・クラスタにアタッチした後、「テスト」タブからRAGツールをテストできます。詳細は、Attach an Existing AI Cluster to an Agentを参照してください。

RAGツールをエージェントに追加する

エージェントに検索拡張生成(RAG)ツールを追加して、エージェントがレスポンスの生成時に関連する外部ナレッジを取得できるようにします。

  1. エージェントにナビゲートします。
  2. ツール・テンプレートから、RAGツールをキャンバスにドラッグ・アンド・ドロップします。
  3. 「構成」タブで、RAGツールが情報をプルするナレッジ・ベースを選択し、プルする情報を定義するためのプロンプトを指定します。「コード」 「コードとして入力」ボタンをクリックして、構成をJSONコードとして指定します。
  4. 「適用」をクリックします 適用ボタン右向き矢印
  5. 構成で設定したパラメータの定義を指定します。「コード」 「コードとして入力」ボタンをクリックして、構成をJSONコードとして指定します。
  6. 適用ボタン左向き矢印 「Apply」をクリックします。
  7. オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。

SQLツール

SQLツールを使用すると、エージェント開発者は、Oracle AI Data Platformカタログに登録された表に対して事前定義済のSQL問合せを実行できます。

設計時に問合せを記述し、必要なランタイム変数を定義します。エージェントはツールを呼び出すときにこれらの変数の値を提供し、その結果はエージェントが要約またはダウンストリーム・ノードに渡すことができる構造化行として返されます。


エージェントは「開発」タブにオープンします。エージェント・ノードのSQL_Agentがキャンバス上にあります。左ペインの「ツール・テンプレート」で「SQLツール」ノードが選択されています。

SQLツールでは、2つの問合せ言語がサポートされています。Spark SQLは、AIデータ・プラットフォームに格納された標準カタログ表に対して実行され、Sparkクラスタが必要です。Oracle SQLは、Oracle Autonomous AI Databaseなどの外部データベースに対して実行されます。ツールごとに方言を選択し、設定の復元は両方で同じです。

ノート:

SQLツールは、読取り問合せを対象としています。一般的なツールはSELECT文を実行し、行を返します。構成するカタログ、スキーマおよび問合せは、ツールに対してプライベートであり、エージェントには公開されません。エージェントには、ツール名、説明、およびAIツール定義(実行時変数)のみが表示されます。

ノート:

SQL問合せツールは、停止したクラスタを自動的に起動しません。そのため、Spark SQL問合せツールに使用されるSparkクラスタには、永久の期間が必要です。クラスタがアイドル・タイムアウトでスピン・ダウンできる場合、クラスタが停止すると、Spark SQL問合せは本番での動作を停止します。

静的問合せおよび動的問合せ

静的問合せは、エージェントによる実行時決定なしで、指定した内容を正確に返します。動的問合せには、実行時に値が設定されていることをエージェントに通知する1つ以上の{{variable}}プレースホルダが含まれます。プレースホルダごとに、名前、タイプ、オプションのデフォルト値、およびエージェントが値の選択に使用する説明を指定します。

たとえば、次の静的問合せは固定結果セットを返します。
SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name
リテラルを{{year}}プレースホルダに置き換えると、エージェントがパラメータ化できる動的問合せになります。 
SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = {{year}} 
ORDER BY customer_name

プレースホルダを追加すると、「AI Tool」定義ペインに各変数が移入されるため、そのタイプ、デフォルト値および説明を設定できます。

プレースホルダは、内部関数を含め、問合せの任意の場所に表示できます。次のSpark SQL問合せは、重大度値を大/小文字を区別せずに照合します:
SELECT incident_id, project_id, incident_date, incident_type, 
       severity, description, workers_involved, days_lost, 
       root_cause, corrective_action, reported_by, status 
FROM safety_incidents 
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')

各変数に明確な説明と適切なデフォルトを指定します。この説明は、有効な値をエージェントに知らせ、エージェントが値を指定しない場合のデフォルトが使用されます。


AIツール定義が変数SEVERITYで表示されます。この変数には、インシデント重大度レベル(メジャー、中程度、マイナー)の説明があります。

ノート:

プレースホルダ名では、大文字と小文字が区別されます。{{SEVERITY}}として記述され、{{severity}}として記述されたプレースホルダは、常に小文字を使用しないかぎり、2つの異なる変数として扱われます。

JSONとしての構成の編集

コード・ビューの切替えを使用して、SQLツール構成をJSONとして直接編集できます。これは、エージェント間でツールをコピーしたり、一括編集を行う場合に便利です。
{ 
  "catalogKey": "construction_data", 
  "schemaKey": "admin", 
  "query": "SELECT project_id, project_name, client_name, ...", 
  "isRowLimitEnabled": null, 
  "maxRows": null 
}

SQLツール・ノードの構成ペインが「パラメータ」タブに開きます。コード・ビューが分離され、「入力スキーマ」フィールドにサンプル・コードが表示されます。

行の制限

ツールが返す行数を制限するには、「戻す最大行数」を選択し、制限値を入力します。行制限により、パフォーマンスが保護され、エージェントに送信されるデータの量が制御されます。

この値は、エージェントが使用しているモデルに対して相対的に設定します。値を大きくすると、問合せが大きい行または大きいテキスト値を持つ列を返した場合に、エージェントが失敗する可能性があります。予期しないエージェント・エラーが表示される場合は、maxRowsを減らすことから始めます。

行制限は、問合せが実行される前に、SQL問合せ自体に適用されます。ほとんどのモデルは制限を検出し、エンド・ユーザーに表示します。静的問合せの場合、制限は使用可能な最初のn行を返します。


SQLツールの「構成」ペインが「返される最大行数」オプションにトリミングされました。このオプションが選択され、行制限として1000が指定されます。

ノート:

エンド・ユーザーに対して行制限を表示しない場合は、指示に従ってエージェントに指示します。

問合せの例

問合せの例およびSQLツール問合せの記述ガイドは、「問合せの例およびガイドの表示」ボタンから参照できます。


SQLツールの構成ページが表示されます。「問合せの例およびガイドの表示」ボタンが強調表示されています。

このガイドでは、様々な問合せパターンを示し、問合せパラメータに関する様々な推奨事項を示します。


SQLツールの例およびガイド・ダイアログが表示されます。

LangGraphコードを使用したSQLツール

ビジュアル・フローと同様に、問合せを作成して、LangGraphコードを使用してエージェントのSQLツールの作成を開始します。

sql_config = { "catalogKey": "adw23ai_phx", 
	  "schemaKey": "gold", 
	  "query": """Select ... from ... limit {{max_number}}""" }

SQL問合せの各パラメータは、名前、型、説明およびオプションでdefaultValueを使用してparams引数に記述します。

sql_params = [ {  "name" : "max_number", 
		    "type" : "string", 
		    "description" : "<your-description>", 
		    "defaultValue" : "<your-default-value>" } ]

最後に、支援ユーティリティからcreate_langgraph_tool()ユーティリティ関数を使用してLangGraph互換ツールを作成します。 

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "SQLTool", 
			   conf=sql_config,
			   params=sql_params) 
sql_tool = create_langgraph_tool(sql_conf.model_dump())

表18-3 SQLツールの構成プロパティ

プロパティ 入力してください 説明
カタログ・キー 文字列 カタログまたはデータベース接続の識別子
スキーマ・キー 文字列 カタログ/データベース内のスキーマ名
問合せ 文字列 SQL問合せ文字列には、{{}}にプレースホルダを含めることができます

テスト・エージェントSQLツール

「テスト」タブは、エージェント全体を実行せずに、ツールを単独で実行します。テストは両方の方言で同じように機能します。「テスト」タブを開き、各ランタイム・パラメータの値を指定(またはデフォルトを使用)し、「送信」をクリックして問合せを実行し、レスポンスを表示します。

ノート:

ツールをテストするには、エージェントがAIコンピュートにアタッチされている必要があります。AIコンピュート・ラベルが緑色で、選択したAIコンピュートがACTIVE状態の場合は、AIコンピュートがアタッチされます。

SQLコマンド・リファレンス

SQLツール問合せは、標準のSQL句から作成された読取り問合せです。Oracle SQL方言は、外部データベースに対してOracle SQLに従います。Spark SQL方言は、Delta Lake表である標準のカタログ表をターゲットとします。この標準カタログでは、現在、Delta Lake 3.2.0でSpark 3.5が実行されます。ほとんどの句は、標準のSQLに従うため、両方の方言で同じように記述されます。主な違いは、各方言が行数を制限する方法です。次の表に、SQLツール問合せで最も頻繁に使用される句およびキーワードを、各方言のフォームとともにリストします。

キーワードまたは句 目 的 Oracle SQL Spark SQL
SELECT 戻す列を選択します SELECT col1, col2
DISTINCT 一意の行のみを返す SELECT DISTINCT col SELECT DISTINCT col
FROM ソース表に名前を付けます。 FROM table_name FROM table_name
WHERE 条件による行のフィルタ WHERE col = value WHERE col = value
その他 条件の組合せまたは否定 a AND b OR NOT c a AND b OR NOT c
次に含まれる リスト内の任意の値に一致 col IN (a, b, c) col IN (a, b, c)
BETWEEN 包含範囲に一致 col BETWEEN x AND y col BETWEEN x AND y
LIKE テキスト・パターンに一致 col LIKE 'A%' col LIKE 'A%'
IS NULL 欠損値のテスト col IS NULL col IS NULL
ORDER BY 結果をソートします。 ORDER BY col DESC ORDER BY col DESC
GROUP BY 集計の行をグループ化 GROUP BY col GROUP BY col
HAVING グループ化された行のフィルタ HAVING COUNT(*) > 1 HAVING COUNT(*) > 1
参加 2つの表の行を結合 a JOIN b ON a.id = b.id a JOIN b ON a.id = b.id
AS 列の別名または表 col AS name col AS name
UNION ALL 2つの結果セットの結合 q1 UNION ALL q2 q1 UNION ALL q2
CASE 条件付きで値を返します。 CASE WHEN c THEN x END CASE WHEN c THEN x END
集計 行の集計 COUNT SUM AVG MIN MAX COUNT SUM AVG MIN MAX
行制限 行数を制限する FETCH FIRST n ROWS ONLY LIMIT n

ノート:

通常、行制限は自分で記述しません。返す最大行数の設定が適用されます。FETCH FIRSTおよびLIMITフォームは、問合せ内に明示的な制限が必要な場合にのみ役立ちます。

完全なSQL文法および各方言の背後にある問合せエンジンについては、次の参照を参照してください。

Oracle AI Data Platform SQL

Spark SQLおよびDelta Lake (標準カタログ)

標準カタログ表はデルタ・レイク表です。標準カタログは現在、Delta Lake 3.2.0でSpark 3.5を実行しています。

エージェントへのSQLツールの追加

エージェントにSQLツールを追加して、登録済外部カタログ内の構造化データ・ソースに対してSQL問合せを実行できるようにすることができます。

  1. エージェントにナビゲートします。
  2. ツール・テンプレートから、SQLツールをキャンバスにドラッグ・アンド・ドロップします。
  3. エージェントのコネクタ・ハンドルをクリックしてドラッグし、ツール・ノードに接続します。

    SQLツールSQL_1に接続されたエージェント・ノードSQL_agentを持つエージェント・キャンバス。

  4. SQLノードをダブルクリックして、構成パネルを開きます。
  5. ツールの名前と説明を指定します。この説明はエージェントに提供され、ツールをコールするタイミングを決定するのに役立ちます。
  6. 「問合せ方言」を選択します。
    • Spark SQLは、標準のAI Data Platformカタログに対して問合せを記述します。
    • Oracle SQLは、外部AI Data Platformカタログに対して問合せを書き込みます。

    ノート:

    Spark SQLには、AIデータ・プラットフォーム・ワークベンチ・ワークスペースで実行中のSparkクラスタが必要です。

    Spark SQLおよびOracle SQLラジアル・オプションを示すSQLツール構成。「Spark SQL」が選択されています。

  7. 「クラスタ」ドロップダウンから、実行中のSparkクラスタを選択します。「クラスタの作成」をクリックして、新しいSparkクラスタをプロビジョニングします。新規クラスタの作成のガイダンスは、カスタム・クラスタの作成を参照してください。

    ノート:

    SQL問合せツールは、停止したクラスタを自動的に起動しません。そのため、Spark SQL問合せツールに使用されるSparkクラスタには、永久の期間が必要です。クラスタがアイドル・タイムアウトでスピン・ダウンできる場合、クラスタが停止すると、Spark SQL問合せは本番での動作を停止します。

    SQLツール・ノードの「構成」ペインが「クラスタ」選択ドロップダウンにトリミングされました。

  8. 「カタログの参照」で、検索フィールドを使用してカタログを名前で検索するか、カタログ・マネージャをクリックしてカタログを検索します。

    SQLツール・ノードの「構成」ペインが「カタログの参照」フィールドにトリミングされました。

  9. 「問合せ」フィールドに、問合せを入力します。「問合せの例およびガイドの表示」をクリックして、コピーまたは適応できる既製のパターンを含むパネルを開きます。

    SQLツールの「構成」ペインが開き、「パラメータ」タブが選択されています。説明、問合せ、問合せの表示の例とガイド、およびフィールドを返す最大行が表示されます。

  10. 「返す最大行数」を選択して、問合せ結果によって返される行数を制限します。

    ノート:

    問合せでこの制限を超える行が返される可能性がある場合は、エージェントがより具体的なデータを検索できるように、{{customer_name}}や{{region}}などの検索パラメータを追加することを検討してください。
  11. 「AIツール定義」ペインで、問合せで設定した変数のタイプ、デフォルト値および説明を設定します。

    SQLツールの「構成」ペインが開きます。「パラメータ」タブが選択され、右側のペインにAIツール定義が表示されます。

  12. オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。