AGenUI: a native A2UI renderer for iOS, Android and HarmonyOS

What AGenUI renders, and who it is for

An LLM that returns a JSON description of a card, a form or a list still leaves you with the problem of turning that description into pixels on a phone. AGenUI takes that description, parses it as it arrives, and draws it with the native UI toolkit of the host platform. The README states the SDK "renders the streaming data of LLM-generated interactive UI in real time on mobile devices" and that it implements the A2UI v0.9 protocol open-sourced by Google.

The audience is narrow and specific: mobile engineers on iOS, Android or HarmonyOS who already have an agent or backend emitting A2UI component trees and who do not want a WebView in the middle. The README lists the supported floors as Android API 21+, iOS 13+, and HarmonyOS NEXT API 17+. Teams building for the browser are outside the scope entirely, since the repository ships platform directories for ios, android and harmony and nothing else.

The component set is the practical measure of fit. There are 22 built-in components: 18 that implement the A2UI protocol (Text, Image, Icon, Divider, Video, AudioPlayer, Button, Row, Column, Card, List, Tabs, Modal, TextField, CheckBox, Slider, ChoicePicker, DateTimeInput) and 4 SDK extensions that are not part of the protocol, starting with Table. If your generated UI needs something outside those 22, the custom component API is the escape hatch, and the README says it lets the LLM emit component descriptions by component name.

The C++ core and how a component tree reaches the screen

The architecture is a shared C++ core engine plus three platform rendering engines. The README assigns a concrete list of jobs to the C++ layer: streaming data parsing, virtual component tree management, render data caching, theme and style resolution, and component change diffing. The core then synchronizes the parsed component protocol to the platform renderers, which trigger drawing.

That split explains the directory layout. core/ holds the engine, and core/include/ is described as the public C++ API consumed by the platform bridging layers. Each platform pairs a renderer with a bridge of a different kind: platforms/ios/ has an Objective-C bridge, platforms/android/ uses JNI, and platforms/harmony/ uses NAPI. The diffing step is the part worth noting for anyone reasoning about cost. Because the core diffs component changes before handing them to the renderer, an incremental update to a card does not require the platform layer to re-render the whole tree.

The performance claim in the README is specific: native rendering on all three platforms, "maintaining a 120 fps refresh rate in core scenarios such as page scrolling". That is a claim from the project, not an independent measurement, and the README does not state the device, the component mix or the payload size behind it. Treat it as a target the project sets for itself rather than a number you can plan against.

Building AGenUI and rendering your first surface

The README points to docs/QuickStart.md for setup and docs/API.md for the reference; there is no package-manager one-liner in the README itself. The repository also carries npm/, agent_sdks/, samples/ and a playground/ directory described as three-platform demo apps for development and debugging, plus scripts/ with build scripts for each platform. The realistic first step is to clone the repository and run the platform build script for your target.

git clone https://github.com/AGenUI/AGenUI.git
cd AGenUI
ls scripts/

That listing shows the per-platform build scripts. Which script you run depends on whether you are targeting ios, android or harmony; the README does not enumerate the script names, so read the directory rather than guessing.

The one configuration call the README documents in detail is the iOS runtime configuration API added in v1.5.0. It takes a JSON string of runtime switches from the host, and the README is explicit about the timing: call it once during SDK initialization, before any surface renders.

AGenUI.setRuntimeConfig(_:)

The borderPixelAlignment switch defaults to on. Per the release notes, it promotes hairline borders to an integer physical pixel width so all four sides render with identical weight across screen scales, and snaps component frames to the physical pixel grid so adjacent siblings stay gap-free. If you turn it off, you are opting back into the sub-pixel behaviour it was added to fix. The README does not show the JSON payload that carries that switch, so read docs/API.md before wiring the call in.

Before writing any of this into an app, check the release you are building against. AGenUI-1.4.0 was released on 2026-08-28 and AGenUI-1.5.0.beta1 on 2026-09-04. The runtime configuration API, the pixel alignment work and the onBlankCheckResult signature change are all listed under v1.5.0, so they are beta-channel features.

Breaking changes, beta-only APIs and the upgrade tax

The clearest limitation is not a missing feature, it is the release channel. The newest tag in the repository is AGenUI-1.5.0.beta1, published on 2026-09-04, while the newest stable-looking tag is AGenUI-1.4.0 from 2026-08-28. Everything the README advertises under What's New in v1.5.0 sits on the beta line, including the runtime configuration API that a host app would call during initialization. A team that pins to 1.4.0 does not get it.

One of those v1.5.0 changes is an outright break. The release notes state that onBlankCheckResult on iOS now reports the component-tree size at detection time and that the signature becomes onBlankCheckResult(_ surface:isBlank:componentCount:). Any existing iOS code implementing the two-argument form will not compile against the new signature. The README does not document a migration path or a deprecation shim for it.

The platform caveats are uneven. The font-weight catalog work in v1.5.0 is described as accepting normal, medium and bold keywords plus numeric 100-900 weights, as either a JSON number or an integer string, "with platform caveats documented in the catalog" rather than in the README. If you are relying on weight rendering, the catalog file is the place to check, not the release notes.

There is also a gap between what the README promises and what it explains. The Function Call integration is described as letting you register client-side tools or functions the LLM can invoke on demand, but the README gives no example of the registration call or its lifecycle. The custom component API is likewise described in one line without a sample. For both, docs/API.md is the only lead the README offers.

AGenUI against a web renderer for the same protocol

The natural alternative is a web-based A2UI renderer, the kind of thing that turns the same component JSON into DOM nodes inside a WebView or a browser tab. The difference is not the protocol, it is where the drawing happens. A web renderer gets one implementation that runs everywhere a browser runs, and it inherits the layout and styling model of CSS. AGenUI instead keeps a C++ core for parsing, diffing and style resolution, then hands the result to Objective-C, JNI and NAPI bridges so that each platform draws with its own toolkit.

That choice buys native scrolling, native text input, native video and audio playback, and native modals, which is why the README can talk about a 120 fps target in scroll scenarios. It costs you three bridge layers to maintain and a C++ toolchain in your build. A web renderer has the opposite profile: broader reach, one code path, and the performance and input quirks of a WebView on mobile.

A second alternative is to skip the protocol layer and hand-write screens per platform. That is the right answer when the UI is fixed and only the data varies. AGenUI only earns its place when the structure of the UI itself is generated, and when that structure has to arrive incrementally while the model is still producing it.

Licence, maintenance and what an upgrade actually costs

AGenUI is licensed under Apache-2.0, and the repository carries both a LICENSE and a NOTICE file at the top level. Apache-2.0 permits commercial use and modification and includes a patent grant, but the NOTICE file matters: if you redistribute the SDK you need to carry the notices forward. That is a general property of the licence, not advice about your situation.

The last push to the default branch was on 2026-09-10, and the repository is not archived. Releases have been frequent through August and September 2026, with 1.4.0.beta2 on 2026-08-22, 1.4.0 on 2026-08-28 and 1.5.0.beta1 on 2026-09-04. The README itself says the project "is under active development and evolving rapidly", which is the project's own framing and also a warning about API stability.

The upgrade cost follows from the architecture. Because the C++ core is shared, a change in the core can move behaviour on all three platforms at once, and the v1.5.0 HarmonyOS line-height rework is an example of a measurement change that alters how text lays out. The iOS onBlankCheckResult signature change is an example of a platform-specific break. Budget for reading CHANGELOG.md on every bump, and for keeping the three platform bridges in step rather than upgrading one at a time.

Editorial conclusion

Adopt AGenUI if you are shipping a native iOS, Android or HarmonyOS app and want A2UI component streams drawn by the platform's own UI stack instead of a web view. Do not adopt it if you are building for the web, if you need a stable API surface today, or if you are not prepared to build the C++ core and bridge layers yourself. Before committing, read docs/QuickStart.md and confirm which of the 22 components your screens actually need, then check whether the platform you target is covered by the 1.5.0 beta notes or only by 1.4.0, because the iOS runtime configuration API and the HarmonyOS line-height rework landed after that stable tag.

Frequently asked questions

Official sources

1. AGenUI/AGenUI on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases