title: swift-a2ui README created: 2026-06-27 tags: [a2ui, swift, spm, llm, ui-protocol] status: active

swift-a2ui

Google A2UI プロトコルの Swift 完全実装 — LLM エージェントがクライアントにリッチ UI を描画するための型安全なライブラリ群

概要

swift-a2ui は A2UI (Agent-to-UI) プロトコル の Swift 実装です。LLM エージェントが JSON メッセージを通じてクライアント上に宣言的な UI サーフェスを生成・更新・削除し、ユーザーのアクションを受け取ってレスポンスを返す仕組みを、コンパイル時型安全な Swift API として提供します。

主な特徴

• A2UI v0.10 完全対応: createSurface / updateComponents / updateDataModel / callFunction / actionResponse の全メッセージ型を実装
• 型安全なカタログ: Swift の型システムを SSOT とした LLM 向けスキーマ生成（JSON ファイルとの乖離をコンパイル時に検出）
• AnyView ゼロのジェネリックレンダラー: カタログを型パラメータとした A2UISurfaceView<Catalog> で、型消去なしに SwiftUI へ描画
• 公式プロトコルへの忠実な準拠: Python SDK (a2ui.adk / a2ui.a2a) の設計をそのまま Swift に写したモジュール構成
• マルチエージェント対応: A2A プロトコル統合とサーフェス所有権台帳によるオーケストレーション

モジュール構成

13 のモジュールを役割ごとに 5 グループに分けて説明します。

グループ 1 — コアプロトコル層

A2UI の有線フォーマット（JSON）を Swift の型として定義する最下層。SwiftUI も LLM クライアントも依存しない。

主な型:

// サーバ → クライアント
public enum ServerMessage: Sendable, Equatable, Codable {
    case createSurface(CreateSurface)
    case updateComponents(UpdateComponents)
    case updateDataModel(UpdateDataModel)
    case deleteSurface(DeleteSurface)
    case callFunction(CallFunctionMessage)
    case actionResponse(ActionResponseMessage)
}

// クライアント → サーバ
public enum ClientMessage: Sendable, Equatable, Codable {
    case action(UserAction)
    case error(ClientError)
    case functionResponse(FunctionResponse)
}

グループ 2 — コンポーネントカタログ

LLM が使えるコンポーネントのパレットを型として定義し、その定義から LLM 向け JSON Schema を自動生成する層。

内蔵コンポーネント（BasicComponentCatalog）:

スキーマは Swift 型から自動生成されるため、実装とスキーマが乖離することはない:

// スキーマ生成
let schema: String = BasicComponentCatalog.catalogSchemaJSON()

// カタログ ID
let id: String = BasicComponentCatalog.catalogId
// → "https://a2ui.org/specification/v0_10/catalogs/basic/catalog.json"

グループ 3 — LLM プロンプト・パーサー

エージェントに渡すシステムプロンプトの組み立てと、LLM 出力からの A2UI メッセージ抽出を担う。

プロンプトの組み立て:

// 標準 builder（カタログ・メッセージ全種）
let builder = A2UIPromptBuilder()
let prompt = builder.buildSystemPrompt(
    role: "You are a helpful assistant that renders UI.",
    uiDescription: "Show a card with a title and a confirm button."
)

// presenter プリセット（コンテンツ提示向け 9 コンポーネント + 3 メッセージに絞る）
let presenterBuilder = A2UIPromptBuilder.presenter()

// カスタム pruning
let builder = A2UIPromptBuilder(
    allowedComponents: ["Text", "Column", "Row", "Button", "Image"],
    allowedMessages: ["CreateSurfaceMessage", "UpdateComponentsMessage"]
)

ストリーミングパーサーの使い方:

let parser = A2UIStreamingParser()

for chunk in llmStream {
    let parts = parser.feed(chunk)
    for part in parts {
        if let messages = part.messages {
            // A2UI ServerMessage 配列を描画系へ流す
            await surface.apply(messages)
        }
        if let text = part.text {
            // プレーンテキスト部分
            print(text)
        }
    }
}
let finalParts = parser.finalize()

グループ 4 — サーフェス状態 / レンダラー

クライアント上のサーフェス状態管理と SwiftUI 描画を担う。

A2UISurfaceView の使い方:

import SwiftUI
import A2UITypedRenderer

// 1. サーフェスを作成（@Observable なので @State に持てる）
@State var surface = TypedSurface<BasicCatalog>(rootId: "root", nodes: [])

// 2. サーフェスメッセージを適用するハンドラ
func apply(_ message: ServerMessage) {
    switch message {
    case .updateComponents(let msg):
        guard let nodes = try? TypedSurface<BasicCatalog>.decodeNodes(
            fromJSONArray: JSONEncoder().encode(msg.components)
        ) else { return }
        surface.applyUpdateComponents(nodes)
    case .updateDataModel(let msg):
        surface.applyUpdateDataModel(path: msg.path, value: msg.value)
    default:
        break
    }
}

// 3. SwiftUI に埋め込む
var body: some View {
    A2UISurfaceView(surface, busy: isGenerating)
}

カスタムカタログの合成:

// 独自コンポーネントを BasicCatalog に上乗せ
enum AppCatalog: A2UICatalog {
    typealias Node = CombinedNode<MyNode, BasicComponent>
    static let catalogId = "com.example.my-app"
}

// BasicEmbeddingNode 準拠で BasicCatalog のレンダラーを再利用
extension MyNode: BasicEmbeddingNode { ... }

グループ 5 — エージェント統合 / オーケストレーション

LLM エージェントへの A2UI ツール提供と、マルチエージェント構成を担う。

A2UIPresenterAgent の注入例:

import A2UIAgent
import A2ACore
import LLMClient

// presenter エージェントに必要なものはすべてライブラリ側が持つ
let agentName = A2UIPresenterAgent.defaultName

// 1. system prompt
let systemPrompt = A2UIPresenterAgent.systemPrompt(language: "Japanese")

// 2. tools（カタログパレットはカスタマイズ可能）
let tools = A2UIPresenterAgent.tools(
    components: ["Column", "Row", "Text", "Image", "Icon", "List", "Card", "Button", "Divider"]
)

// 3. A2A card の extensions に宣言
let agentExtension = A2UIPresenterAgent.agentExtension()

// 4. オーケストレータの system prompt に注入する制約
let constraint = A2UIPresenterAgent.hostOutputConstraint(agentName: agentName)

オーケストレーション（SurfaceOwnership）:

import A2UIOrchestration

var ownership = SurfaceOwnership()

// サブエージェントの応答を受け取るたびに所有権を記録
ownership.record(surfacesCreatedIn: responseparts, by: "a2ui")

// UserAction をルーティング（LLM 呼び出し不要）
if let agent = ownership.owner(ofUserActionIn: incomingParts) {
    // 対象エージェントへ直接転送
    await router.send(to: agent, parts: incomingParts)
}

// 送信前にデータモデルをエージェントの所有サーフェスだけに絞る
let metadata = try ownership.outboundMetadata(
    baseMetadata,
    capabilities: clientCapabilities,
    for: "a2ui"
)

インストール

Swift Package Manager

Package.swift の dependencies に追加:

.package(url: "https://github.com/no-problem-dev/swift-a2ui.git", from: "0.0.1"),

ターゲットの dependencies で必要なモジュールを列挙:

.target(
    name: "MyApp",
    dependencies: [
        // 最小構成（コアのみ）
        .product(name: "A2UICore", package: "swift-a2ui"),

        // プロンプト組み立て + パーサー
        .product(name: "A2UIPrompt", package: "swift-a2ui"),
        .product(name: "A2UIParser", package: "swift-a2ui"),

        // SwiftUI レンダラー（iOS/macOS UI）
        .product(name: "A2UITypedRenderer", package: "swift-a2ui"),

        // LLM エージェントツール
        .product(name: "A2UIAgentTool", package: "swift-a2ui"),

        // presenter エージェント自己記述
        .product(name: "A2UIAgent", package: "swift-a2ui"),

        // A2A 統合 / オーケストレーション
        .product(name: "A2UIA2A", package: "swift-a2ui"),
        .product(name: "A2UIOrchestration", package: "swift-a2ui"),
    ]
)

対応プラットフォーム

Swift ツールズバージョン: 6.2

外部依存パッケージ

ライセンス

LICENSE を参照してください。

最終更新: 2026-06-27