Limitations of A2UI: Understanding the Constraints of Google's Agent-to-UI Protocol

A2UI is a declarative JSON protocol that intentionally sacrifices styling flexibility, dynamic scripting, and arbitrary component support to ensure safe, portable agent-to-client communication, requiring strict catalog versioning and graceful degradation when components are unavailable.

A2UI (Agent-to-UI) is Google's declarative protocol enabling LLM-driven agents to describe user interfaces as structured JSON rather than executable code. While this approach ensures security and cross-platform compatibility, the google/A2UI repository explicitly documents several architectural constraints that teams must evaluate before adoption. Understanding these A2UI limitations helps determine when the protocol fits agent-driven workflows and when traditional UI frameworks become necessary.

Core Architectural Constraints

Limited Scope: Not a UI Framework

According to docs/introduction/what-is-a2ui.md, A2UI is explicitly not a UI framework or HTML replacement. It transports only declarative component trees, meaning it cannot express arbitrary client-side logic or custom JavaScript. This intentional design choice prioritizes safety over expressive power, preventing agents from injecting executable code while limiting the complexity of interactions that can be described.

No Robust Styling System

The protocol lacks comprehensive styling capabilities. As documented in the same file, only minimal server-side style hints are supported—typically limited to predefined variant strings like "primary" or "secondary". The client bears full responsibility for visual styling, making fine-grained brand consistency difficult across different renderer implementations.

{
  "component": "Button",
  "variant": "primary",
  "child": "submit-text",
  "action": { "event": { "name": "confirm" } }
}

The variant field represents the only styling hook available; arbitrary CSS classes or inline styles cannot be transmitted through the protocol.

Component Catalog and Versioning Limitations

Strict Catalog Dependency

Agents can only request components defined in the client's implemented catalog. The file docs/concepts/catalogs.md establishes that structural changes—including new components or additional properties—require publishing a new catalog version (e.g., incrementing from v0.9 to v0.10). Both the agent SDK and client renderer must upgrade simultaneously to maintain compatibility.

{
  "version": "v0.9",
  "surfaceUpdate": {
    "components": [
      {
        "component": "Button",
        "tooltip": "Click to confirm"
      }
    ]
  }
}

Adding a tooltip property to an existing Button component constitutes a breaking change that invalidates the payload against the v0.9 schema, forcing a version bump before deployment.

LLM-Friendly Schema Constraints

The JSON schema must remain flat and explicit to support reliable LLM generation. Complex, deeply nested structures are discouraged according to the design principles in docs/introduction/what-is-a2ui.md, constraining how expressive UI hierarchies can be. This limitation ensures predictable agent output but restricts sophisticated layout compositions.

Runtime Validation and Degradation Issues

Two-Phase Validation Requirements

A2UI implements validation at both agent-side (pre-send) and client-side (runtime). As detailed in docs/concepts/catalogs.md, any validation failure forces the agent to fall back to plain text or alternative UI strategies rather than attempting partial rendering. This strict validation flow protects against malformed payloads but reduces flexibility when handling edge cases.

Graceful Degradation Necessity

Even after schema validation, runtime problems such as missing assets, unimplemented components, or platform-specific constraints require the client to degrade gracefully. When a renderer encounters an undefined component, it must substitute a placeholder rather than crashing.

{
  "version": "v0.9",
  "surfaceUpdate": {
    "surfaceId": "demo",
    "components": [
      {
        "id": "profile",
        "component": "FacePile",
        "users": ["alice", "bob"]
      }
    ]
  }
}

If the client catalog does not include FacePile, the renderer in renderers/lit/ will replace it with a generic card or skip the component entirely, potentially degrading the user experience.

Performance and Implementation Gaps

Latency from LLM Fallbacks

The personalized learning demo in samples/personalized_learning/README.md documents significant performance limitations. When keyword-based routing fails, the system triggers LLM generation, introducing 2-5 seconds of latency. The orchestration logic in src/chat-orchestrator.ts demonstrates this bottleneck:

if (!keywordMatch) {
  const response = await llm.generateTopicFallback(userQuery);
}

This fallback mechanism, while robust, creates noticeable delays in interactive workflows.

Content Retrieval Accuracy

The demo's keyword-based routing system can produce incorrect source citations. Production deployments would require semantic search or reranking infrastructure to replace the sample's simple dictionary matching, adding complexity not addressed in the current implementation.

Deployment and Feature Limitations

The sample implementation assumes a fixed directory layout (renderers/lit located at ../../renderers/lit), requiring manual path updates if the repository structure changes. Additionally, the demos lack multi-topic handling, dynamic audio/video generation capabilities, and fully-featured sidebar UI components, as noted in the sample documentation.

Security and Dynamic Behavior Trade-offs

Because the protocol transmits only declarative data, it cannot express arbitrary client-side logic. While this creates a strong security boundary that prevents code injection, it eliminates the ability to implement complex state management, real-time calculations, or custom interactions outside the agent's direct control. This limitation is permanent and architectural, not merely a missing feature.

Summary

• A2UI is strictly declarative and cannot replace full UI frameworks or execute arbitrary JavaScript
• Component changes require catalog version bumps, preventing rapid iteration without coordinated updates
• Styling is limited to predefined client-side variants with no support for custom CSS or inline styles
• Runtime validation failures force immediate fallback strategies rather than partial error recovery
• LLM-friendly schema constraints discourage complex nested structures, limiting UI expressiveness
• Sample implementations exhibit 2-5 second latency during LLM fallbacks and lack advanced features like multimedia generation
• Deployment scripts assume rigid directory structures that require manual configuration changes

Frequently Asked Questions

Can A2UI handle custom JavaScript or dynamic client-side logic?

No. According to docs/introduction/what-is-a2ui.md, A2UI explicitly avoids executable code transmission. The protocol sends only declarative JSON data, making it impossible to express custom JavaScript or complex client-side state management. This is an intentional security feature that limits dynamic behavior but ensures safe rendering across platforms.

What happens when an agent requests a component not supported by the client?

The client must implement graceful degradation. As documented in docs/concepts/catalogs.md, when a renderer encounters an undefined component like FacePile, it replaces the component with a generic placeholder or skips it entirely rather than throwing an error. This requires robust fallback UI patterns in the client implementation to maintain user experience continuity.

Why does adding a new component property require a catalog version update?

A2UI enforces strict schema compliance through its catalog versioning system. The file docs/concepts/catalogs.md states that structural changes—including new properties like a tooltip field on a Button component—constitute breaking changes that demand a new catalog version. Both agent and client must upgrade simultaneously because the protocol validates payloads against specific schema versions before rendering.

How does A2UI's keyword-based routing impact performance?

The personalized learning demo reveals that keyword-based routing failures trigger LLM fallback generation, introducing 2-5 seconds of latency according to samples/personalized_learning/README.md. Additionally, this approach can produce inaccurate content citations, suggesting production deployments would need semantic search or reranking infrastructure to replace the demo's simple keyword matching algorithm.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}