2026年7月3日金曜日

APEX 26.1のAIエージェントのレスポンス形式にJSONオブジェクトを指定する

Oracle APEX 26.1のAIエージェントは、レスポンス形式にJSONオブジェクトを指定できます。JSONスキーマを定義することにより、PL/SQL APIのAPEX_AI.GENERATEを呼び出したときに、レスポンスとして得られるJSONオブジェクトの形式を決めることができます。

実装サンプルとして、以下のAPEXアプリケーションを作成してみました。

AIエージェントにメッセージを送信し、レスポンスとして得られたGeoJSONのポリゴンをAPEXのマップ・リージョンに表示しています。LLMにOpenAI GPT-5.5を使用しています。


作成したAPEXアプリケーションのAPEXlang形式のエクスポートを以下に置きました。


以下より、作成したAPEXアプリケーションについて紹介します。

共有コンポーネントのAIエージェントとして、Get Polygon from a promptを作成しています。

生成AIのサービスにGPT-5.5を選択しています。このサービスは、あらかじめAPEXワークスペースに、生成AIとして作成しておきます。システム・プロンプトとして以下を記述します。

「プロンプトに関連する地域を推測し、その地域を囲むポリゴンをGeoJSONのPolygonとして生成してください。」


レスポンス形式のタイプにJSONオブジェクトを選択し、JSONスキーマとして以下を記述します。OpenAI GPT-5.5に出力させました。Claude Sonnet 5でレビューしています。


オンライン・ヘルプに記載されていますが、タイプにJSONオブジェクトを指定した場合、このAIエージェントを呼び出せるのは、PL/SQL APIのAPEX_AI.GENERATEに限られます。詳細の静的IDはAPI呼び出しの際に使用されます。
Select the type of response that should be generated by the AI provider.
  • Text: Plain text
  • JSON Object: A JSON object that will adhere to a specific JSON schema. Note that AI Agents which return a JSON object can currently only be referenced by the apex_ai.generate PL/SQL API.

このスキーマ定義はChat Completions APIであれば、response_formatのjson_schemaとして送信されます。このAIエージェントはツールを含みませんが、ツールを含むこともできるはずです（まだ動作確認ができていません）。ユーザー向けの最初のレスポンスが、設定したJSONスキーマに従ったJSONオブジェクトになります。

また、JSONスキーマのオンライン・ヘルプに記載されていますが、生成AIが返すレスポンスについて、データベースが26aiであればJSONオブジェクトの検証を行いますが、それ以前のバージョン（つまり19c）は検証しないようです。性能の低いLLMを使用する場合、レスポンスが指定したJSONスキーマに従わないことがあるので注意が必要です。
The JSON Schema based on which the JSON object is generated.

Note that the referenced AI provider might not support the full scope of the JSON Schema specification. Consult the documentation of the individual AI providers for more information.

Starting with database 26ai, the incoming JSON object is automatically validated against the JSON Schema. For earlier database versions, Oracle recommends validating the JSON object programatically before further processing.
プロンプトからGeoJSONのポリゴンを返すAIエージェントの説明は以上です。

ホーム・ページに、生成されたポリゴンをマップに表示する機能を実装しています。

ホーム・ページにマップ・リージョンとレイヤーを作成します。とりあえずポリゴンが表示できればよいので、最低限の実装にしています。

マップ・リージョンはJavaScriptから扱えるように、HTML DOM IDとしてMAPを設定しています。


レイヤーは、GeoJSONのポリゴンを表示するように構成します。ただし、AIエージェントを呼び出して得られるポリゴンだけを表示するため、データ・ソースは空にします。

属性の名前をPolygonとし、タイプとしてポリゴンを選択します。

ソースの位置にデータ・ベースを選択し、タイプにSQL問合せ、SQL問合せとして以下を記述します。必ずfalseとなる条件を設定しているため、１行も選択されません。

select 'label' as label, null as polygon from dual where 1<>1

列のマッピングのジオメトリ列のデータ型としてGeoJSONを選び、GeoJSON列にPOLYGON（SELECT文に含まれる列POLYGON）を選択します。


描画されるポリゴンの外観を設定します。

塗りつぶしの色を赤、塗りつぶしの不透明度を0.5、ストロークの色も赤にしています。

レイヤーを取り出すファンクションgetLayerIdByNameの引数は、レイヤーの名前です。詳細の静的IDではありません。


プロンプトはページ・アイテムP1_PROMPTに入力します。タイプはテキスト・フィールドにしています。


AIエージェントが返すポリゴンは、ページ・リージョンP1_POLYGONに保持します。タイプは非表示で良いのですが、データを確認するためテキスト領域としています。


ボタンDRAWを作成します。動作のアクションとして、APEX 26.1の新機能であるトリガー・アクションを設定します。


ボタンDRAWをクリックしたときに最初に実行されるトリガー・アクションとして、Get a polygon from a promptを作成します。

PL/SQLで以下を記述します。先ほど作成したAIエージェントをAPEX_AI.GENERATEから呼び出しています。
begin
    :P1_POLYGON := apex_ai.generate(
        p_agent_static_id => 'get-polygon-from-a-prompt'
       ,p_prompt => :P1_PROMPT
    );
end;
送信するアイテムにP1_PROMPT、戻すアイテムにP1_POLYGONを設定します。

サーバー側で処理している間にスピナーを表示するように、処理中の表示をオンにします。この設定はAPEX 26.1の新機能です。

実行の結果を待機をオンにし、ポリゴンをP1_POLYGONに設定した後に、後続のトリガー・アクションが動作するようにします。


後続のトリガー・アクションとして以下のJavaScriptのコードを実行します。初版はOpenAI GPT-5.5に書いてもらって、一部Claude Sonnet 5に書き直してもらいました。コメントはブログの著者が書いています。


ページ・アイテムP1_POLYGONに保持されているGeoJSONのポリゴンを、マップに描画しています。


今回作成したAPEXアプリケーションの説明は以上です。

生成AIの出力フォーマットを規定することにより、後続の処理の実装（今回の例ではマップへの描画）が容易になります。

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完
投稿者 時刻:
ラベル: ,