Create initial implementation for a2ui_agent. by polina-c · Pull Request #1020 · flutter/genui

polina-c · 2026-08-11T18:21:13Z

Prompt:

Use this blueprint to implement the library a2ui_agent: https://github.com/a2ui-project/a2ui/blob/main/blueprints/modules/a2ui_agent.blueprint.md

Next steps:

test coverage
use in genui and create migration plan
port to g3
migrate users

gemini-code-assist

Code Review

This pull request introduces the a2ui_agent package, which provides the A2UI Agent SDK including support for the Direct JSON inference format, streaming parsers, catalog document utilities, and payload validation. The review feedback highlights a critical syntax error in catalog_document.dart where invalid null-aware map syntax is used, and a medium-severity issue in streaming.dart regarding the use of a literal null character in a string literal.

_{Note: Security Review did not run due to the size of the PR.}

…t-lib

polina-c · 2026-08-12T00:42:40Z

If looks ok, I will resolve circlular dependencies.

jacobsimionato

Hey this is looking great - nice work Polina and Gemini! It is a lot of code!

I'm actually finding it okay to review, because it's mostly about the interfaces. But I do wonder about trying to split it a little... e.g. you could probably omit the express format completely in the first PR for example.

I like Nan's idea of trying to do conformance tests up front too. Though they will only really test the implementation, and the more interesting part to review as a human is the APIs and how you've translated them to Dart. So maybe we can human-review the APIs here and not worry too much about the implementation, then add conformance tests and have an agent fix the implementations where necessary.

I dunno, curious about @nan-yu 's thoughts on the best process also. I'd like to make sure that both of us get a proper chance to review the APIs here, because they are important and difficult to change later.

jacobsimionato · 2026-08-12T04:09:27Z

+/// currently being streamed. Formats only implement [emitDelta], which is
+/// handed the whole raw block accumulated so far and returns the messages that
+/// have not been emitted yet.
+abstract class IncrementalStreamProcessor {


This seems like a useful utility - I wonder if it should be in the shared design!

jacobsimionato · 2026-08-12T04:13:18Z

+/// Client functions execute on the renderer, so the agent side carries the
+/// signature but cannot run it. [execute] throws to make an accidental
+/// server-side invocation loud instead of silently wrong.
+class DeclaredFunction extends FunctionImplementation {


I think we should instead handle FunctionApi and FunctionImplementation similar to how we handle ComponentApi and ComponentImplementation in the core library.

E.g. FunctionApi does not declare execute at all, and FunctionImplementation extends FunctionApi.

Then we have Catalog<C extends ComponentApi, F extends FunctionApi> perhaps.

This should also be moved to the a2ui_core layer.

jacobsimionato · 2026-08-12T04:16:31Z

@gspencergoog used ANTLR to generate the core parts of this for Python and Kotlin, based on some language definition file. Can we do that for Dart too? It seems supported - https://github.com/antlr/antlr4

See https://github.com/a2ui-project/a2ui/tree/main/agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/express/generated

Also, feel free to omit the express stuff from the initial PR if you like - it's easy to add as a followup because it's behind a well-defined narrow interface (InferenceFormatFactory, InferenceFormat).

jacobsimionato · 2026-08-12T04:18:52Z

+/// [protocolVersion] and [catalogId], when given, must agree with what the
+/// document declares; a conflict throws [A2uiValidationError] rather than
+/// silently loading a catalog the renderer did not ask for.
+Catalog<ComponentApi> catalogFromDocument(


I think the protocol version and catalog Id should be declared in the document anyway, right?

I think this should be implemented in the core library, possibly on the Catalog and Component classes / interfaces themselves.

Yes, the Catalog class is designed to have from_json and catalog_schema, which builds a Catalog class from a JSON schema, and returns the catalog schema in JSON representation.

jacobsimionato · 2026-08-12T04:21:34Z

+///
+/// The key of the surrounding map describes the example turn; the value is the
+/// A2UI payload the model is expected to produce for it.
+typedef PromptExamples = Map<String, List<AgentToRendererMessage>>;


jacobsimionato · 2026-08-12T04:23:10Z

+  /// Optional few-shot example turns, keyed by a description of the turn.
+  final PromptExamples? examples;
+
+  const PromptGenerator(this.catalogs, {this.examples});


I can't remember what is in the standard design, but I'm wondering if we maybe don't need to expose the catalogs or examples or define a constructor here. Instead, we just expose generate() and each inference format can implement this however it wants.

jacobsimionato · 2026-08-12T04:24:17Z

@nan-yu if we don't have them already, let's add conformance tests requiring that each prompt generator implementation returns exactly the same prompt for a given catalog. Then we know that the eval work we do will translate across library implementations.

We have it already in https://github.com/a2ui-project/a2ui/blob/a70e0ebc7ec37d848f1bd6194d10cc135efb5ab0/agent_sdks/conformance/suites/inference_format.yaml#L191.

Just a heads up, we're planning to restructure the conformance suite to be more modularized, but it will have same coverage.

jacobsimionato · 2026-08-12T04:29:49Z

Also, I think we reached consensus to do this in the A2uI repo, right? I know that was after you created this PR though!

polina-c · 2026-08-12T17:24:49Z

Also, I think we reached consensus to do this in the A2uI repo, right? I know that was after you created this PR though!

I am confused.

I thought we have agreement to copy it to a2ui repo after a2ui repo is ready, together with a2ui_core, that is in monorepo with this code (see a2ui-project/a2ui#2234).

Do you suggest to hold development?

nan-yu · 2026-08-12T22:39:08Z

This should belong to the Dart a2ui_core library, which maps the web_core version, https://github.com/a2ui-project/a2ui/blob/main/renderers/web_core/src/v0_9/schema/client-capabilities.ts#L55.

It actually brings up a broader issue. Should we update the Dart a2ui_core library first, and then build the a2ui_agent on the latest a2ui_core?

nan-yu · 2026-08-12T22:48:29Z

The validation layer should also reside in the a2ui_core layer.

nan-yu · 2026-08-12T22:51:01Z

We have it already in https://github.com/a2ui-project/a2ui/blob/a70e0ebc7ec37d848f1bd6194d10cc135efb5ab0/agent_sdks/conformance/suites/inference_format.yaml#L191.

Just a heads up, we're planning to restructure the conformance suite to be more modularized, but it will have same coverage.

nan-yu · 2026-08-12T23:05:20Z

+
+  @override
+  Catalog<ComponentApi> load() {
+    if (protocolVersion == ProtocolVersion.v09) return MinimalCatalog();


Why MinimalCatalog? Do we have a BasicCatalog in Dart?

nan-yu · 2026-08-12T23:07:20Z

+/// `package:a2ui_core` bundles the minimal catalog for `v0.9`. Other versions
+/// have no bundled catalog in Dart yet, so asking for one is an error rather
+/// than a silent fallback to a catalog the renderer never agreed to.
+class BundledCatalogProvider extends CatalogProvider {


I forgot to update the blueprint when we decided to remove the BundledCatalogProvider class. Nothing needs to be bundled with the SDK. We can use the BasicCatalog directly from a2ui_core. I'll update the blueprint separately.

nan-yu · 2026-08-12T23:21:35Z

+/// Client functions execute on the renderer, so the agent side carries the
+/// signature but cannot run it. [execute] throws to make an accidental
+/// server-side invocation loud instead of silently wrong.
+class DeclaredFunction extends FunctionImplementation {


This should also be moved to the a2ui_core layer.

nan-yu · 2026-08-12T23:23:13Z

+/// [protocolVersion] and [catalogId], when given, must agree with what the
+/// document declares; a conflict throws [A2uiValidationError] rather than
+/// silently loading a catalog the renderer did not ask for.
+Catalog<ComponentApi> catalogFromDocument(


Yes, the Catalog class is designed to have from_json and catalog_schema, which builds a Catalog class from a JSON schema, and returns the catalog schema in JSON representation.

nan-yu · 2026-08-12T23:26:31Z

+import '../utils/schema_utils.dart';
+
+/// A single problem found in an A2UI payload.
+class A2uiValidationIssue {


Can we rename to A2uiValidationError? It should also go to the a2ui_core layer.

nan-yu · 2026-08-12T23:27:46Z

+/// This is the agent SDK's validation layer. The A2UI agent specification
+/// delegates it to `A2uiValidator` in the core package;
+/// `package:a2ui_core` does not ship one yet, so the checks live here and
+/// operate on the `v0.9` envelopes that package models.


The validator in a2ui_core should support validation against all protocol versions.

nan-yu · 2026-08-12T23:29:43Z

Most of these unit tests should be moved to conformance spec, so we don't repeat for each implementation.

polina-c added 12 commits August 10, 2026 17:22

-

8572646

-

d4c616c

Update a2ui_agent_example.dart

3cc5223

Update CHANGELOG.md

9545b0c

Update pubspec.yaml

fb8690d

Update pubspec.yaml

1ca909b

-

d128c2c

-

fdf246b

-

f092604

Create format.dart

3cd13c9

-

b0d9e3e

-

209bbca

gemini-code-assist Bot reviewed Aug 11, 2026

View reviewed changes

Comment thread packages/a2ui_agent/lib/src/utils/catalog_document.dart

Comment thread packages/a2ui_agent/lib/src/inference_formats/direct_json/streaming.dart

polina-c added 7 commits August 11, 2026 11:29

-

1e94e1b

-

fffe38e

Create direct_json_parser_test.dart

dcb0995

-

19e72ab

Merge branch 'main' of https://github.com/flutter/genui into implemen…

0f882e5

…t-lib

-

e9bd3bf

Update CHANGELOG.md

04f2187

polina-c marked this pull request as ready for review August 11, 2026 20:26

Update pubspec.yaml

442d1a6

jacobsimionato reviewed Aug 12, 2026

View reviewed changes

Merge branch 'main' into implement-lib

d8d49be

nan-yu reviewed Aug 12, 2026

View reviewed changes

Uh oh!

Conversation

polina-c commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

polina-c commented Aug 12, 2026

Uh oh!

jacobsimionato left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobsimionato commented Aug 12, 2026

Uh oh!

polina-c commented Aug 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

polina-c commented Aug 11, 2026 •

edited

Loading