a2ui-pydantic

A Python implementation of the A2UI (Agent to UI) protocol using Pydantic. This library provides type-safe, validated models for building AI agent interfaces that render natively across web, mobile, and desktop platforms.

About A2UI

A2UI is a protocol that enables AI agents to generate rich, interactive user interfaces through declarative component descriptions. Instead of executing arbitrary code, agents send structured JSON messages that clients render using their own native widgets. Learn more at a2ui.org.

Features

• ✅ Complete A2UI v0.8 Schema Support - Full implementation of the A2UI specification
• ✅ Type-Safe Models - Built with Pydantic v2 for runtime validation and type checking
• ✅ 18 Component Types - Text, Image, Button, Form inputs, Layout containers, and more
• ✅ Message Types - BeginRendering, SurfaceUpdate, DataModelUpdate, DeleteSurface
• ✅ Data Binding - Support for literal values and data model path references
• ✅ Comprehensive Validation - Automatic validation of required fields, enums, and constraints
• ✅ Python 3.11+ - Modern Python with type hints throughout

Installation

Using uv (Recommended)

uv add a2ui-pydantic

Using pip

pip install a2ui-pydantic

From Source

git clone https://github.com/nurokhq/a2ui-pydantic.git
cd a2ui-pydantic
uv sync --all-groups

Quick Start

Creating a Simple UI Message

from a2ui_pydantic import (
    A2UIMessage,
    BeginRendering,
    SurfaceUpdate,
    SurfaceComponent,
    ComponentWrapper,
    TextComponent,
    ButtonComponent,
    Action,
    Styles,
)

# Create a begin rendering message
message = A2UIMessage(
    beginRendering=BeginRendering(
        surfaceId="main",
        root="header",
        styles=Styles(
            font="Roboto",
            primaryColor="#00BFFF"
        )
    )
)

# Create a surface with components
text_comp = TextComponent(
    text={"literalString": "Welcome to A2UI"},
    usageHint="h1"
)

button_comp = ButtonComponent(
    child="button-text",
    action=Action(name="submit", context=[])
)

update_message = A2UIMessage(
    surfaceUpdate=SurfaceUpdate(
        surfaceId="main",
        components=[
            SurfaceComponent(
                id="header",
                component=ComponentWrapper(Text=text_comp)
            ),
            SurfaceComponent(
                id="button-text",
                component=ComponentWrapper(Text=TextComponent(
                    text={"literalString": "Click Me"}
                ))
            ),
            SurfaceComponent(
                id="submit-btn",
                component=ComponentWrapper(Button=button_comp)
            )
        ]
    )
)

# Serialize to JSON
import json
print(json.dumps(message.model_dump(by_alias=True), indent=2))

Using Data Binding

from a2ui_pydantic import (
    DataModelUpdate,
    DataModelEntry,
    TextComponent,
)

# Update data model
data_update = DataModelUpdate(
    surfaceId="main",
    path="/user",
    contents=[
        DataModelEntry(key="name", valueString="Alice"),
        DataModelEntry(key="age", valueNumber=30),
    ]
)

# Reference data in components
text_with_binding = TextComponent(
    text={"path": "/user/name"}  # Binds to data model
)

Project Structure

a2ui_pydantic/
├── __init__.py          # Public API exports
├── base.py              # Base models (Literal*OrPath, etc.)
├── components.py        # All 18 component types
├── messages.py          # Message types (A2UIMessage, etc.)
├── data_model.py        # Data model structures
├── actions.py           # Action and context models
└── enums.py             # Enumeration types

Development

Setup

# Clone the repository
git clone https://github.com/nurokhq/a2ui-pydantic.git
cd a2ui-pydantic

# Install with dev dependencies
uv sync --all-groups

Running Tests

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=a2ui_pydantic --cov-report=term

# Run specific test file
uv run pytest tests/test_components.py

Linting and Type Checking

# Run pylint
uv run pylint a2ui_pydantic tests

# Run mypy
uv run mypy a2ui_pydantic tests

# Run bandit (security)
uv run bandit -r a2ui_pydantic

Component Reference

The library supports all A2UI v0.8 components:

Content Components:

• TextComponent - Text with usage hints (h1-h5, body, caption)
• ImageComponent - Images with fit modes and usage hints
• IconComponent - Icons from the A2UI icon set
• VideoComponent - Video playback
• AudioPlayerComponent - Audio playback with description

Layout Components:

• RowComponent - Horizontal layout with distribution/alignment
• ColumnComponent - Vertical layout with distribution/alignment
• ListComponent - List with direction (vertical/horizontal)
• CardComponent - Card container
• TabsComponent - Tabbed interface
• DividerComponent - Visual separator
• ModalComponent - Modal dialog

Form Components:

• ButtonComponent - Button with actions
• CheckBoxComponent - Checkbox input
• TextFieldComponent - Text input (short/long/obscured/number/date)
• DateTimeInputComponent - Date and time picker
• MultipleChoiceComponent - Multi-select options
• SliderComponent - Numeric slider

Message Types

• BeginRendering - Initialize a new surface with root component and styles
• SurfaceUpdate - Update or create a surface with components
• DataModelUpdate - Update the data model for a surface
• DeleteSurface - Remove a surface

Data Binding

Components support two value types:

1. Literal Values - Direct values (e.g., {"literalString": "Hello"})
2. Path References - Data model paths (e.g., {"path": "/user/name"})

This enables dynamic UIs where component values are bound to a data model that can be updated independently.

Resources

• A2UI Official Website - Protocol documentation and guides
• A2UI Specification - Complete technical specification
• A2UI GitHub - Official A2UI repository

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request to the GitHub repository.

Status

This library implements the A2UI v0.8 (Stable) specification. The A2UI protocol is currently in public preview and may evolve. This library will be updated to track specification changes.