AI エージェントに「候補者に合う求人を3件推薦して」と頼むと、これまでは文章で答えが返ってきました。読み比べるのも、「1番と3番で」と返事を打つのも人の仕事です。
Google が 2026年11月11日に正式版を出した A2UI 1.0 は、この返し方を変える仕組みです。エージェントは文章の代わりに「画面の設計図」を JSON で返し、アプリはそれを自分の部品で描きます。利用者はカードを見比べ、チェックを入れ、ボタンを押すだけで、その操作がデータとしてエージェントに戻ります。
この記事では、公式サンプルと、自作の「求人推薦エージェント」を手元の Mac で実際に動かし、録画・スクリーンショットと実測値を交えて、A2UI で何ができるのか、どこに注意が要るのかをまとめます。

図1:同じ依頼への返し方の違い。A2UI では、選択や入力が画面の中で完結し、結果がデータでエージェントに届きます
この記事で分かること
- A2UI の仕組み(エージェント・通信・描画の3層)と、HTML を書かせる方法との違い
- 1.0 で増えたこと(双方向の関数呼び出し、アクセシビリティ、入力チェックなど)
- Python の Agent SDK と React で、操作できる画面を返すエージェントを作る手順(コード付き)
- 画面の書き方(推論形式)による速さの違いと、危ない出力がどこで止まるかの実測
- 2026年11月14日時点で、配布されているパッケージごとに使える機能の差
想定読者は、Python や React で業務向けの AI エージェントを作っている、または作ろうとしている方です。A2UI を初めて聞く方にも分かるよう、用語は順に説明します。
この記事の確認範囲
| 項目 | 内容 |
|---|---|
| 確認日 | 2026年11月14日 |
| 情報源 | Google Developers Blog(2026-11-11)、a2ui.org、GitHub a2ui-project/a2ui(main 3ed9601、11/13)、a2ui-project/labs(046a2df) |
| 実行環境 | MacBook Pro(Apple M5 Max・メモリ 128GB)、macOS 26.6.2、Node.js 22.23、Python 3.12 |
| パッケージ | PyPI a2ui-agent-sdk 0.11.0(a2ui-core 0.6.0)、npm @a2ui/react・@a2ui/web_core 0.15.0、比較用に GitHub main をソースからビルド |
| LLM | LM Studio の qwen/qwen3.8-27b(MLX 4bit、思考オフ、temperature 0) |
| 試していないもの | Gemini API での会話(API キーが必要)、Flutter・SwiftUI・Jetpack Compose の実機表示、A2A・AG-UI での接続 |
求人データ・会社名はすべて検証用に作った架空のものです。
A2UI とは何か
発表の中身
A2UI(Agent-to-User Interface)は、AI エージェントが利用者に「操作できる画面」を返すための、オープンな仕組みです。2025年12月にプレビュー版が公開され、2026年11月11日に初の安定版として 1.0 が出ました。
公式ブログで挙げられている要点は次のとおりです。
- エージェントは「何を表示するか」を記述し、各アプリが自分のネイティブ部品で描く
- エージェントが配置・設定できるのは、開発者が登録した部品だけ
- 1.0 で、画面とエージェントの双方向の関数呼び出し、アクセシビリティ、追加情報(メタデータ)の拡張に対応
- 描画ライブラリ(Renderer)は React・Angular・Lit・Flutter・SwiftUI・Jetpack Compose、エージェント側の SDK は Python・TypeScript・Dart
- Atlassian(Jira)、Alation、Bloomberg、ByteDance(Lynx)などが採用、Google 社内でも Gemini Notebook などで使用
一方で、すべてが 1.0 に移ったわけではありません。ブログ自身が、Jetpack Compose の Renderer は 0.9.1(1.0 は近日)、Gemini 側の対応は 0.9.1、ByteDance の Lynx は 0.9 から移行中と書いています。この「版のずれ」は、後半の実測でも別の形で現れました。
3つの層で考える
A2UI は、エージェントから画面までを次の3層に分けています。

図2:エージェントは画面の設計図をデータで書き、描くのはアプリ側の部品。操作は逆向きに戻ります
- 推論(エージェント側):LLM が画面の設計図を書きます。書き方(推論形式)は、通信と同じ JSON をそのまま書く「Direct JSON」と、短い記法の「Express」から選べます。Agent SDK がそれを検証し、正式なメッセージに変換します。
- 運搬:
createSurface(画面を作る)などのメッセージを、A2A・AG-UI・SSE・MCP Apps など好きな経路で運びます。中身はapplication/a2ui+jsonという JSON です。 - 描画(アプリ側):Renderer がメッセージを解釈し、カタログ(使ってよい部品の一覧)にある部品で画面を組み立てます。React なら React の部品、Flutter なら Flutter のウィジェットで描かれます。
なぜ HTML ではなく「データ」なのか
「LLM に HTML を書かせて表示すればよいのでは」と思うかもしれません。A2UI がそうしない理由は、図3の比較で分かります。

図3:A2UI ではエージェントは部品を選んで並べるだけ。何を許すかはカタログで決めます
HTML をそのまま表示すると、プロンプトインジェクション(文書などに仕込まれた命令で LLM が操られること)でスクリプトや偽の入力欄が混ざったときに、そのまま動いてしまいます。見た目もアプリのデザインとそろいません。A2UI では、届くのは「どの部品を、どのデータで」というデータだけで、ボタンが起こせるのは名前付きのイベントか、カタログにある関数の呼び出しだけです。
覚えておきたい用語
| 用語 | 意味 |
|---|---|
| Surface(サーフェス) | エージェントが管理する画面の1区画。ID で区別する |
| Component(部品) | Text・Card・CheckBox・Button などの画面部品 |
| Catalog(カタログ) | アプリが許可した部品と関数の一覧。エージェントへの制限にもなる |
| Data model(データモデル) | 画面が持つデータ。部品は {"@path": "/selected/j101"} のように場所を指して値を表示・更新する |
| Action(アクション) | ボタンなどの操作。イベント名と、選んだ値などの context がエージェントに届く |
| Renderer(レンダラー) | メッセージを受け取って画面を描くライブラリ |
1.0 で何が変わったか
仕様リポジトリの移行ガイド(v0.9 → v1.0)から、主な変更を図4・図5にまとめました。

図4:0.9 → 1.0 の主な変更。★ は今回の検証で実際に使ったもの
いちばん大きいのは関数呼び出しが両方向になったことです。これまでは「エージェントが画面を送る」「画面が操作を返す」の一方通行が基本でした。1.0 では、画面がエージェントの関数を呼んで値を受け取ったり(例:応募枠の残りをその場で問い合わせる)、エージェントが画面の関数を呼んで端末の情報を受け取ったりできます。

図5:1.0 のメッセージ。どの関数をどちら側から呼べるかは、カタログの allowedCallers で決めます
そのほか、読み上げ用のラベルに加えて「内容が変わったら読み上げる(live)」「隠す(hidden)」が指定できるようになり、入力チェックの関数は「OK か」だけでなく理由も返せるようになりました。部品の共通キーには @accessibility・@checks のように @ が付きます。ただし、この @ 付きの書き方は、公開中のパッケージではまだ一部しか使えませんでした(後述)。
公式サンプル「Travel A2UI」を動かす
まずは公式クイックスタートの旅行プランナー「Travel A2UI」を動かしました。Python のサーバー1つが、React(Web)と Flutter(モバイル)の2つのクライアントに同じメッセージを送るサンプルです。
手順
# サンプルを取得する
git clone https://github.com/a2ui-project/labs
cd labs/samples/travel-a2ui
# 公式の一括スクリプト(React と Flutter の両方をビルドして起動する)
./scripts/quickstart.sh both
公式スクリプトは Python 3.11 以上、Node 20 以上、Flutter 3.47 以上を前提にしています。今回は、スクリプトの中身と同じ手順を1つずつ実行しました。
# Python のサーバーを仮想環境に入れる
python3.12 -m venv .venv
.venv/bin/pip install -r apps/server/requirements.lock
.venv/bin/pip install --no-deps -e apps/server
# React クライアントをビルドする
npm ci
npm run build
# Flutter クライアントを Web 向けにビルドする(約15秒)
(cd apps/flutter && flutter pub get && flutter build web --release --base-href=/flutter/)
# サーバーを起動する(React は http://127.0.0.1:8080、Flutter は /flutter/)
.venv/bin/python -m uvicorn travel_a2ui.doors.http:app --host 127.0.0.1 --port 8080 --app-dir apps/server/src
Mac では npm run build が Cannot find native binding で止まりました。lock ファイルに Mac(Apple シリコン)用のネイティブ部品が含まれていなかったためで、npm の既知の不具合です。同じ版の部品を足すと通りました。
# rolldown と lightningcss の版を確かめてから、Mac 用の部品を同じ版で足す
node -p "require('./node_modules/rolldown/package.json').version" # 1.2.7
node -p "require('./node_modules/lightningcss/package.json').version" # 1.33.0
npm install --no-save @rolldown/binding-darwin-arm64@1.2.7 lightningcss-darwin-arm64@1.33.0
npm run build
動かして分かったこと
起動すると、API キーなしでも「録画済みのサンプル旅行」が表示されます。会話の中に航空券のカードが並び、右側に旅程のまとめが出ます。

図6:公式サンプルの会話画面(録画済みのサンプル)。カードと右側のパネルが A2UI で描かれた部分です
Catalog タブでは、エージェントが使える部品が実際の Renderer で一覧表示されます。このサンプルでは、旅行用の独自部品 15 個と A2UI の基本部品 18 個の、合わせて 33 個でした。エージェントはこの中からしか部品を選べません。

図7:カタログの一覧。「エージェントが描けるもの」がそのまま見えます
Wire タブでは、モデルが書いたもの(A2UI Express)と、画面が受け取ったもの(A2UI の JSON)を並べて見られます。料金のまとめカードの例では、Express が JSON より 61% 短いと表示されました。

図8:同じ画面の2つの表現。モデルには短い記法で書かせ、SDK が JSON に変換します
なお、会話を進める(自分で旅行を頼む)には Gemini の API キーが要ります。Flutter 版と Home タブ(ダッシュボード)は、起動するとまずキーの入力を求められました。今回はキーを使わずに検証したため、Flutter での描画は確認できていません。
自作の「求人推薦エージェント」を作る
公式サンプルは旅行向けで、モデルも Gemini 固定です。そこで、業務での使い方としてよく挙がる「求人を推薦するエージェントが候補をカードで表示し、担当者がチェックボックスで選んで推薦を承認する」流れを、自分で組んでみました。モデルは API キーの要らない、手元の Qwen 3.8 27B(LM Studio)です。
全体の流れ

図9:検証アプリの流れ。年収と応募枠はサーバー側のデータから入り、LLM には渡りません
ポイントは3つです。
- マクロ:LLM は
JobCard("j101", "推薦理由")のように求人 ID と理由だけを書き、カードの中身(タイトル・年収・チェックボックスなど)はサーバーの Python 関数が組み立てます。年収は「社外秘」という想定で、LLM には渡していません。 - エージェント関数:カードの「応募枠 残り2名」は、画面がエージェントの関数
checkOpeningsを呼んで表示します(画面 → エージェント)。 - 画面側の関数:エージェントは画面を作る前に、画面の関数
getClientContextを呼んで端末のタイムゾーンを受け取ります(エージェント → 画面)。
準備
mkdir -p jobmatch/server && cd jobmatch/server
python3.12 -m venv .venv
.venv/bin/pip install "a2ui-agent-sdk==0.11.0" fastapi uvicorn httpx
# LM Studio のサーバーを起動し、Qwen を読み込む(OpenAI 互換 API が :1234 で開く)
~/.lmstudio/bin/lms server start
~/.lmstudio/bin/lms load qwen/qwen3.8-27b --context-length 32768 -y
ステップ1:カタログに関数を足す
基本のカタログ(Basic Catalog)に、エージェント側で動く checkOpenings と、画面側で動く getClientContext を足します。カタログの ID は Basic Catalog のままにして、画面側と ID をそろえます。
from a2ui.core import AgentFunction
from a2ui.core.basic_catalog import BasicCatalog
from a2ui.core.catalog.functions import FunctionImplementation
from jobs import OPENINGS # {"j101": 2, "j102": 1, ...}(検証用の架空データ)
def check_openings(args: dict) -> str:
n = OPENINGS.get(args["jobId"])
return "募集終了" if n == 0 else f"応募枠 残り{n}名"
# 画面から呼ばれ、エージェント(サーバー)で実行される関数
CHECK_OPENINGS = AgentFunction(
"checkOpenings",
handler=check_openings,
return_type="string",
schema={"type": "object", "properties": {"jobId": {"type": "string"}},
"required": ["jobId"], "additionalProperties": False},
description="求人の応募枠の残りを文字列で返す",
)
# エージェントから呼べる、画面側の関数(実装は画面にある。ここでは宣言だけ)
GET_CLIENT_CONTEXT = FunctionImplementation(
"getClientContext", return_type="object",
schema={"type": "object", "properties": {}, "additionalProperties": False},
allowed_callers="rendererOrAgent", is_definition=True,
description="端末のタイムゾーン・言語・画面幅を返す",
)
basic = BasicCatalog("1.0")
CATALOG = basic.copy_with(
functions=[*basic.functions.values(), GET_CLIENT_CONTEXT],
agent_functions=[CHECK_OPENINGS],
)
ステップ2:マクロで「求人カード」を定義する
@macro を付けた関数は、LLM から見ると1つの部品のように見えます。LLM が JobCard("j101", "理由") と書くと、SDK がこの関数を実行し、基本部品の組み合わせに展開して画面へ送ります。
from a2ui.builder.v1_0 import Card, CheckBox, Column, DataBinding, FunctionCall, Icon, Row, Text
from a2ui.transformers.macros import macro
from jobs import JOBS # 年収・担当者などの社外秘データを含む
@macro
def JobCard(job_id: str, reason: str) -> Card:
"""求人カード。タイトル・会社・条件・年収と推薦チェックボックスを含む。
Args:
job_id: 求人 ID(j101 など、求人一覧にある ID)。
reason: この候補者に合う理由(日本語で1〜2文)。
"""
j = JOBS[job_id]
return Card(child=Column(children=[
Text(text=f"#### {j['title']}"),
Row(children=[Icon(name="locationOn"),
Text(text=f"{j['company']}・{j['location']}・{j['remote']}", variant="caption")]),
Text(text=f"**{j['salary']}** 必要スキル: {', '.join(j['skills'])}"),
Text(text=f"推薦理由: {reason}"),
# 表示する文字を、エージェント関数の呼び出しで決める(画面 → エージェント)
Text(text=FunctionCall(call="checkOpenings", args={"jobId": job_id})),
CheckBox(label="この求人を推薦する", value=DataBinding(path=f"/selected/{job_id}")),
]))
docstring の Args: は、そのまま LLM への説明(プロンプト)になります。
ステップ3:LLM に書かせて、検証する
SDK の A2uiRequestProcessor が、カタログの説明をプロンプト用の文章(prompt_snippet)にし、LLM の出力を parse_response で検証します。検証に通らなければ、エラー文を添えてもう一度書かせます。
import httpx
from a2ui.core import A2uiError
from a2ui.inference_formats import ExpressFormatFactory
from a2ui.parser import A2uiPart
from a2ui.processor import A2uiRequestProcessor
from a2ui.transformers.macros import MacroExpander
expander = MacroExpander([JobCard], on_error="raise")
inference_catalog = expander.transform_to_inference_catalog(CATALOG) # JobCard の説明を足す
processor = A2uiRequestProcessor(catalogs=[inference_catalog], format_factory=ExpressFormatFactory())
system = RULES + "\n\n" + processor.prompt_snippet # RULES は役割・求人一覧(年収なし)・画面の作り方
def call_llm(messages):
r = httpx.post("http://127.0.0.1:1234/v1/chat/completions", json={
"model": "qwen/qwen3.8-27b", "messages": messages,
"temperature": 0, "max_tokens": 6000, "reasoning_effort": "none",
}, timeout=1800)
return r.json()["choices"][0]["message"]["content"]
def run_turn(user_text: str) -> list[dict]:
msgs = [{"role": "system", "content": system}, {"role": "user", "content": user_text}]
for _ in range(2): # 1回目+やり直し1回
out = call_llm(msgs)
try:
wire = []
for part in processor.parse_response(out): # 検証(カタログに合わなければ例外)
if isinstance(part, A2uiPart):
for m in expander.transform_to_transport(part.a2ui): # マクロを展開
wire.append(m.model_dump(by_alias=True, exclude_none=True))
return wire
except A2uiError as e:
msgs += [{"role": "assistant", "content": out},
{"role": "user", "content": f"A2UI の検証エラー: {e}\n修正して全体を書き直して"}]
raise RuntimeError("検証に通る画面を作れなかった")
実際に Qwen が書いた Express は次のとおりです(1回目で検証に通ったもの)。
<a2ui>
surface("jobs")
$/selected/j101 = false
$/selected/j102 = false
$/selected/j104 = false
$/form/email = ""
root = Column([intro, card1, card2, card3, emailField, approveBtn], "start", "stretch")
card1 = JobCard("j101", "フルリモート対応で、時系列予測の機械学習実務をそのまま活かせます。")
card2 = JobCard("j102", "週4リモートでLLM/RAG開発に携わり、Pythonスキルを最新技術に広げられます。")
card3 = JobCard("j104", "フルリモートでMLOpsの基盤構築に携わり、機械学習の運用面を強化できます。")
emailField = TextField("通知先メールアドレス", $/form/email, "example.com", "shortText", ?email("有効なメールアドレスを入力してください。"))
approveBtn = Button(approveLabel, "primary", Event("approve_recommendation", {selected: $/selected, email: $/form/email}))
approveLabel = Text("選んだ求人で推薦を承認")
</a2ui>
?email(...) が入力チェック、Event("approve_recommendation", {...}) がボタンを押したときにエージェントへ届くイベントです。SDK はこれを、部品 35 個ほどの createSurface メッセージ(JSON)に変換して画面へ送ります。
ステップ4:サーバーで画面からのメッセージを受ける
画面から届くメッセージは、RendererToAgentMessageProcessor に渡すと種類ごとに処理されます。callAgentFunction には SDK がその場で checkOpenings を実行して答え、action(承認ボタン)は LLM の次のターンに回します。
import json
from a2ui.rpc import RendererFunctionCalls, RendererToAgentMessageProcessor
# app は FastAPI、push_to_renderer は SSE で画面へメッセージを送る自作の関数(全体は code/server/app.py)
calls = RendererFunctionCalls(catalogs=[CATALOG]) # エージェント → 画面の呼び出しを管理
rpc = RendererToAgentMessageProcessor([CATALOG], on_renderer_function_response=calls.resolve)
@app.post("/api/renderer")
async def renderer(body: dict):
msg = body["message"]
result = await rpc.process_message(msg)
if result.handled: # callAgentFunction・rendererFunctionResponse は SDK が処理
return {"messages": [r.model_dump(by_alias=True, exclude_unset=True) for r in result.replies]}
if "action" in msg: # ボタン操作は、中身を LLM に渡して次の画面を作る
a = msg["action"]
return {"messages": run_turn(f"UI操作: {a['name']} context={json.dumps(a['context'], ensure_ascii=False)}")}
@app.post("/api/chat")
async def chat(body: dict):
# エージェント → 画面の関数呼び出し。SSE で画面へ送り、答えを待つ
msg, fut = calls.call(catalog_id=CATALOG.catalog_id, name="getClientContext", args={})
await push_to_renderer(msg.model_dump(by_alias=True, exclude_unset=True))
ctx = await fut # {"timeZone": "Asia/Tokyo", "locale": "ja-JP", "viewportWidth": 1440}
return {"messages": run_turn(body["text"] + f"\n(画面の環境: タイムゾーン {ctx['timeZone']})")}
ステップ5:React で描く
画面側は @a2ui/web_core の MessageProcessor と、@a2ui/react の A2uiSurface だけで描けます。outboundListener に渡した関数が、画面からエージェントへのメッセージ(callAgentFunction など)の送り口になります。
import {MessageProcessor, createFunctionImplementation} from '@a2ui/web_core';
import {basicCatalog} from '@a2ui/web_core/catalogs/basic/v1';
import {A2uiSurface, MarkdownContext} from '@a2ui/react';
import {renderMarkdown} from '@a2ui/markdown-it';
import {z} from 'zod';
// 画面側の関数 getClientContext を、Basic Catalog と同じ ID のまま足す
const getClientContext = createFunctionImplementation(
{name: 'getClientContext', returnType: 'object', schema: z.object({}).strict(), allowedCallers: 'rendererOrAgent'},
() => ({timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
locale: navigator.language, viewportWidth: window.innerWidth}),
);
const catalog = basicCatalog.copyWith({functions: [...basicCatalog.functions.values(), getClientContext]});
const post = (url: string, body: unknown) =>
fetch(url, {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(body)}).then(r => r.json());
const processor = new MessageProcessor(
[catalog],
// ボタンなどの操作 → エージェントへ
async action => {
const envelope = {version: '1.0', action: {name: action.name, surfaceId: action.surfaceId,
sourceComponentId: action.sourceComponentId, timestamp: action.timestamp, context: action.context}};
processor.processMessages((await post('/api/renderer', {message: envelope})).messages);
},
{
// callAgentFunction・rendererFunctionResponse → エージェントへ
outboundListener: async m => processor.processMessages((await post('/api/renderer', {message: m})).messages),
},
);
// サーバーから押し出されるメッセージ(callRendererFunction)を受ける
new EventSource('/api/events').onmessage = ev => processor.processMessages([JSON.parse(ev.data)]);
// 描画:surface ごとに A2uiSurface を置くだけ
export const Surfaces = ({ids}: {ids: string[]}) => (
<MarkdownContext.Provider value={renderMarkdown}>
{ids.map(id => <A2uiSurface key={id} surface={processor.model.surfacesMap.get(id)!} />)}
</MarkdownContext.Provider>
);
アイコン(Icon)は Material Icons のフォントで描かれるため、HTML でフォントを読み込んでおきます。読み込まないと「location_on」という文字のまま表示されました。
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
ここで1つ注意があります。上のコードのうち、copyWith と、エージェント関数の自動呼び出しは、npm 公開版 0.15.0 にはまだ入っていません。今回は GitHub main(11/13)のソースを Vite の別名(alias)で読み込んでビルドしました。詳しくは「配布版ごとの差」の節で説明します。
実行結果
依頼文を送ってから承認するまでの操作を録画しました。MP4 は等速、GIF は LLM が画面を書いている約30秒を10倍速にし、全体を1.25倍速にしています。

図10:依頼から承認までの実際の操作(等速の MP4 版)。右側は送受信した A2UI メッセージの記録です
依頼を送ると、まずエージェントが画面の getClientContext を呼び、続いて Qwen が画面を書きます。この回は 34.2 秒・出力 401 トークンで、1回目で検証に通りました(後の計測では同じ書き方の平均が 25.0 秒でした)。カード3枚が出たあと、画面が checkOpenings を3回呼び、「応募枠 残り2名」などが後から入りました。

図11:生成された求人カード。年収はマクロがサーバーの DB から入れ、応募枠はエージェント関数で取得しています
メール欄に「recruiter@」とだけ入れると、入力チェック(email 関数)が働いて赤いエラーが出ました。チェックは画面の中で完結し、エージェントには問い合わせません。読み上げソフト向けに、入力欄には aria-invalid="true" と、エラー文を指す aria-describedby が自動で付いていました。

図12:入力チェックの表示。エラー文はモデルが Express の ?email("...") で指定したものです
承認ボタンを押すと、選んだ2件({"j101": true, "j102": false, "j104": true})とメールアドレスが action の context としてエージェントに届き、Qwen が確認画面を作りました。

図13:承認後の確認画面(surface: done)。タイムゾーンは getClientContext で受け取ったものです
右側の記録を開くと、実際のメッセージが見られます。callAgentFunction には呼ぶ関数(@call)と引数、どのカタログの関数かが入り、エージェントは同じ functionCallId を付けた agentFunctionResponse で答えます。承認ボタンの action には、画面のデータモデルから解決された値(選んだ求人とメール)がそのまま入っていました。

図14:画面 → エージェントの関数呼び出し(callAgentFunction)。1つの求人につき1回送られています
逆向きの、エージェント → 画面の呼び出しも記録の先頭に残っています。サーバーが callRendererFunction で getClientContext を呼び、画面が rendererFunctionResponse でタイムゾーン(Asia/Tokyo)・言語(ja-JP)・画面幅(1440px)を返しました。確認画面の「通知は Asia/Tokyo の平日 9〜18 時に送ります」は、この値を使ったものです。

図15:エージェント → 画面の関数呼び出し(callRendererFunction)。1.0 で追加された向きです
書き方で速さはどれだけ変わるか
A2UI では、LLM に画面をどう書かせるか(推論形式)を選べます。同じ画面を、3通りの書き方で Qwen に書かせて比べました。

図16:同じ画面の3通りの書き方(依頼1の実際の出力から抜粋)
- Direct JSON:通信で使う JSON をそのまま書く。部品ごとに ID を手で付け、親子関係を ID で指す
- Express:
Card(Column([Text(...), CheckBox(...)]))のように入れ子で書く短い記法。ID は SDK が付ける - Express + マクロ:Express に加えて、サーバーで定義した
JobCardを使う
計測の条件
候補者の条件を変えた5つの依頼(「Python と機械学習3年、リモート希望」「TypeScript と React、九州在住」など)を、3通りの書き方で1回ずつ実行しました(計15回)。モデルは Qwen 3.8 27B(MLX 4bit、思考オフ、temperature 0)、M5 Max です。計測中にブラウザでの画面撮影を並行して行った時間帯があるため、秒数は目安として見てください。検証に落ちたときは、エラー文を添えて1回だけやり直させました。計測用のスクリプトは bench.py です。
cd jobmatch/server
.venv/bin/python bench.py # 結果は results/bench.jsonl と bench_summary.json
結果

図17:1回目の出力の平均(5依頼)
| 書き方 | 出力トークン(平均) | LLM の応答時間(1回目の平均) | 入力トークン(平均) | 1回目で検証OK | やり直し後 |
|---|---|---|---|---|---|
| Direct JSON | 1,927 | 121.1 秒 | 10,993 | 3/5 | 5/5 |
| Express | 736 | 48.7 秒 | 6,524 | 5/5 | 5/5 |
| Express + マクロ | 392 | 25.0 秒 | 6,610 | 4/5 | 5/5 |
Express は Direct JSON の約 38% の出力で同じ画面を書き、マクロを足すと約 20% まで減りました。手元の 27B モデルでは出力の速さがそのまま待ち時間に出るため、Direct JSON で平均 121 秒かかった画面が、マクロ付き Express では 25 秒ほどで出ました。公式ドキュメントは「Direct JSON は位置引数の呼び出しより約3倍長い」と説明しており、今回の Express との差(約 2.6 倍)はおおむねその範囲でした。
入力(プロンプト)も、カタログの説明が Express 向けのほうが短いため、Direct JSON の約 59% でした。
検証に落ちた例も記録しておきます。
- Direct JSON・依頼3:部品 ID にハイフンを使った(例:
card-j106)。1.0 は ID を識別子の形に限る(A2uiValidationError: Validation failed for component 'Card': components.card-j106.id: Comp…) - Express + マクロ・依頼3:ボタンの子に、部品 ID ではなく文字列(「選んだ求人で推薦を承認」)を直接書いた(
A2uiIntegrityError: Dangling reference: Component 'approveBtn' references non-existent com…) - Direct JSON・依頼5:Text の variant に、カタログにない値を書いた(Basic Catalog の Text は caption と body だけ)(
A2uiValidationError: Validation failed for component 'Text': components.header.variant: In…)
3件とも、SDK のエラー文(どの部品の、どの項目が、なぜ)をそのままモデルに渡すと、やり直し1回で通りました。
なお、短くなるのは LLM が書く量だけです。画面に届く JSON は、マクロ付きのほうがむしろ大きくなりました(平均 4,648 文字・部品 34.8 個。Direct JSON は 3,407 文字・28.4 個)。マクロがアイコンや応募枠の表示など、モデルが省きがちな部品まで毎回きちんと組み立てるためです。
一方で、Direct JSON には「通信と同じ形なので、途中まで届いた部分から順に描ける(ストリーミング)」という利点があります。Express はブロックを最後まで読んでから変換するため、今回のように画面全体を一度に出す使い方向きです。待ち時間を短くしたいなら Express とマクロ、届いた順に少しずつ見せたいなら Direct JSON、と使い分けるのがよさそうです。
危ない出力はどこで止まるか
A2UI の売りは「エージェントが登録された部品しか使えない」ことです。本当にそうなるのかを、「モデルがこう書いてしまった」という想定の出力を直接流して確かめました(LLM は使わず、文字列を SDK と画面に渡しています)。

図18:エージェント側の検証と、画面側の描画の2段で止まる
エージェント側では、Python SDK の parse_response に次のような出力を渡しました。
# カタログにない部品を使った出力(モデルがこう書いてしまった想定)
bad = '<a2ui-json>[{"version": "1.0", "createSurface": {"surfaceId": "t", "catalogId": "<Basic Catalog の ID>", ' \
'"components": [{"id": "root", "component": "HtmlBlock", "html": "<script>alert(1)</script>"}]}}]</a2ui-json>'
processor.parse_response(bad)
# → A2uiValidationError: Validation failed for component 'HtmlBlock':
# components.root.component: Unrecognized component type 'HtmlBlock'
結果をまとめると、次のとおりです。
| 想定した出力 | エージェント側 SDK | 画面側(main) |
|---|---|---|
カタログにない部品 HtmlBlock | 拒否 | 届いても何も描かない |
ボタンに未登録の関数 deleteAllUsers | 拒否 | — |
知らない属性 onclick | 拒否 | — |
| 必須抜け・型の誤り・存在しない子 ID | 拒否 | — |
文章中の <script>・onerror | 通過(ただの文字列) | 文字として表示され、実行されない |
openUrl に javascript: の URL | 通過 | 開かない(http・https・mailto・tel だけ許可) |
入力チェックに固まる正規表現 (a+)+$ | 通過 | 固まらずに「不正」と判定 |
部品を4種に絞ったカタログで Image | 拒否(絞る前は通過) | — |
エージェントが画面の openUrl を直接呼ぶ | 拒否(rendererOnly) | — |
形の誤りはエージェント側の SDK で、文字列に紛れた危険は画面側で止まりました。逆に言えば、SDK の検証だけでは文字列の中身までは見ません。Markdown を表示する部品の無害化(DOMPurify)や URL の制限は Renderer に任されているので、自作の部品を足すときは、同じ配慮を自分で入れる必要があります。公式 SDK の README も、外部のエージェントからの UI 定義は「信頼できない入力として扱う」よう注意しています。
カタログを絞る(ComponentPruningTransformer)と、同じ出力でも拒否されるようになりました。業務アプリでは「この画面で使ってよい部品」を最小限にしておくと、プロンプトインジェクションへの備えにも、トークンの節約にもなります。
配布版ごとの差:「1.0」でも使える範囲が違う
検証中にいちばん時間を使ったのが、この点です。同じメッセージを、npm 公開版(0.15.0)と GitHub main の描画ライブラリ、PyPI 公開版の Python SDK(0.11.0)に通して比べました。

図19:2026年11月14日時点の実測。1.0 の新しい書き方は、公開版ではまだ一部しか通りません
分かったことは3つです。
- エージェント関数の自動呼び出しは、npm 0.15.0 では動かない:表示に
checkOpeningsを使った文字は空のままで、callAgentFunctionが送られませんでした。main では自動で送られ、「応募枠 残り1名」が表示されました。web_core の CHANGELOG では、この機能(実装がない関数をエージェントに回す)は Unreleased(未リリース)の欄にあります。 @checks・@accessibilityは、公開版どうしではまだ使えない:npm 0.15.0 はVALIDATION_FAILEDで部品を描かず、Python SDK 0.11.0 は検証で拒否しました。どちらも 0.9 の書き方(checks・accessibility)なら通り、Python SDK が出力するのもこちらでした。@付きへの切り替えは、Python 側も TypeScript 側も CHANGELOG の Unreleased にあります。- 読み上げの細かさが違う:0.9 の書き方の入力チェックでは、main は入力欄に
aria-invalid="true"を付けましたが、npm 0.15.0 は付けませんでした。アイコンのラベルも、main は中の要素に、0.15.0 は外側の要素に付いていました。
つまり、2026年11月14日の時点では「公開版どうし(0.9 の書き方)でそろえれば、今すぐ使える」「1.0 の新機能(自動の関数呼び出しや @ 付きのキー)が要るなら、main をソースからビルドする」のどちらかになります。ブログが書いている Jetpack Compose・Gemini 側の 0.9.1 と合わせて、導入前に各パッケージの版と CHANGELOG を確かめるのがおすすめです。
業務で使うときの設計ポイント
検証を通じて、業務アプリに入れるときに効きそうだと感じた点をまとめます。
社外秘のデータは LLM に渡さず、マクロで差し込む
今回の JobCard のように、LLM には ID と判断(推薦理由)だけを書かせ、年収や担当者などのデータはサーバー側で差し込めます。LLM に渡すデータが減るので、情報漏えいの心配が減り、出力も短くなります。公式ブログも「データの結び付けをサーバー側で行い、機密の値がモデルに届かない」ことを 1.0 の利点に挙げています。
承認は「action」で受け、処理はサーバーで行う
「推薦を承認する」流れは、ボタンの action で実現できました。実際の推薦処理(ATS への登録やメール送信)は、action を受け取ったサーバーのコードで行い、LLM に任せないのが安全です。今回は確認画面だけを LLM に作らせましたが、処理そのものは決まったコードで書く想定です。
画面の形が毎回変わる場面にだけ使う
A2UI は便利ですが、毎回同じ入力フォームで済むなら、ふつうに画面を作るほうが簡単です。図20の順に考えると判断しやすくなります。

図20:A2UI を使うかどうかの判断
MCP Apps(MCP のツールが HTML の画面を返し、iframe で隔離して表示する仕組み)とは競合というより組み合わせの関係で、公式ガイドには A2UI の画面を MCP Apps の中に入れて Claude や Gemini に表示する方法も載っています。
LLM の出力は「検証→やり直し」を前提にする
今回の計測でも、Direct JSON で1回、部品 ID の付け方が原因で検証に落ちました。SDK の検証エラーは「どの部品の、どの項目が、なぜ」まで具体的に返るので、そのままモデルに渡すと1回で直りました。やり直しの回数を決めておき、それでも通らなければ文章だけで答えるなど、逃げ道を作っておくと安心です。
トラブルシューティング
検証中に実際に起きたことを、確認する順にまとめます。

図21:症状・原因・直し方
| 症状 | 原因 | 直し方 |
|---|---|---|
npm install が ERESOLVE で止まる | @a2ui/markdown-it 0.2.2 が @a2ui/web_core ^0.14 を要求している | npm install --legacy-peer-deps |
ビルドで Cannot find native binding | lock ファイルに Mac 用の部品がない(npm の既知の不具合) | 同じ版の @rolldown/binding-darwin-arm64・lightningcss-darwin-arm64 を入れる |
アイコンが location_on と文字で出る | Material Icons のフォント未読み込み | HTML でフォントを読み込む |
| エージェント関数を使った文字が空 | npm 0.15.0 は自動で呼ばない | main をビルドする、またはアプリ側で processor.callAgentFunction() を呼ぶ |
@checks・@accessibility で拒否される | 公開版は 0.9 の書き方 | checks・accessibility で書く |
A2uiValidationError(例:card-j106 must be a valid UAX #31 identifier) | 1.0 は部品 ID を識別子の形(ハイフン不可)に限定 | エラー文を添えて書き直させる。プロンプトで「ID は英数字と _ だけ」と指示する |
同じ surfaceId で INTEGRITY_ERROR | 1.0 は surfaceId の重複を禁止 | 画面ごとに別の ID にするか、先に deleteSurface する |
まとめ
- A2UI 1.0 は、エージェントが「画面の設計図」を JSON で返し、アプリが自分の部品で描く仕組みです。HTML やコードを送らないので、見た目と安全性をアプリ側が握れます。
- 1.0 では関数呼び出しが両方向になりました。手元の検証でも、画面がエージェントに応募枠を問い合わせ、エージェントが画面に端末のタイムゾーンを問い合わせる流れが動きました。
- 書き方(推論形式)で速さが大きく変わります。Express とマクロを使うと、Direct JSON より出力が大幅に短くなり、手元の 27B モデルでも実用的な速さになりました。
- 危ない出力は、形の誤りをエージェント側の SDK が、文字列に紛れた危険を画面側が止めました。自作の部品を足すときは、画面側の無害化を自分で入れる必要があります。
- 2026年11月14日の時点では、1.0 の新しい書き方の一部が公開パッケージに入っていません。今すぐ使うなら公開版どうしでそろえ、新機能が要るなら main をビルドします。
次の一歩としては、自分の業務の画面から「毎回形が変わるところ」を1つ選び、カタログを最小限に絞ったうえで、マクロで社内データを差し込む構成から試すのがおすすめです。
参考リソース
- A2UI 1.0: Build delightful, fast, reliable, agentic experiences(Google Developers Blog、2026-11-11)
- A2UI 公式サイト / クイックスタート / ロードマップ
- GitHub:a2ui-project/a2ui(仕様の移行ガイドは
v1_0/docsのevolution_guide.md) - GitHub:a2ui-project/labs(Travel A2UI)
- Using Macros(a2ui.org)
- A2UI in MCP Apps(a2ui.org)
- A2UI Playground(CopilotKit)

