formio-uag

Universal Agent Gateway（UAG）は、Model Context Protocol（MCP）を活用し、Form.io を使用したプロセス内エージェント自動化を実現します。UAG は、JavaScript Rendererが人間に提供するものと同じものを AI エージェントに提供します。つまり、Form JSON スキーマを解釈し、理解しやすい形式に変換します。UAG の場合、Form JSON モデルを AI が読み取れる Markdown 形式に変換することで、エージェントが収集対象データの目的と構造を簡単に理解できるようにします。

---

UAG が実現する主なシナリオは 2 つあります。

• 非構造化の「チャット」入力から決定論的なフォーム送信へ：Form.io フォームの JSON スキーマを使用して、自然言語による会話形式の入力から、決定論的な構造化データオブジェクトを生成します。

このフローの動作する例については、Conversation Form Exampleをお試しください。

• エージェント型 Form.io ワークフロー：UAG は、既存の送信データと「コンテキスト」基準をもとに、ワークフローのシナリオ内で AI エージェントが独自のデータと分析を提供できるようにします。Form.io の申請フォームを使用した大学出願プロセスを示す以下の例では、この主なシナリオの仕組みを説明しています。

エージェント型ワークフローの詳細については、専用のエージェント型ワークフローセクションをご覧ください。このフローの動作する例については、Agentic Workflow Exampleをお試しください。

---

UAG が提供する多くの利点の 1 つは、AI の処理サイクルに動的コンテキストを注入できることです。これは、簡単に変更してあらゆる環境にデプロイできる動的な Form JSON スキーマによって実現されます。そのため、アプリケーションを更新したり、プロセス内のエージェントを再トレーニングしたりする必要はありません。これにより、実行中の既存プロセスに動的なコンテキストの変更をシームレスに注入でき、UAG を利用するエージェントの動作が自動的に更新されます。

試してみましょう！

このリポジトリには、Docker Compose を使って UAG とともに Form.io サーバーを起動する動作するサンプルが 3 つあります。作成するものに合ったサンプルを選んでください。

サンプル	パターン	ライセンス
カスタムモジュール	会話形式、既存のクライアント。 Claude Desktop をフォームに接続して、「新しい顧客を追加したいです」のように話しかけます。カスタムモジュールとして構築されているため、エージェントが実行できる操作はロールと権限によって決まります。	オープンソース — 無料
会話フォーム	会話形式、独自の UI。 質問のすべてがフォームから取得されるチャットアプリケーションです。約 200 行で、コードにフィールド名はありません。フォームを編集すると、会話の内容も変わります。	オープンソース — 無料
エージェント型ワークフロー	自律型。 送信内容を受け取るとエージェントが起動し、ルーブリックに照らして評価して判断を書き戻します。それを受けて 2 つ目のエージェントが起動します。人もチャットウィンドウも必要ありません。	エンタープライズ

また、フロービューアーもあります。エージェント型の実行におけるすべての処理をリアルタイムで表示する小さなプロキシで、エージェントが実際に何をしているのかを最も手早く確認できます。

このリポジトリのドキュメント

このファイルは、UAG の概要、フォームの設定方法、デプロイ方法、トラブルシューティングを説明するメインリファレンスです。その他のドキュメントは、説明対象のコードの近くにあります。

ドキュメント	内容
README.md（このファイル）	概念、エージェント型ワークフローの設定、MCP ツール、デプロイ、環境変数、トラブルシューティング。
module/Readme.md	カスタムモジュールの作成 — 独自の MCP ツール、フォームアクション、事前定義済みフォームとリソース、設定のオーバーライドを追加し、Docker コンテナーにマウントする方法。
integrations/claude/Readme.md	Claude 連携 — API エンドポイントとコマンド、Node または Docker での実行方法、環境変数、Form.io Webhook アクションからの起動方法。
examples/custom-module/Readme.md	サンプル — Claude Desktop から会話形式で操作するカスタムモジュール。エージェントが実行できる操作はロールと権限によって決まります。
examples/conversation-form/Readme.md	サンプル — 質問のすべてがフォームから取得される独自のチャットアプリケーション。
examples/agentic-workflow/Readme.md	サンプル — 2 つのエージェントペルソナを連携させた、Webhook をトリガーとする自律型ワークフロー。
examples/flow-viewer/Readme.md	エージェント型の実行におけるすべての処理をリアルタイムで表示する小さなプロキシ — トークンリクエスト、各ツール呼び出し、書き戻しを確認できます。エージェントが何をしているのかを最も手早く確認できます。
examples/custom-module/module/templates/Readme.md	Lodash テンプレートを使って、UAG がエージェントに返すレスポンステンプレートをオーバーライドする方法。
test/e2e/Readme.md	エンドツーエンドテストスイート — 3 つのレイヤー、それぞれの対象範囲、実行方法。

---

エージェント型ワークフロー

UAG の強力な機能の 1 つが、agent_provide_data ツールです。このツールを使うと、汎用的にトレーニングされたエージェントに、既存の送信データを分析し、設定可能な 基準 に従って独自のデータを生成する方法を指示できます。従来、この動作を実現するには専用にトレーニングされたエージェントが必要でしたが、Form.io プラットフォームが提供する動的な設定機能を活用できませんでした。このツールは、自動化されたワークフローの一環としてエージェントが独自のデータを正確に生成できるよう、必要な「コンテキスト」を汎用的にトレーニングされたエージェントに提供することで、この目的を実現します。この機能は、構造化データを理解し、UAG から提供された設定済みの 基準 の「コンテキスト」に従って独自のデータを追加できる AI エージェントを活用する、エージェント型ワークフローで UAG を使用する場合に特に役立ちます。

たとえば、大学出願プロセスのバックエンド管理を自動化したいとします。この例では、出願者が、学業、課外活動、表彰、ボランティア活動、場合によってはエッセイなど、さまざまなデータ項目からなる申請書を提出します。従来、このような申請書は、合格候補者の資格を評価するために管理者が審査していました。以下の図に示すように、agent_provide_data ツールを使うことで、このプロセスを自動化できるようになりました。

この機能を実現するために、agent_provide_data ツールは以下の情報を使用し、それを汎用的にトレーニングされたエージェントに渡して、独自の申請データを生成します。

• 既存の送信データ：エージェントが独自のデータを追加するには、設定済みの 基準 に従って分析するデータとして使用できる、既存の申請データが必要です。
• 基準：データを分析する際に従う 基準 をエージェントに提示するとともに、必須フィールド に入力する方法を指示するコンテンツです。
• 必須フィールド：agent_provide_data プロセスの一環として、エージェントが入力する必要のあるフォームフィールドです。

セットアップ

フォームで agent_provide_data ツールを使用するには、まず AI エージェントが読み取り、使用するフォーム内のセクションを指定する必要があります。これは、フォームの「事務局記入欄」のような項目に似ていますが、そのセクションの値を入力するのは人間ではなく、自動化された AI エージェントです。agent_provide_data ツールで使用できるようフォームを設定するには、基準 と エージェントフィールド の 2 種類のフィールドを追加できます。

セットアップは 4 つの手順で構成され、すべて必須です。

1. フォームに uag のタグを付けます（下記参照）。これを行わないと、UAG はフォームを認識しません。
2. エージェントが何をすべきかを学習するための 基準 コンテンツコンポーネントを追加します。
3. エージェントが入力できる エージェントフィールド を追加します。
4. 送信時にエージェントを起動する Webhook アクション を追加します。Claude との統合を参照してください。この手順には Enterprise Server が必要です。アクションでリクエストヘッダーを設定し、ペイロードを変換する必要があるためです。Community Edition では、申請データの作成後に独自のコードから統合を起動してください。

4 つの手順すべてを含む動作例については、エージェント型ワークフローの例を参照してください。

フォームに uag タグを付ける

UAG は、uag タグが付いたフォームのみを登録します。このタグがないフォームは、すべてのエージェントとすべてのツール（get_forms を含む）から見えません。フォームビルダーでは Form Settings → Tags で設定します。フォームの JSON では次のようになります。

"tags": ["uag"]

エージェントがフォームは存在しないと言い張る場合は、まずこの設定を確認してください。タグがない場合、どこにもエラーは表示されず、エージェントから見るとフォームは存在しないためです。また、新しくタグを付けたフォームが反映されるのは、次回のプロジェクトキャッシュの期限切れ後です。そのため、最大で PROJECT_TTL 秒かかる場合があります（プロジェクトキャッシュと TTL を参照）。

エージェントの「Criteria」コンポーネント

最初に設定する必要があるのは、AI エージェントにデータの解釈方法を指示する特別な コンテンツコンポーネント です。たとえば、大学出願エッセイの提出内容を評価する方法を AI エージェントに指示するために作成された、Criteria コンテンツブロックを以下に示します。

このコンテンツは、提出データの分析方法や理解方法を学ぶ必要がある新入社員向けの手順書を書くように作成します。また、基準に設定されたフォームの値を入力する方法を AI エージェントに指示するためにも使用します。この基準を作成したら、uag というプロパティを追加して UAG フィールドとして「フラグ」を付ける必要があります。このプロパティの値は、エージェントの persona として扱います。これにより、複数のエージェントに異なる役割を担わせ、提出データを分析して各自の値を出力できます。さらに、「criteria」コンテンツには、値が criteria の uagField プロパティも設定する必要があります。正しく設定された uag criteria コンテンツコンポーネントは、以下のようになります。

この Criteria コンテンツコンポーネント をフォームに追加したら、次はエージェントに入力させるフィールドを追加します。これらは エージェントフィールド と呼ばれます。

エージェントフィールド

フォーム内のどこにでも、エージェントフィールドとしてフラグを付けられるフィールドをドラッグ＆ドロップできます。上記の例のフォームに「事務局使用欄」セクション（パネルなど）があるとします。このパネル内で最初に表示されるのは、後続のフィールドへの入力方法を指示するコンテンツコンポーネントです。これが先ほど説明した Criteria です。その次に、エージェントが入力するフィールドが続きます。Criteria コンテンツコンポーネントと同じ値を持つ uag プロパティが設定されたフィールドは、すべてエージェントフィールドとして使用されます。

たとえば、大学出願エッセイ用のフォームを作成したとします。Criteria の下には、提示された Criteria に従ってエッセイを「採点」するためのフィールドを配置できます。次のようになります。

これらの各フィールドにエージェントフィールドとして「フラグ」を付けるには、Criteria コンテンツに設定したものと同じペルソナフラグを持つ uag プロパティを追加するだけです。

ネストされたコンポーネント フィールドの集合に uag プロパティで「フラグ」を付けることもできます。その場合は、すべてのフィールドを ネストされたコンポーネント（パネル、コンテナー、フィールドセットなど）で囲みます。そうすると、このネストされたコンポーネント内のすべてのフィールドが、そのペルソナを持つエージェントのコンテキストに追加されます。

フォームごとの複数のペルソナ

フォームごとに複数のペルソナを設定することもできます。プロセス内で、互いに独立した複数の評価を行う必要がある場合にとても便利です。たとえば、上に示したフローチャートの図を見ると、大学出願フォームがあります。最初のエージェント型評価は、出願者がフォームを送信したときに行われ、出願が受理されるかどうかを判定します。その後、出願者が受理された場合、奨学金や学資援助を授与するために、まったく異なる評価を行う必要があります。その場合は、提出データをそれぞれ異なる観点から評価するため、基準もまったく別のものが必要になります。

これを実現するには、各コンポーネントの uag プロパティの値を、そのフィールドに適用するペルソナに応じて「フラグ付け」するだけです。上の例では、出願者を受理すべきかどうかを評価する Content コンポーネントを追加し、そのコンテンツに次の uag プロパティを指定します。uag="application"。出願の承認にあたり AI エージェントが入力する必要のあるフィールドにも、uag="application" プロパティを設定します。次に、フォームの別のセクションに、学資援助担当 AI エージェントの基準を記述した別の Content コンポーネントを作成します。このコンテンツには uag="finance" プロパティを設定します。学資援助担当 AI エージェントが入力する必要のあるフィールドにも、uag="finance" を設定します。これにより、複数の汎用トレーニング済みエージェントに、エージェント型プロセスの該当部分にのみ関連するデータの読み取り方や解釈方法を動的に「教える」ことができ、柔軟で動的な AI 連携を実現できます。

エージェントのフィールドは、評価基準の隣に配置する必要はありません。あるパネルの status フィールドに uag="application" を設定し、その隣のフィールドに uag="finance" を設定できます。これにより、ワークフローの単一フィールドを、その段階の担当ペルソナに割り当てることができます。

ペルソナを連結してワークフローを構成する

フォーム上の複数のペルソナは、後続のペルソナを起動する仕組みがあって初めて役立ちます。各ペルソナは送信データを書き込むため、2番目のペルソナを起動する自然なきっかけは、最初のペルソナによる書き込みです。

これは、create ではなく update で実行される2つ目の Webhook アクションを設定し、最初のペルソナが設定するフィールドの条件で絞り込むことで構成します。

{
  "name": "webhook", "handler": ["after"], "method": ["update"], "priority": 0,
  "condition": {
    "conjunction": "all",
    "conditions": [
      { "component": "status", "operator": "isEqual", "value": "scholarshipEvaluation" }
    ]
  },
  "settings": {
    "method": "post",
    "url": "http://formio-uag-claude:3300/agent/claude/agent_provide_data",
    "headers": [{ "header": "x-token", "value": "<your project API key>" }],
    "transform": "payload = {formName: 'application', submissionId: payload.submission._id, persona: 'finance'};",
    "block": false
  }
}

大学出願ワークフローでは、入学審査ペルソナは奨学金の審査対象となる出願者に限り、status を scholarshipEvaluation に設定します。そのため、学資援助ペルソナが起動するのは該当する出願のみです。単に受理された出願者や不採用となった出願者については、起動されません。

ループを避けてください。 2番目のペルソナも送信データに書き込むため、同じ update Webhook が再び実行されます。各ペルソナ自身の書き込みによって、そのペルソナを起動した条件に再び一致しないようにしてください。上の例では、学資援助ペルソナが status を scholarshipGranted に設定するため、条件に一致しなくなり、ワークフローが終了します。ペルソナの実行後も条件が真のままになると、コンテナを停止するまで無限ループが発生し、API クレジットを消費し続けます。

この2つのペルソナを使ったワークフローの、完全な実行可能バージョンはエージェント型ワークフローの例にあります。

統合

UAG の「エージェント化」を促進するため、汎用的にトレーニングされた AI エージェントと直接通信し、UAG を活用して AI エージェントの動作を自動化できる「統合」も提供しています。これには、AI エージェントのプロセスを起動するとともに、デプロイ済みの UAG に接続する単一の API エンドポイントが含まれます。これらの API エンドポイントは、フォーム内のシンプルな Webhook アクションを使って起動でき、フォームの送信をきっかけにエージェントプロセスを開始できます。以下は、特定の統合を使って単一の API 呼び出しでエージェントタスクを実行する方法を示す図です。

各統合は独自の MCP クライアントを実行し、UAG に向けて接続するため、これらを動作させるうえで UAG をパブリックにアクセス可能にする必要はありません。統合から到達可能であればよく、たとえばプライベート Docker ネットワーク経由や localhost 上で接続できます。

これらの統合は integrations フォルダー内にあります。自動化されたエージェントワークフローを実現するため、次の 統合 が提供されています。

• Claude Integration

各統合の仕組みを確認するには、いずれかの統合リンクをクリックしてください。

統合のバージョン互換性

統合のバージョンは UAG とは独立して管理されます。UAG とコードを共有しておらず、それぞれが独自の MCP クライアントを実行して MCP/HTTP 経由で UAG と通信します。そのため、統合のリリースが UAG のリリースを意味するわけではなく、その逆も同様です。両者のバージョン番号を一致させても、役に立つどころか誤解を招きます。

この表を使って、互換性のある組み合わせを選択してください。各行には、統合の各バージョンが動作することが確認されている UAG の範囲を記載しています。

統合	バージョン	互換性のある UAG バージョン	備考
@formio/uag-claude	1.3.x	>= 1.12.0	現行。
@formio/uag-claude	1.2.x	1.10.0 – 1.11.x

各統合のバージョンが更新されたリリースでは、両方の成果物が公開されます。

• npm: @formio/uag、@formio/uag-claude
• Docker Hub: formio/uag、formio/uag-claude

行を追加する場合： 統合独自の package.json のバージョンを更新してください。CI は次のリリースタグで npm と Docker Hub に公開し、そのバージョンがすでに公開済みの場合は自動的にスキップします。そのため、コアのみのリリースでは変更のない統合は再ビルドされません。

examples/ の compose ファイルはタグなしで formio/uag と formio/uag-claude を参照しているため、常に最新のリリースを取得し、古い状態になることはありません。再現可能なスタックが必要な場合は、上記の表から互換性のある組み合わせを選び、両方のイメージを固定してください。

---

技術概要

UAG は、多数の機能レイヤーで構成されていると考えることができます。各レイヤーは、大きく分けて動的なコンテキストの取得、または決定論的なデータ構造の送信のいずれかを担います。UAG では、以下のレイヤーを活用しています。

1. MCP インターフェース：UAG のエントリーポイントは、AI エージェントとサーバー上で実行されるツールの間に位置する MCP インターフェースです。
2. 認可：MCP 仕様の一環として、AI エージェントとバックエンドサービス間のすべてのやり取りでは、OIDC（PKCE）認証を利用した認可プロセスを通過する必要があります。ただし、UAG はこのプロセスをさらに拡張し、Form.io がすでに提供している認証方式の柔軟性に加えて、OIDC（PKCE）認証レイヤーを追加しています。そのため、SAML、Form.io 認証、OIDC、または Form.io プラットフォームを通じたカスタム認証プロセスを使用している場合でも、UAG で認証できます。
3. 動的なコンテキストを提供する事前定義済み MCP ツール：UAG は MCP を利用し、Form.io プラットフォームで互換性があるものとしてマークされたフォームとリソースに基づいて、AI エージェントに動的なコンテキストを提供する複数の事前定義済みツールを提供します。これらのツールについては、以下のセクションで詳しく説明します。
4. カスタムツール（カスタムモジュールで提供）：これにより、開発者は Form.io のフォームや送信データ構造を活用する新しいツールを導入し、AI エージェントに追加機能を提供できます。これにより、特定のユースケースで所定の目標を達成するための、カスタムエージェントとのやり取りが可能になります。
5. カスタムアクション（カスタムモジュールで提供）：AI エージェントから提供されたすべてのデータがサニタイズおよび検証された後に実行される、組み合わせ可能なミドルウェアを開発者が作成できます。これにより、AI エージェントから収集したデータを、任意のバックエンドシステムやワークフローと連携させることができます。
6. 組み込みアクション：モジュールを通じて導入されるカスタムアクションに加え、UAG は既存のアクションもいくつかサポートしており、任意のフォームまたはリソースに割り当てることができます。たとえば、AI エージェントによる送信が行われるたびに、任意のエンドポイントに REST API 呼び出しを送信する Webhook アクションがあります。これは、AI エージェントとのやり取りをきっかけにバックエンドのワークフローを開始する、任意のサーバーレス関数を指定するために使用できます。
7. 事前定義済みフォームとリソース（カスタムモジュールで提供）：開発者は、AI エージェントにデフォルトのデータ構造を提供するモジュールをリリースできます。特定の目標を達成するモジュールを作成する際、その目標に必要なデータ構造が、フォームまたはリソースで定義された所定のフィールドセットに従う必要がある場合に便利です。たとえば、開発者が UAG 用の CRM モジュールをリリースする場合、そのモジュールで、ほとんどの CRM 実装に一般的に含まれるデフォルトの 顧客 および 会社 リソースも提供するのが妥当です。
8. カスタムデータベース（カスタムモジュールで提供）：デフォルトでは、UAG は「Submission Proxy」を介してデータを収集および取得し、データは REST API を通じて Enterprise Server プロジェクトまたは Open Source サーバーに送信されます。ただし、これを変更して、データをデータベースとの間で直接送受信することもできます。これは、UAG が提供するデータベースインターフェースを通じて実現できます。詳しくは、Module のドキュメントを参照してください。この機能を利用するには、UAG が Enterprise Server に接続されている必要があります。

以下の図は、これらすべてのレイヤーがどのように構成され、UAG を形成しているかを示しています。

動的コンテキストを提供する事前定義済み MCP ツール

UAG が提供する以下のツールについて説明します。

ツール名	ツールの説明
get_forms	AI エージェントに、利用可能なフォームの一覧を提供します。 uag のタグが付いたフォームのみを返します。
get_form_fields	AI エージェントが、ユーザーは特定のフォームを使用する意図があると推測した場合、このツールは、そのフォームを送信するために必要なすべてのフィールドの概要（フィールドのデータパスを含む）をエージェントに提供します。
get_field_info	get_form_fields を使用してフィールドが特定された後、このツールは、検証、条件設定、入力形式など、要求されたフィールドに関する具体的な情報を提供します。 このツールは、MCP サーバーに送信するデータの形式と構造を AI エージェントに指示します。
collect_field_data	AI エージェントが、必要な情報をユーザーから動的に収集できるようにします。ユーザーの入力を複数のフィールドに一度に解析でき、必要に応じてユーザーに追加情報を求めます。 このツールは、複雑で構造化されたデータ収集に対応しており、入れ子になったフォームやデータグリッドなど、入れ子または複数値のフィールドと互換性があります。
confirm_form_submission	フォームを送信する前に、収集したすべてのデータの概要を提示するために使用します。
submit_completed_form	ユーザーから収集したすべてのデータを送信し、フォームの送信内容を作成できる機能を AI エージェントに提供します。
find_submissions	ユーザーの自然言語によるリクエストを、送信内容または特定の送信内容の特定フィールドに対するクエリとして解析できるようにします。
submission_update	未入力のフィールドを補完するか、許可されている場合は既存のフィールドを更新して、既存の送信内容を更新できる機能を AI エージェントに提供します。既存のフィールド値のコンテキストを AI エージェントに提供し、インラインでの変更や編集を可能にします。
agent_provide_data	設定可能な Criteria で定義されたルールに従って、AI エージェントが既存の送信データを分析できるようにします。その後、submission_update ツールを使用して、特定の persona に設定されたフィールドに生成データを提供するようエージェントに指示します。このツールセットの詳細については、エージェント型ワークフローセクションをご覧ください。
fetch_external_data	リソースコンポーネント、URL 付きのセレクト、またはデータソースコンポーネントを使用して、フォームのワークフローに外部データを取り込めるようにします。

カスタムモジュール

UAG は、AI エージェントと動的な JSON フォームの間のやり取りを可能にするスタンドアロンシステムとして使用できますが、このプラットフォームの真価は、開発者がカスタムモジュールとツールを使って機能を拡張し、業界固有のユースケースを解決するときに発揮されます。開発者は、業界固有のテクノロジーとのやり取りを実現するために、カスタムツール、アクション、事前定義されたリソースとフォームを導入する Module を作成できます。以下の仕組みを使って、カスタム統合機能を実現できます。

1. 事前定義されたフォームとリソース：Form.io のテンプレートシステムを使用すると、カスタムモジュールに、複数のフォーム、リソース、アクション（およびそれらに関連するロールと権限）を含む Form.io プロジェクトのテンプレートエクスポートを含めることができます。モジュールを使用すると、これらのアセットが自動的に「登録」され、AI エージェントがすぐに認識できるようになります。
   たとえば、モジュールに「First Name」、「Last Name」、「Email」フィールドを持つ Customer リソースが含まれているとします。その場合、AI エージェントに「新しい Customer を追加したい」と伝えるだけで、エージェントは顧客データ構造のコンテキストを自動的に認識し、リクエストの意図を正確に理解します。
2. カスタムアクション：アクションは、構成可能な Express.js ミドルウェア関数を任意のフォームやリソースに関連付け、AI エージェントが送信したデータが適切なデータ検証とサニタイズを通過した後に実行できる、組み合わせ可能なミドルウェア関数として考えることができます。バックエンドのプロセスやワークフローとのカスタム統合に使用できます。
3. カスタムツール：カスタムアクションの提供に加えて、モジュールではカスタム MCP ツールを導入し、業界固有の目的に応じて、UAG と AI エージェントの間に特別なやり取り機能を提供できます。
4. カスタム認証：モジュールでは、認証に関するカスタム要件をサポートするために、「authentication」ランディングページを変更することもできます。
5. 動作のオーバーライド：モジュールでは、UAG のデフォルトの動作を「オーバーライド」することもできます。これにより、特定のモジュールを使用するユーザーは、業界固有のニーズに応じて、ツールや応答を「調整」し、より良い結果を得られます。

Form.io は、開発者が GitHub と NPM を通じて独自のカスタムモジュールを構築し、より広いコミュニティに貢献できるようにすることを目指しています。

カスタムモジュールの使用

カスタムモジュールを開発したら、誰でもそのモジュールを（NPM 経由で）インストールして、次のように簡単に使用できます……

_{これはあくまで例です。}

import { UAGServer } from '@formio/uag';
import { ExampleUAG } from '@example/uag';
import Express from 'express';
try {
    (async function () {
        const server = new UAGServer();
        server.use(ExampleUAG);
        const app = Express();
        app.use(await server.router());
        const port = process.env.PORT || 3200;
        app.listen(port, () => {
            console.log(`Form.io UAG server running on port ${port}`);
            console.log(`Visit http://localhost:${port} to access the application`);
        });
    })();
} catch (error) {
    console.error('Failed to start server:', error);
    process.exit(1);
}

独自のカスタムモジュールの構築を始めるには、Modules Readme のヘルプドキュメントをご覧ください。

UAG のデプロイ

以下のセクションでは、UAG の実行インスタンスを作成して Form.io Platform に接続し、AI エージェントが使用できるように設定する手順を説明します。

このドキュメントでは、Form.io Open Source で UAG を使用する方法を説明します。Form.io Enterprise で UAG を使用する方法については、https://help.form.io/uag をご覧ください。

エージェントの接続方法

デプロイ前に、UAG の /mcp エンドポイントへの接続をどちら側から開始するかを決めておくとよいでしょう。この判断によって、UAG をインターネットからアクセス可能にする必要があるかどうかが決まります。

接続モデル	MCP クライアントを実行する側	UAG にパブリックドメインが必要か
ローカル MCP クライアント	UAG と同じ環境で実行される独自のアプリケーションまたはインテグレーション	いいえ。 UAG はそのプロセスからアクセスできればよく、http://localhost:3200 やプライベート Docker ネットワークのアドレスで問題ありません。
リモート MCP クライアント	UAG に接続するホステッドエージェント（Claude.ai および Claude Desktop のコネクター、Anthropic MCP コネクター、その他のリモート MCP ホスト）	はい。 エージェントがパブリックインターネット経由で /mcp と OAuth ディスカバリーエンドポイントにアクセスできる必要があります。

ローカル MCP クライアントでは、アプリケーションが UAG に向けて接続し、自らツールを呼び出して、その結果を使用するモデルに渡します。外部から接続されることはないため、UAG をネットワーク内だけに置いたまま運用できます。Claude インテグレーションはこの方式で動作します。また、開発者のマシン上でスタック全体を実行する場合も含め、サーバー間や Webhook 起動の自動化に推奨される方式です。

公開されている Claude インテグレーションイメージを使用する場合は、formio/uag-claude:1.3.0 以降が必要です。それ以前のイメージは MCP サーバーの URL を Anthropic API にリモートコネクターとして渡すため、API が UAG に接続し、パブリック URL が必須でした。古いイメージでプライベートアドレスを指定すると、Anthropic API から Connection error while communicating with MCP server という内容の 400 エラーが返ります。これは UAG の障害のように見えますが、実際にはそうではありません。

リモート MCP クライアントでは、エージェントがネットワークの外部にあり、こちらに接続してくるため、/mcp と .well-known OAuth ディスカバリーエンドポイントが HTTPS 経由でパブリックにアクセス可能である必要があります。また、BASE_URL にはそのパブリック URL を設定する必要があります。ドメインと URL の設定を参照してください。

どちらの方式も、同じ UAG デプロイに対して同時に使用できます。

ローカル MCP クライアントの認証

リモートエージェントは、ブラウザーを使った OAuth（PKCE）フローで認証します。ローカルクライアントにはブラウザーがないため、client_credentials グラントを使用して {{ BASE_URL }}/auth/token にサーバー側キーを送信し、アクセストークンと交換します。その後、そのトークンを Bearer トークンとして /mcp リクエストに含めます。

client_id にはプロジェクト名をプレフィックスとして付ける必要があります。オープンソースデプロイの場合、プロジェクト名は formio-oss です。

POST /auth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "formio-oss-x-admin-key",
  "client_secret": "{{ ADMIN_KEY }}"
}

Enterprise の場合は、プロジェクトエンドポイントに記載されているプロジェクト名をプロジェクト API キーと組み合わせて使用します。たとえば、"client_id": "myproject-x-token" と "client_secret": "{{ PROJECT_KEY }}" を指定します。

レスポンスには access_token が含まれます。これを Authorization: Bearer {{ access_token }} として UAG に渡します。トークンの有効期限は JWT_EXPIRE_TIME に従うため、長時間実行するクライアントではトークンをキャッシュし、有効期限が切れる前に更新してください。実装例については、integrations/claude/auth.js を参照してください。

実行環境

現在、UAG で動作する実行環境は次の 2 つです。

• Docker
• Node.js (Express)

Docker

UAG を Docker で実行すると、AWS や Azure などの一般的なホスティング環境で、幅広いデプロイ方法を利用できます。また、Kubernetes や Docker Compose などの一般的なオーケストレーションランタイムも使用できます。UAG の実行に使用するコンテナーは次のとおりです。

formio/uag

このコンテナーは、次の 2 つの方法で実行できます。

• Docker-Compose.yml - 推奨方式です。複数コンテナーの Docker Compose スタックとしてデプロイします。
• Docker Run - 一般的な docker run コマンドを使用するスタンドアロンコンテナーです。

Docker Compose（推奨）

UAG の起動には、Docker Compose の使用を推奨します。これにより、複数のコンテナを 1 つのインスタンス内で実行するようにオーケストレーションでき、デプロイメントをよりシームレスかつ簡単に管理できます。以下は、Form.io UAG と Form.io OSS サーバーの両方を同じインスタンスで実行する簡単な例です。

docker-compose.yml

services:
  mongo:
    image: mongo
    restart: always
    volumes:
      - ./data/db:/data/db
    environment:
      - MONGO_INITDB_ROOT_USERNAME
      - MONGO_INITDB_ROOT_PASSWORD
  formio:
    image: formio/formio:rc
    restart: always
    links:
      - mongo
    depends_on:
      - mongo
    environment:
      PORT: 3000
      DEBUG: formio.*
      NODE_CONFIG: '{"mongo": "mongodb://mongo:27017/formio-oss", "jwt": {"secret": "CHANGEME"}, "mongoSecret": "CHANGEME"}'
      ROOT_EMAIL: [email protected]
      ROOT_PASSWORD: CHANGEME
      ADMIN_KEY: CHANGEME
    ports:
      - "3000:3000"
  formio-uag:
    image: formio/uag
    restart: always
    links:
      - formio
    depends_on:
      - formio
    environment:
      PORT: 3200
      DEBUG: formio.*
      PROJECT: http://formio:3000
      ADMIN_KEY: CHANGEME
      JWT_SECRET: CHANGEME
      JWT_EXPIRE_TIME: 525600
      LOGIN_FORM: http://localhost:3000/user/login
      # The address clients reach the UAG at — this is the UAG's own port,
      # not the Form.io server's. See the BASE_URL section below.
      BASE_URL: http://localhost:3200
    ports:
      - "3200:3200"

以下のように入力して実行できます。

docker compose up -d

Docker Run

以下に、docker run コマンドを使用して UAG を実行する例を示します。

Open Source サーバーを指定した UAG

docker run -d \
  -e "PROJECT=https://forms.mysite.com" \
  -e "ADMIN_KEY=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "BASE_URL=https://forms.mysite.com" \
  -e "LOGIN_FORM=https://forms.mysite.com/user/login" \
  -e "PORT=3200" \
  --restart unless-stopped \
  --network formio \
  --name formio-uag \
  -p 3200:3200 \
  formio/uag

Form.io Enterprise Server を指定した UAG

docker run -d \
  -e "PROJECT=https://forms.mysite.com/myproject" \
  -e "PROJECT_KEY=CHANGEME" \
  -e "UAG_LICENSE=YOUR-LICENSE" \
  -e "JWT_SECRET=CHANGEME" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "BASE_URL=https://forms.mysite.com" \
  -e "LOGIN_FORM=https://forms.mysite.com/myproject/user/login" \
  -e "PORT=3200" \
  --restart unless-stopped \
  --network formio \
  --name formio-uag \
  -p 3200:3200 \
  formio/uag

起動したら、以下にアクセスして OSS デプロイメントと UAG サーバーの両方を利用できます。

• http://localhost:3000: Form.io OSS サーバー
• http://localhost:3200: UAG サーバー

Node.js ランタイム環境でも Docker でも、UAG は 環境変数 と モジュール を使用して制御します。

環境変数

このモジュールは、さまざまな方法で設定できます。その方法の 1 つが環境変数の使用です。以下に記載します。

Variable	Description	Example
PROJECT	必須。 Enterprise プロジェクトのエンドポイント、または OSS サーバーの URL となる API エンドポイントです。	http://localhost:3000
PROJECT_KEY	（Enterprise のみ）この UAG が紐付けられているプロジェクトの API キーです。Project Settings → API Keys にあります。Open Source デプロイメントでは、代わりに ADMIN_KEY を使用します。	CHANGEME
ADMIN_KEY	（Open Source のみ）OSS サーバーをインストールして接続するための ADMIN_KEY を指定できます。	CHANGEME
UAG_LICENSE	Form.io Enterprise デプロイメントで UAG を実行するためのライセンスです。
PROJECT_TTL	プロジェクトキャッシュの TTL（秒単位）です。UAG 内のフォームとリソースを更新するために、プロジェクトに加えられた「変更」を確認する間隔を制御します。	900
PORT	サーバーの実行に使用するポートです。	3200
DEBUG	サーバーの動作をデバッグログに出力するための変数です。	formio.*
PORTAL_SECRET	Enterprise のみ：Form.io Enterprise Portal から UAG に接続できます。	CHANGEME
JWT_SECRET	必須。 UAG の認証プロセスで生成される JWT トークンの生成と検証に使用するシークレットです。接続先の Enterprise Server の JWT_SECRET と一致させる必要はありません。	CHANGEME
JWT_EXPIRE_TIME	JWT シークレットの有効期限です。	3600
MONGO	（Enterprise のみ）送信データを Form.io Submission API にリダイレクトせずに、UAG を Mongo データベースに直接接続できます。
MONGO_CONFIG	Node.js Mongo Driver 用の JSON 設定です。
BASE_URL	必須。 クライアントからアクセスできる UAG の URL です。.well-known OIDC（PKCE）定義で公開され、認証コールバックに使用されます。リモートエージェントが接続する場合はパブリック URL が必要です。ローカル MCP クライアントの場合は、プライベート URL または localhost URL で問題ありません。	https://forms.yoursite.com
LOGIN_FORM	/auth/authorize ページで読み込まれる、ログインフォーム JSON エンドポイントの URL です。ブラウザーを使用するログインフローでのみ使用されるため、そのブラウザーからアクセスできる必要があります。	https://mysite.com/project/user/login
CORS	CORS ドメイン、またはクロスドメインのリソース共有を設定するための「cors」Node.js モジュール用 JSON 設定です。	.
NODE_TLS_REJECT_UNAUTHORIZED	Node.js の標準変数です。PROJECT が自己署名証明書、またはその他の信頼されていない証明書で保護された https URL の場合は、0 に設定します。これはローカル環境や内部デプロイメントでよくある設定です。この設定がないと UAG はサーバーに接続できず、すべてのツール呼び出しが失敗します。すべての送信リクエストで証明書検証が無効になるため、ネットワーク外部からアクセス可能なデプロイメントでは絶対に設定しないでください。	0

プロジェクトのキャッシュと TTL

デフォルトでは、UAG は TTL を使用してプロジェクトのアセットを「取得」し、登録して UAG にキャッシュします。つまり、基盤となるプロジェクトのフォームやリソースに変更を加えた場合（直接変更した場合も、デプロイを通じて変更した場合も）、変更が反映されるまで TTL 設定の秒数だけ待つ必要があります。たとえば、TTL が 900（15 分）に設定されている場合、フォームやリソースを変更すると、その変更が UAG に反映されるまで最大 15 分待つ必要があります。「更新」が発生すると、基盤となるプロジェクトのエンドポイントに対して「export」メソッドの API 呼び出しが行われます。この API 呼び出しはプロセッサーに大きな負荷をかけるため、TTL を 60 未満に設定することは推奨されません。値を 0 にすると「TTL なし」と解釈されます。この場合、プロジェクトのフォームやリソースを更新するには、UAG の再起動が必要です。

このパラメーターの使用方法を以下の表で説明します。

環境変数	値	結果
PROJECT_TTL	0	TTL がないため、更新は行われません。更新を「無効」にし、更新されたフォームやリソースを再取得する唯一の方法を UAG サーバーの再起動にする場合に使用できます。
PROJECT_TTL	60	1 分ごとに変更を確認します
PROJECT_TTL	3600	1 時間ごとに変更を確認します

フォームの編集がすぐに反映されないのは、このキャッシュが原因です。uag タグの追加、Criteria コンテンツコンポーネントの書き換え、Agent Fields の追加や削除など、エージェントが把握する情報に変更を加えた場合、次の有効期限が来てからエージェントに反映されます。Criteria を頻繁に編集する場合は、UAG を再起動すると、待たずにプロジェクトを再登録できます。

docker restart formio-uag

ドメインと URL の設定

重要な「ドメイン」環境変数は 3 つあり、ユースケースに応じてどのように設定するかを理解しておく必要があります。これらを パブリック にする必要があるかどうかは、エージェントの接続方法によって異なります。エージェントの接続方法を参照してください。

リモートエージェントが UAG に接続する場合、認証できるように、これらを正しく設定し、パブリックにする必要があります。ローカル MCP クライアントのみを使用する場合は、3 つすべてにプライベートアドレスまたは localhost アドレスを指定できます。

PROJECT

PROJECT 環境変数は、UAG サーバーからプロジェクトのエンドポイント（Enterprise の場合）または OSS のベース URL への接続に使用します。これはパブリック DNS エントリである必要はなく、UAG コンテナから Server コンテナに接続できる URL であれば問題ありません。設定例を以下に示します。

OSS Server へのローカル接続

Docker Compose ファイル内などでローカル接続を使用する場合、PROJECT 環境変数には、以下のようにローカル URL を直接指定できます。

docker-compose.yml

services:
  formio:
    image: formio/formio:rc
    restart: always
    environment:
      PORT: 3000
      ADMIN_KEY: CHANGEME
  formio-uag:
    image: formio/uag
    restart: always
    links:
      - formio
    depends_on:
      - formio
    environment:
      PROJECT: http://formio:3000
      ADMIN_KEY: CHANGEME

この例では、Docker Compose により、デプロイ用に ADMIN_KEY を設定した OSS Form.io コンテナを起動しています。UAG は http://formio:3000 を使用して接続します。これはローカルの Docker ネットワーク名であり、docker compose ファイルの「links」プロパティで指定されています。

Enterprise Server プロジェクトへのローカル接続

ローカル環境で UAG とともに Enterprise Form.io サーバーを使用する場合は、以下のように PROJECT_KEY を使用して、UAG が独立したプロジェクトに接続するよう設定する必要があります。

docker-compose.yml

services:
  formio-enterprise:
    image: formio/formio-enterprise
    restart: always
    environment:
      PORT: 3000
  formio-uag:
    image: formio/uag
    restart: always
    links:
      - formio-enterprise
    depends_on:
      - formio-enterprise
    environment:
      PROJECT: http://formio-enterprise:3000/myproject
      PROJECT_KEY: CHANGEME

パブリック DNS

プロジェクトが UAG と同じネットワーク上にない場合は、以下のようにドメイン名を PROJECT として指定できます。

docker-compose.yml：Enterprise（formio/formio-enterprise）に接続

services:
  formio-uag:
    image: formio/uag
    restart: always
    environment:
      PROJECT: https://forms.mydomain.com/myproject
      PROJECT_KEY: CHANGEME

docker-compose.yml：オープンソース（formio/formio）に接続

services:
  formio-uag:
    image: formio/uag
    restart: always
    environment:
      PROJECT: https://forms.mydomain.com
      ADMIN_KEY: CHANGEME

BASE_URL

BASE_URL には、UAG にアクセスできる URL を設定します。この値は、OIDC（PKCE）認証用の .well-known 定義内で公開され、認証コールバックに使用されます。

ローカルクライアントの場合も、BASE_URL は必ず必要です。UAG の認証プロバイダーは、この値が設定されている場合にのみ有効になります。そのため、値を省略すると、すべてのリクエストで /mcp が 401 を返し、/auth/token と /.well-known/* エンドポイントは存在しない状態（404）になります。/auth/token の 404 は、BASE_URL が設定されていないことを示す最も明確なサインです。

設定する値は、エージェントの接続方法によって異なります。

• リモートエージェントから接続する場合：UAG をホストしている、パブリックにアクセス可能なドメインを設定します。これは、エージェントに認証先として通知されるアドレスです。たとえば、BASE_URL: https://forms.mysite.com です。
• ローカルの MCP クライアントのみの場合：クライアントが UAG にアクセスするために使用するアドレスを設定します。プライベート URL や localhost の URL でも問題ありません。たとえば、Docker ネットワーク内では BASE_URL: http://localhost:3200 または BASE_URL: http://formio-uag:3200 です。

リモートエージェントが認証できない場合、最も一般的な原因は BASE_URL の不一致です。エージェントはディスカバリードキュメントからこの値を読み取り、その値に従ってアクセスします。そのため、エージェントがアクセスできない場所を指していると、UAG 自体が正常に稼働していても認証に失敗します。

LOGIN_FORM

これは、プロジェクトまたは OSS デプロイメントのログインフォームの URL です。ユーザーが {{ BASE_URL }}/auth/authorize にアクセスしたときに読み込まれるフォームを指定します。この URL にアクセスした際に、フォームを読み込めないというメッセージが表示される場合、LOGIN_FORM 環境変数がプロジェクトの正しいフォーム JSON エンドポイントを指していません。

これはブラウザーベースのログインフローでのみ使用されるため、ログインを実行するブラウザーからアクセスできる必要があります。client_credentials グラントで認証するローカル MCP クライアントは、このページを読み込みません。

例：

• Enterprise の例：LOGIN_FORM: https://forms.mysite.com/myproject/user/login
• OSS の例：LOGIN_FORM: https://forms.mysite.com/user/login

Node.js（Express）：

Node.js 環境では、ローカルで実行中の Node.js および Express.js 環境に UAG をインポートできます。まず UAG モジュールをインポートし、Express.js アプリケーション内で「use」することで動作します。最初に、以下のように Node.js Express アプリケーションに UAG をインストールします。

npm install --save @formio/uag

or

yarn add @formio/uag

You can then mount the UAG within your Express application, as seen in the following example:

import 'dotenv/config';
import Express from 'express';
import { UAGServer } from '@formio/uag';
try {
    (async function () {
        const server = new UAGServer();
        const app = Express();
        app.use(await server.router());
        const port = process.env.PORT || 3200;
        app.listen(port, () => {
            console.log(`Form.io UAG server running on port ${port}`);
            console.log(`Visit http://localhost:${port} to access the application`);
        });
    })();
} catch (error) {
    console.error('Failed to start server:', error);
    process.exit(1);
}

モジュールを使用して UAG の機能を拡張する方法もあります。詳しくは、Modules Readme を参照してください。

Form.io Enterprise Server との使用

UAG を Form.io Enterprise Server と使用すると、UAG 内のフォームやリソースを管理するうえで、いくつかのメリットを得られます。Enterprise Server で利用できる機能は次のとおりです。

• フォームのリビジョン - フォームのリビジョンシステムを使用すると、フォームに加えられた変更を追跡し、その変更を各リビジョンに対して送信された送信データと関連付けられます。この機能により、フォームスキーマが変更された場合でも、そのフォームに送信されたデータが送信時のフォームのリビジョンと対応していることを確認できます。この強力な機能に加えて、フォームの変更によって発生したミスやリグレッションを「ロールバック」する方法としても、フォームのリビジョンを活用できます。スキーマを使って AI エージェントを再トレーニングしたり、トレーニングを解除したりする代わりに、以前のリビジョンに戻すだけで、AI エージェントはそれに応じて調整されます。
• 送信データのリビジョン - 送信データのリビジョンを使用すると、送信データに加えられた変更を追跡し、誰がデータを変更したかを確認できます。これと UAG の機能を組み合わせることで、ワークフロー内で AI エージェントと人間の両方が行ったデータの変更を監査できるようになります。
• ステージのバージョンとデプロイ - ステージのバージョンを使用すると、プロジェクト内のすべてのフォームとリソースにわたって「タグ」バージョンを作成できます。これにより、多数の異なるフォームやリソースを利用する AI エージェントが、プロジェクト全体と確定的な方法で連携する時点を記録できます。また、プロジェクト内のフォームとリソース全体をそれぞれ独立してバージョン管理およびデプロイできる、より洗練された「ロールバック」方法も利用できます。

Enterprise Server に対して UAG を実行する

Enterprise Server に対して UAG を実行するには、このモジュールの OSS ランタイムとは異なるいくつかの環境変数を指定する必要があります。Enterprise プロジェクトに対して実行するには、次の環境変数が必要です。

変数	説明	例
PROJECT	Enterprise Server の場合、UAG の接続先となるプロジェクトエンドポイントを指定します。	https://mydeployment.com/myproject
PROJECT_KEY	プロジェクトの API キーです。プロジェクト設定で確認できます。	CHANGEME
UAG_LICENSE	Form.io ライセンスチームから提供されるライセンスです。「一時」ライセンスまたは正式ライセンスを取得するには、[email protected] にお問い合わせください。

これらの環境変数を設定すると、Enterprise プロジェクトを指定して UAG を実行できます。

トラブルシューティング

UAG の問題のほとんどはコードではなく設定に起因し、原因から離れたところに症状が現れる傾向があります。タグが付いていないとフォームが存在しないように見え、BASE_URL が設定されていないと権限エラーのように見えることがあります。以下の表では、発生しそうな症状と、実際の原因を対応付けています。

症状	考えられる原因
エージェントがフォームは存在しないと言う、または get_forms にそのフォームが表示されない	フォームに uag タグが付いていないか、変更がまだプロジェクトキャッシュに反映されていません。フォームへの uag タグの付け方とプロジェクトキャッシュと TTLを参照してください。
/auth/token が 404 を返し、/.well-known/* も見つからない	BASE_URL が設定されていません。認証プロバイダーはこの値が設定されている場合にのみ有効になるため、これらのエンドポイントは存在しません。BASE_URLを参照してください。
すべての /mcp リクエストが 401 を返す	BASE_URL が設定されていない（上記参照）か、クライアントが Authorization: Bearer <token> を送信していません。サーバー側のクライアントについては、ローカル MCP クライアントの認証を参照してください。
リモートエージェント（claude.ai、Claude Desktop コネクター）が認証できない	BASE_URL が、公開アクセス可能な HTTPS URL を指していません。エージェントはディスカバリードキュメントからこの値を読み取り、その URL にアクセスするため、サーバー側ではなくエージェント側から見て正しい値でなければなりません。
Claude インテグレーションが 400 ... Connection error while communicating with MCP server を返す	formio/uag-claude イメージのバージョンが 1.3.0 より古く、UAG をリモート MCP サーバーとして扱っているため、Anthropic API がプライベートアドレスに接続しようとしています。1.3.0 以降にアップグレードしてください。エージェントの接続方法を参照してください。
UAG がサーバーにまったく接続できず、すべてのツールが失敗する	PROJECT が自己署名証明書を使用する https URL の場合は、NODE_TLS_REJECT_UNAUTHORIZED=0 を設定してください。それ以外の場合は、PROJECT がUAG コンテナー内から名前解決できることを確認してください。これはコンテナー間のアドレスであり、ブラウザー用のアドレスではありません。PROJECTを参照してください。
送信が作成されても何も起こらない	Webhook アクションが実行されていません。handler が after であり、method に create が含まれていること、また API キーのヘッダーがインテグレーションの PROJECT_KEY（Enterprise）または ADMIN_KEY（OSS）と一致することを確認してください。
送信は作成されるが、応答が長時間返ってこない	Webhook アクションに block: true が設定されています。エージェントの実行には数十秒かかるため、送信者を待たせないよう block: false に設定してください。
エージェントが継続して実行され、API クレジットを消費する	連鎖したペルソナが自分自身を再トリガーしています。自身による書き込みが、開始のきっかけとなった update Webhook の条件を引き続き満たしています。ペルソナを連鎖させてワークフローにするを参照してください。
エージェントが一部のフィールドには入力するが、ほかのフィールドには入力しない	それらのフィールドに uag プロパティがないか、その値が Criteria コンポーネント上のペルソナと完全に一致していません。エージェントが書き込む可能性のあるすべてのフィールドに、直接、または親コンポーネントから継承する形で、同じペルソナを設定する必要があります。
エージェントがフォームで拒否される値を書き込む	Criteria で形式と許可値が十分に指定されていません。単位、丸め方、正確な選択肢の値を明示し、フィールドキーをそのまま記載してください。
実行に失敗し、ログを見ても問題箇所がわからない	UAG の前に Flow Viewer を配置してください。トークンリクエスト、tools/list、引数を含む各ツール呼び出し、書き戻しが順番に表示されます。

どれにも当てはまらない場合は、まずサンプルのいずれかを実行して環境自体に問題がないことを確認し、その設定を自分の設定と比較してください。