A complete, runnable sample of A2UI with Genkit Dart, split into two packages:
server/: a plaindart:ioHTTP server hosting an A2UI-enabled Genkit agent. The whole A2UI integration is thea2ui()middleware frompackage:genkit_a2ui/a2ui.dartin the agent'suselist. It is a member of the root pub workspace.client/: a Flutter app that streams the agent withremoteAgentand renders each surface witha2ui_flutter(ana2ui_coreMessageProcessorplus anA2uiSurfacewidget per surface). Button presses and form submits are sent back to the agent as the next turn.
The client deliberately does not depend on genkit_a2ui. A2UI travels as
spec-shaped data parts, so the client needs only package:genkit,
a2ui_flutter, a2ui_core, and the two helpers in
client/lib/a2ui_helpers.dart (copied from the genkit_a2ui README). That way
the server package's dependencies can never constrain which renderer version
the client uses. It is also why the two halves are separate packages: pub
resolves a whole package at once, so a shared pubspec would pull the server's
dependencies into the client.
It also demonstrates a custom catalog: a bespoke Gauge component that is
not part of the bundled basic catalog. See "Custom catalog"
below.
- Flutter SDK.
- A Gemini API key in
GEMINI_API_KEY.
-
Start the agent server (terminal 1). Run
dart pub getonce at the repository root, then:cd testapps/a2ui/server dart run build_runner build --delete-conflicting-outputs GEMINI_API_KEY=your-key dart run bin/server.dartIt listens on
http://localhost:8080and mounts the agent at/api/uiAgent. -
Run the Flutter client (terminal 2):
cd testapps/a2ui/client flutter pub get flutter run -d chromePoint it at a different server with
--dart-define=AGENT_BASE_URL=http://host:port.
The client's widget tests (flutter test in client/) render a surface from
canned messages, so they need neither the server nor an API key.
- "What's the weather in Tokyo?" renders a weather card.
- "Show the weather in Tokyo with a gauge." renders the custom
Gaugecomponent (see below). - "Compare the weather in London, Paris and Rome." renders a comparison.
- "Give me a short signup form (name and email) with a submit button." renders a form; submitting sends the entered values back to the agent.
- The
a2ui()middleware turns the model's UI blocks into a2uidataparts ({"messages": [...]}, mimeapplication/a2ui+json) on both the streamed chunks and the final message. - The client reads those messages with
a2uiMessagesFromand feeds each to aMessageProcessor, which creates and updates the surfaces. The client catalog has the same catalog id the agent uses, so surfaces resolve to real widgets. - The renderer reports a button press as a spec-shaped
{version, action}message.a2uiActionToMessageforwards it untouched as the next turn, and the middleware summarizes it for the model.
By default the a2ui() middleware uses the bundled basic catalog (Text,
Card, Column, Button, ...). This sample instead ships its own catalog that adds
a bespoke Gauge component. A catalog has two halves that must agree on a
catalog id (here com.example.a2ui.weather, in each package's
lib/shared.dart):
- Server (
server/lib/agent.dart):weatherCatalogis the model-facing half. The middleware injects it into the system prompt so the model knowsGaugeexists, and validates that emitted surfaces only reference components in the catalog.registerCatalogs()(called fromserver/bin/server.dart) registers it withloadCatalog(...), and the agent selects it witha2ui(catalog: weatherCatalogId, validate: 'strict'). - Client (
client/lib/gauge.dart+client/lib/catalog.dart):gaugeis an a2ui_flutterComponentImplementation(aname, a propschema, and abuilderthat paints the gauge).catalog.dartlists it next to the basic components in aCatalogImplementationunder the same id.
The name on both sides ('Gauge') and the catalog id must match, otherwise the
model would emit a Gauge the client can't render, or the client would register
widgets under an id no surface references.