本文へ移動
技術を、自社の仕事に。
判断と実行を助けるメディア

記事を検索

A2UI v1.0への移行 themeと@付きキーをスキーマで検証

目次 · 7項目

社内の問い合わせ窓口や申請の画面に、AIエージェントが入力フォームや確認のカードを出す機能を試作していると、エージェントの出力を「どの仕様の版で」検証するかが問題になります。エージェントが返すJSONと、画面側の描画ライブラリが期待する形がずれると、部品が表示されない、入力した値がエージェントに届かない、といった不具合になるからです。

A2UI(Agent-to-User Interface)は、エージェントが画面の部品をコードではなくデータ(JSON)で送り、アプリの側の描画ライブラリ(レンダラー)がそれを自前の部品で表示する、オープンソースの仕組みです。仕様の v1.0(状態は「Current」)は v0.9 から互換性のない変更を含みます。本記事では、公式の移行ガイドの要点と、仕様の JSON Schema で実際にメッセージを検証した結果をまとめます。

A2UIの前提

リポジトリ(a2ui-project/a2ui)の README は、A2UI を「open-source generative UI framework」と説明し、使う場面として、エージェントが遠隔や第三者のもので信頼の境界をまたぐ場合を挙げています。「A2UI expresses UI using data, not code.」とあり、エージェントが使える部品はカタログ(部品の一覧と仕様)で決まり、スキーマで形が縛られます。

v1.0の仕様では、エージェントから画面への通知は createSurface(表示領域の作成)・updateComponents(部品の追加・更新)・updateDataModel(データの更新)・deleteSurface(削除)が基本です。v1.0 ではこれに、双方向の関数の呼び出し(callRendererFunction・callAgentFunction と、それぞれの応答)が加わりました。

v0.9から書き換えが要る点

移行ガイド(evolution_guide.md)の「Migration guide」から、エージェントの出力に関わる主な変更を抜き出すと次のとおりです。

変更v0.9v1.0
メッセージの版"version": "v0.9""version": "1.0"
見た目の指定createSurface に theme(primaryColor など)削除。見た目は表示する側の部品に任せる
部品の共通の項目accessibility・checks@accessibility・@checks(@catalogId・@metadata を追加)
データの削除value を省いてもよかったvalue は必須。削除は null を明示
MIMEタイプapplication/json+a2uiapplication/a2ui+json

このほか、TextField の validationRegexp が削除されて @checks と regex の関数に置き換わり、TextField の value が必須になりました。openUrl の関数は利用者の操作を必要とする(requiresUserActivation: true)扱いです。11月19日には、Text の variant から見出しの h1〜h5 が外れ、caption と body だけになったことが移行ガイドに追記されました。見出しは Text.text の Markdown(## 見出し など)で書きます。11月20日に確かめたところ、"variant": "h2" の部品は、main のスキーマでも次の節の 0.15.0 の同梱スキーマでも拒否されました。カタログを自作している場合は、"protocolVersion": "1.0" の指定が必要で、ガイドは「Catalogs authored for v0.9 cannot be used directly with v1.0 protocol runtimes」と書いています。

@ の付け方には注意書きがあります。ガイドは「Do not migrate v0.9 payloads with a blanket find-and-replace of "path": → "@path":」と警告しており、@ を付けるのはデータの結び付け(DataBinding)や関数の呼び出しの位置と、部品の直下の共通の項目に限られます。updateDataModel の path や、リストのひな形の path には付けません。

スキーマで検証した結果

2026年11月14日に、仕様の JSON Schema(リポジトリの main から取得した agent_to_renderer.json・common_types.json と、基本のカタログ catalogs/basic/v1/catalog.json)を、ajv 8.20(JSON Schema 2020-12)で読み込み、7通りのメッセージを検証しました。Node.js 22.23.4 で実行しています。11月20日に main のスキーマを取得し直し、同じ7通りを検証して(Node.js 22.23.5、ajv 8.20.0)、結果が変わらないことを確かめました。

INVALID  A: v0.9の形のまま(version "v0.9"・theme あり)
INVALID  B: version だけ "1.0" にして theme を残す   ← theme が追加の項目として拒否
valid    C: theme を外し、部品とデータを createSurface の1通に入れる
INVALID  D: updateDataModel で value を省く           ← value が必須
valid    E: updateDataModel で value: null(削除)
INVALID  F: 部品に v0.9 の書き方の accessibility    ← 評価されない項目として拒否
valid    G: 部品に v1.0 の書き方の @accessibility

B のように、版の番号だけを書き換えた出力は、厳密な検証では通りません。仕様は「A createSurface carrying theme fails strict validation; relaxed renderers drop it.」としており、緩い描画ライブラリでは theme が黙って捨てられるだけで、エラーにならないこともあります。テストで通っても、検証の厳しさが違う環境では落ちる、という差が生まれます。

A2UI v1.0のスキーマでの検証結果。v0.9の形のメッセージ、versionだけを1.0にしてthemeを残したもの、valueを省いたupdateDataModel、@なしのaccessibilityは仕様のmainのスキーマで拒否された。themeを外して部品とデータを1通に入れたもの、value: nullでの削除、@accessibilityは通った。npmの@a2ui/web_core 0.15.0の同梱スキーマでは、accessibilityと@accessibilityの判定が逆になった

配布中のライブラリの同梱スキーマとの差

同じ7通りを、npm で配布されている @a2ui/web_core 0.15.0(2026年11月2日公開)に同梱された v1.0 のスキーマ(src/v1_0/schemas/)でも検証しました。A〜E は同じ結果でしたが、F と G は逆になりました。0.15.0 の同梱スキーマでは、@ なしの accessibility が通り、@accessibility が拒否されます。同梱の common_types.json には "accessibility" の定義があり、@accessibility・@checks・@catalogId・@metadata の定義はありません。

移行ガイドの「Component envelope mixin keys」は、@ 付きのキーへの移行を「early v1.0 drafts」からの変更として説明しています。リポジトリの履歴では、仕様と SDK を @ 付きのキーに切り替える変更(「feat!: emit @-prefixed v1.0 component envelope keys across spec and SDKs」)が入ったのは11月11日で、0.15.0 の公開(11月2日)より後です。0.15.0 の同梱スキーマは、この変更の前の内容と読めます。ガイドは移行期間の扱いとして、描画ライブラリと Core SDK は、部品のスキーマに同じ名前の項目がなければ @ なしの古いキーも受け付け、両方が付いた部品は拒否する、エージェント向けの SDK は @ 付きのキーだけを出力する、と書いています。描画ライブラリの実際の動作は、今回は確認していません。

エージェントの側では、Python 向けの a2ui-agent-sdk 0.12.0(11月17日公開)のリリースノートが、v1.0 の部品に @catalogId・@metadata・@accessibility・@checks を出力する互換性のない変更(BREAKING CHANGE)を案内しています。この SDK を更新したエージェントの出力を、0.15.0 の同梱スキーマで検証すると、G と同じく @accessibility が拒否されることになります。

React・Lit 向けの @a2ui/react・@a2ui/lit の最新版も 0.15.0(11月2日公開)、Angular 向けの @a2ui/angular は 0.14.0 です。仕様の main と、配布中のライブラリの版の間には差がある前提で進めます。

移行の進め方(編集部の提案)

  1. 検証に使うスキーマを、描画ライブラリの版に合わせる。 エージェントの出力をCIで検証する場合は、本番で使う描画ライブラリの版に同梱されたスキーマを使います。仕様の main のスキーマで検証すると、今回の F・G のように、本番の描画ライブラリとは逆の判定になることがあります。エージェント側の SDK(a2ui-agent-sdk 0.12.0 など)を更新するときも、描画ライブラリの版との組み合わせで検証します。
  2. エージェントへの指示とカタログを同時に直す。 モデルへの指示(プロンプト)にカタログや出力例を入れている場合は、theme を含む例や @ なしの例を消し、v1.0 の例に差し替えます。版の番号だけを変えた出力は B のように拒否されます。
  3. 一括置換をしない。 "path": を "@path": に一括で置き換えると、updateDataModel の path まで変わってしまいます。移行ガイドの対象の位置の一覧と照らし合わせ、検証を通しながら直します。
  4. データの削除の書き方を確かめる。 updateDataModel で value を省いて削除していた処理は、value: null に直します。

AIエージェントの部品やツールの入出力の形を、言語をまたいでそろえる話題はGoogle ADKの5言語対応の記事で、エージェントに渡すスキルの効果の確かめ方はエージェントのスキルの評価の記事で扱いました。

確認した範囲

2026年11月14日に、a2ui-project/a2ui の README、仕様(specification/v1_0/docs/a2ui_protocol.md)、移行ガイド(specification/v1_0/docs/evolution_guide.md)、JSON Schema(specification/v1_0/json/ と catalogs/basic/v1/catalog.json)を main から取得して確認しました(資料調査)。あわせて npm の @a2ui/web_core 0.15.0 を取得し、同梱のスキーマと main のスキーマのそれぞれで、7通りのメッセージを ajv 8.20 で検証しました(Node.js 22.23.4)。描画ライブラリでの表示、エージェントの SDK の出力、モデルに生成させた出力の検証は行っていません。11月20日に、main のスキーマでの検証のやり直し、移行ガイドの更新(11月19日)、GitHub のリリース(a2ui-agent-sdk 0.12.0 など)、npm の最新版(@a2ui/web_core・@a2ui/react・@a2ui/lit は 0.15.0、@a2ui/angular は 0.14.0 のまま)、公式サイト(a2ui.org)を確認しました。公式サイトは v1.0 を「Current」と表示していますが、v1.0 の公開日の告知は見つかっていません。

AIエージェントを社内の業務の画面に組み込む設計や、出力の検証の仕組みづくりは、グリームハブの開発・AI・自動化のご相談で承っています。お問い合わせからご相談ください。

参考資料

この記事を共有XFacebook
鈴木 翔

技術の可能性に魅了され、学生時代からプログラミングとデジタルアートの分野に深い関心を持つ

この記事のテーマを、自社の次の一歩へ

自社での進め方を、具体的に。

つくりたい仕組み、既存システム、運用の条件を整理し、実現に向けた次の一歩を考えます。

  • 実現したい仕組み
  • 既存環境との接続
  • 運用の条件
開発・運用の構想を相談する

構想段階からご相談いただけます。この記事の情報を相談フォームに引き継ぎます。

最新記事をメールで受け取る