ADK と A2UI を使用したフロントエンド エクスペリエンス

1. 概要

ほとんどの AI エージェントはテキストで返信します。この Codelab では、A2UI を使用して、エージェントがユーザー インターフェースで応答できるようにします。エージェントは、標準コンポーネントのカタログを使用して、カード、リスト、ボタン、フォームを JSON で記述します。クライアントは、独自のネイティブ ウィジェットを使用してそれらをレンダリングするため、新しいレイアウトに新しいフロントエンド コードは必要ありません。

エージェントは Agent Development Kit(ADK)を使用して構築します。

作成するアプリの概要

3 つのステージのクラウド インフラストラクチャのモックアップ ダッシュボード:

  1. リソースデータをプレーン テキストとして返す標準エージェント
  2. 構造化された A2UI JSON と同じデータを返す A2UI エージェント
  3. ADK Dev UI で A2UI JSON をインタラクティブな UI コンポーネントとして表示するレンダリングされたエージェント

ADK A2UI エージェント

学習内容

  • A2UI の仕組み: 18 個のプリミティブ、UI を構築するメッセージ、フラット コンポーネント モデル
  • A2UI SDK を使用して ADK エージェントに A2UI JSON の生成を求める方法
  • adk web で A2UI コンポーネントをレンダリングする方法

必要なもの

  • 課金を有効にした Google Cloud プロジェクト
  • ウェブブラウザ(Chrome など)
  • Cloud Shell ではなく独自のマシンでコードを実行する場合は、Python 3.12 以降と uv

この Codelab は、Python と Google Cloud にある程度精通している中級レベルのデベロッパーを対象としています。

この Codelab を完了するには約 20 分かかります。

この Codelab で作成するリソースの費用は 5 ドル未満です。

2. 環境を設定する

Google Cloud プロジェクトの作成

  1. Google Cloud コンソールのプロジェクト セレクタ ページで、Google Cloud プロジェクトを選択または作成します。
  2. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

Cloud Shell エディタを起動する

Google Cloud コンソールから Cloud Shell セッションを起動するには、Google Cloud コンソールで [Cloud Shell をアクティブにする] をクリックします。

これにより、Google Cloud コンソールの下部ペインでセッションが起動します。

エディタを起動するには、Cloud Shell ウィンドウのツールバーにある [エディタを開く] をクリックします。

API を有効にする

Cloud Shell エディタのツールバーで、[ターミナル]、[新しいターミナル] の順にクリックし、次のコマンドを実行して必要な API を有効にします。

gcloud services enable aiplatform.googleapis.com

依存関係のインストール

ターミナルで次のコマンドを実行して、この Codelab 用のフォルダを作成します。このフォルダ内には、エージェント コード用の a2ui_agent フォルダがあります。また、Agent Development Kit(ADK)と A2UI SDK をインストールします。

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

uv はこの Codelab 用の隔離された Python 環境を作成するため、何も有効にする必要はありません。Python コマンドの先頭に uv run を付けます。

3. エージェントを構築する

まず、書式なしテキストを返す標準の ADK エージェントから始めます。これが、現在のほとんどのエージェント アプリの外観です。

プロジェクト設定を構成する

ターミナルで次のコマンドを実行して、プロジェクトとロケーションを使用して a2ui_agent/.env を作成し、ADK が Google Cloud プロジェクトを介して Gemini を呼び出すようにします。ADK はこのファイルを自動的に読み込むため、新しいターミナルでも設定が機能します。

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

ツールとモックデータを定義する

次の内容で a2ui_agent/resources.py を作成します。このツールは、ステータスとともにクラウド リソースのリストを返します。

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

エージェントを定義する

以下の内容で a2ui_agent/agent.py を作成します。

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. エージェントをテストする

ADK には、テスト用にブラウザでエージェントを操作してプロンプトを送信するために使用できる開発 UI が含まれています。

ADK 開発 UI を起動する

Cloud Shell エディタのターミナルで、次のコマンドを実行して ADK デベロッパー UI を起動します。

uv run adk web --port 8080 --allow_origins "*" --reload_agents

次のようなメッセージが表示されます。

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8080.                         |
+-----------------------------------------------------------------------------+

ADK 開発 UI を開く

ADK デベロッパー UI をブラウザで開くには、ローカル テスト URL を Ctrl キーまたは Cmd キーを押しながらクリックするか、[ウェブでプレビュー] ボタンをクリックして [ポート 8080 でプレビュー] を選択します。

ADK デベロッパー UI が表示されたら、プルダウン メニューから a2ui_agent を選択します。

サンプル プロンプトを送信する

エージェントにサンプル プロンプトを送信します。

What's running in my project?

別のサンプル プロンプトを試してみましょう。次のようなテキスト出力が得られます。

Does anything need my attention?

会話は次のようになります。

ADK テキスト エージェント

回答は正確ですが、テキストの壁になっています。

5. A2UI JSON を生成する

次に、エージェントをプレーン テキストから A2UI に切り替えます。

A2UI Python SDK には、システム プロンプトを自動的に作成するプロンプト ジェネレータが含まれています。LLM に A2UI コンポーネント カタログ全体、正しいプロパティ名と型、JSON 構造を教えます。

エージェントを更新する

a2ui_agent/agent.py の内容を次のように置き換えます。

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

show_raw_json は A2UI JSON をテキストとして表示するため、読み取ることができます。後で削除して、UI のレンダリングを確認します。

prompt_generator.generate() メソッドは、ロールの説明と完全な A2UI JSON スキーマ、および少数ショットの例を組み合わせるため、LLM は出力をフォーマットする方法を正確に把握できます。コンポーネント カタログを手動で作成する必要はありません。

この Codelab では、adk web A2UI レンダラがサポートするバージョンである A2UI バージョン 0.8(version="0.8")を使用します。

6. JSON 出力をテストする

以前に実行した ADK デベロッパー UI がまだ実行されている場合は、エージェントに加えた変更が自動的に再読み込みされます。

a2ui_agent を選択し、ADK 開発 UI の右上にある [+New Session] をクリックして新しいセッションを開始し、以前と同じプロンプトを送信します。

What's running in my project?

今回は、エージェントはプレーン テキストではなく A2UI JSON で応答します。チャット出力には、beginRendering や surfaceUpdate などの構造化メッセージ(dataModelUpdate が含まれる場合もあります)が JSON コードブロックで表示されます。

ADK A2UI JSON

JSON はカード、アイコン、ボタンを含むリッチな UI を記述しますが、show_raw_json はそれをテキストとして保持するため、読み取ることができます。次に、この JSON の構造を確認し、show_raw_json を削除して実際の UI コンポーネントとしてレンダリングします。

7. A2UI について

エージェントが生成した JSON を確認します。A2UI には、UI の構築に使用する 3 種類のメッセージがあります。エージェントの出力では、3 つすべてが毎回使用されるとは限りません。

1. beginRendering

レンダリング サーフェスを作成し、ルート コンポーネントに名前を付けます。

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

2. surfaceUpdate

コンポーネント ツリーを ID 参照(ネストされていない)を含むフラット リストとして送信します。

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

3. dataModelUpdate

構造とは別にデータを送信します。

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

コンポーネントは {"path": "key"} を使用してデータにバインドされます。コンポーネント ツリーを再送信せずにデータを更新できます。

18 個のプリミティブ

カテゴリ

コンポーネント

レイアウト

カード、列、行、リスト、タブ、区切り線、モーダル

ディスプレイ

テキスト、画像、アイコン、動画、音声プレーヤー

入力

TextField、DateTimeInput、MultipleChoice、CheckBox、Slider

操作

ボタン

エージェントは、これらの同じコンポーネントから、ブラウズビュー、優先順位ダッシュボード、構成フォームなどのさまざまなレイアウトを構築します。各コンポーネントの詳細については、コンポーネント リファレンスをご覧ください。

8. A2UI コンポーネントをレンダリングします。

SDK は A2UI を標準の タグでラップします。adk web はそれらを認識し、組み込みの A2UI レンダラでコンポーネントをレンダリングします。確認するには、show_raw_json を削除します。

エージェントを更新する

a2ui_agent/agent.py の内容を次のように置き換えます。前のステップからの変更点は、show_raw_json 関数、その after_model_callback パラメータ、および使用されていた 2 つのインポートがなくなったことです。

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

9. レンダリングされた UI をテストする

以前に実行した ADK デベロッパー UI がまだ実行されている場合は、エージェントに加えた変更が自動的に再読み込みされます。

ブラウザタブを更新し、a2ui_agent を選択してから、ADK 開発 UI の右上にある [+New Session] をクリックして新しいセッションを開始し、前と同じプロンプトを送信します。

What's running in my project?

今回は、adk web が A2UI コンポーネントを実際の UI(ステータス インジケーター、リソースの詳細、操作ボタンを含むカード)としてレンダリングします。

ADK A2UI エージェント

別のプロンプトを試して、エージェントが同じプリミティブのセットから別の UI を作成する方法を確認します。

Does anything need my attention?

最後に、別のプロンプトを試して、新しいサービスをデプロイするための別の UI を生成します。

I need to deploy a new service

3 つのプロンプトはすべて同じエージェント、ツール、コンポーネントを使用しますが、それぞれ異なる UI が生成されます。

10. クリーンアップ

ローカル サーバーが実行されたままにならないように、リソースをクリーンアップします。

  • adk web を実行しているターミナルで、Ctrl+C キーを押してエージェント サーバーを停止します。

この Codelab 専用のプロジェクトを作成した場合は、プロジェクト全体を削除できます。

gcloud projects delete <YOUR_PROJECT_ID>

11. 完了

A2UI を使用してリッチでインタラクティブな UI を生成する ADK エージェントを構築しました。

学習した内容

  • A2UI は、18 個の宣言型プリミティブと、UI を構築するいくつかのシンプルなメッセージを含むプロトコルです。
  • A2UI SDK は、コンポーネント カタログを LLM に教えるシステム プロンプトを生成します。
  • 同じエージェント、ツール、プリミティブが、さまざまなインテントに対応するさまざまな UI を構成する
  • 開発中に A2UI コンポーネントを adk web で直接レンダリングできます

本番環境のフロントエンドをビルドする

この Codelab では、開発とテストのために adk web 内で A2UI をレンダリングしました。

本番環境では、公式の A2UI レンダラを使用してフロントエンドを構築します。

プラットフォーム

レンダリング

インストール

ウェブ(React)

@a2ui/react

npm install @a2ui/react

ウェブ(Lit)

@a2ui/lit

npm install @a2ui/lit

ウェブ(Angular)

@a2ui/angular

npm install @a2ui/angular

モバイル/パソコン

Flutter GenUI SDK

スタートガイド

リファレンス ドキュメント

次のステップ

Gemini Enterprise Agent Ready(GEAR)を使用してエンタープライズ グレードのエージェントを構築してデプロイするための学習リソースをご覧ください。