feat(js/plugins/a2ui): add a2ui plugin

[pavelgj]

Adds @genkit-ai/a2ui, a Genkit plugin that lets an agent stream A2UI ("Agent to UI") surfaces — rich, interactive UI rendered incrementally by the client — instead of just prose. Also adds a runnable js/testapps/a2ui sample (Express backend + Vite/Lit frontend).

Status: proof-of-concept / exploration.

How it works

A2UI travels on its own channel: a Genkit data part with mime type application/a2ui+json whose payload is an array of A2UI envelope messages (1:1 with the A2UI spec's A2A binding). The whole server integration is a single model middleware, a2ui(), added to an agent's use array. It injects the catalog's capabilities into the system prompt, then intercepts model output (streamed chunks and the final message), extracts a2ui fenced blocks, validates them against the catalog, and rewrites them into a2ui data parts.

Server usage

import { genkit } from 'genkit/beta';
import { googleAI } from '@genkit-ai/google-genai';
import { a2ui, basicCatalog } from '@genkit-ai/a2ui';

const ai = genkit({ plugins: [googleAI()] });

export const uiAgent = ai.defineAgent({
  name: 'uiAgent',
  model: 'googleai/gemini-flash-latest',
  system: 'You help users. Render UI when it is clearer than prose.',
  use: [a2ui()], // <- the only A2UI-specific line
});

Client usage

@genkit-ai/a2ui/client is browser-safe. Pull envelopes off each chunk with a2uiEnvelopes and feed them to a renderer (e.g. @a2ui/lit); send user actions (button presses, form submits) back with actionToMessage:

import { a2uiEnvelopes, actionToMessage } from '@genkit-ai/a2ui/client';
import { MessageProcessor } from '@a2ui/web_core/v0_9';
import { basicCatalog } from '@a2ui/lit/v0_9';
import { remoteAgent } from 'genkit/beta/client';

const chat = remoteAgent({ url: '/api/uiAgent' }).chat();
const processor = new MessageProcessor([basicCatalog], (action) =>
  runTurn({ message: actionToMessage(action) })
);

async function runTurn(input) {
  const turn = chat.sendStream(input);
  for await (const chunk of turn.stream) {
    if (chunk.text) appendProse(chunk.text);
    const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk.content);
    if (envelopes.length) processor.processMessages(envelopes);
  }
}

runTurn('weather in Tokyo');

What's included

• Plugin (js/plugins/a2ui): a2ui() middleware, envelope parser/validator, the basic catalog + model-facing instructions, and the browser-safe /client entrypoint (a2uiEnvelopes, actionToMessage, streamA2uiAgent). Options: catalog (required), instructions ('system'), validate ('strict'), surfaceId, version ('v0.9'). Unit tests for the middleware and parser.
• Testapp (js/testapps/a2ui): Express server exposing the agent + a Vite/Lit chat UI that renders surfaces, with a getWeather demo tool and suggested prompts.

Testing

• pnpm -C js/plugins/a2ui test
• Manual: cd js/testapps/a2ui && genkit start -- pnpm start, open http://localhost:8080 — tried weather, comparisons, and a signup form (values round-trip back to the agent).

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[pavelgj]

/gemini review

[pavelgj]

/gemini review

[pavelgj]

/gemini review

[pavelgj]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the @genkit-ai/a2ui plugin, which enables Genkit agents to stream rich, interactive UI surfaces using the A2UI protocol. It includes the server-side a2ui() middleware, browser-safe client helpers, a streaming parser, and a complete runnable test application. The review feedback highlights several critical robustness issues where the code lacks defensive checks when handling message content and parts, which could lead to runtime TypeErrors or data corruption if the input structures are not arrays or valid objects.