IA · A2UI

A2UI

@vueui-nova/a2ui 1.0.0@a2ui/web_core 0.15.0Protocolo A2UI v1.0Catálogo v1: 77 componentes

A2UI (Agent-to-UI) é um protocolo aberto em que o agente responde com uma descrição de interface em JSON, em vez de texto ou HTML. O app recebe essas mensagens e monta a tela com os próprios componentes. A ui-nova é um catálogo A2UI completo, e o pacote @vueui-nova/a2ui é o renderer Vue.

O que é o A2UI v1.0

  • Versão-alvo: v1.0, a atual. A v0.9 é a anterior e a v0.8 (beginRendering, surfaceUpdate) está deprecada.
  • O agente manda uma lista plana de componentes com ids, um deles root, e um data model separado. Valores podem ser literais, {"@path": "/x"} ou chamadas de função {"@call": …}.
  • Inputs escrevem só no data model local. O agente recebe os valores quando uma action dispara, com o context já resolvido.
  • O agente só pode usar componentes do catálogo que o app anuncia. Prop ou componente inventado vira error com path, para o agente se corrigir.
  • O protocolo não depende de transporte: funciona sobre A2A, AG-UI, MCP, WebSocket ou SSE/JSONL. O tema fica 100% no app, porque a v1.0 removeu theme da mensagem.

Fluxo de mensagens

DireçãoMensagemCampos principais
agente → renderercreateSurfacesurfaceId, catalogId, components (lista plana, um com id: "root"), dataModel, sendDataModel
agente → rendererupdateComponentssurfaceId, components: substitui ou adiciona por id
agente → rendererupdateDataModelsurfaceId, path (JSON Pointer), value (null remove)
agente → rendererdeleteSurfacesurfaceId
agente → renderercallRendererFunction / agentFunctionResponseRPC de funções (gh:specification/v1_0/docs/a2ui_custom_functions.md)
renderer → agenteactionname, surfaceId, sourceComponentId, timestamp, userMessage?, context
renderer → agenteerrorcode (VALIDATION_FAILED, INTEGRITY_ERROR, INVALID_FUNCTION_CALL, UNALLOWED_PARENT, UNALLOWED_CHILD, EXPRESSION_ERROR), message, surfaceId, path
renderer → agentecallAgentFunction / rendererFunctionResponseRPC no sentido inverso

Como a ui-nova se encaixa

  • Catálogo: 77 componentes (71 da lib e 6 primitivos do adapter: Column, Divider, Image, List, Row, Text), 14 funções do catálogo básico e 127 ícones. Ele é gerado do código da lib e está em /a2ui/catalog/v1.json.
  • Renderer: um adapter Vue sobre @a2ui/web_core, o núcleo dos renderers oficiais (React, Lit, Angular). Não existe renderer Vue oficial.
  • Mapeamento: cada componente do catálogo aponta para um V*. O bind vira v-model, os eventos viram action e @accessibility vira aria-*.
  • Skills: 5 skills ensinam agentes a usar a lib e gerar payloads válidos.

Os 111 componentes da lib no catálogo

GrupoQuantidadeCritério
catálogo v171 (+6 primitivos do adapter = 77)Serializável e útil para agentes. Componentes compostos usam bind múltiplo; inputs sensíveis exigem opt-in do host (D11).
fora do catálogo40Shell de app, composables, motion e interações que não cabem no protocolo (drag-and-drop, upload de arquivo, menus por coordenada). Cada um tem o motivo no mapeamento.

API

Renderer
import { createA2uiRenderer } from '@vueui-nova/a2ui'

const renderer = createA2uiRenderer({
  compat: true,                           // aceita também o catálogo básico (D4)
  onAction: (msg) => transport.send(msg), // envelope {version:'1.0', action:{...}}
  onError:  (msg) => transport.send(msg),
  urlPolicy: { allow: [/^https:\/\/(.+\.)?empresa\.com\//] },
  onOpenUrl: (url) => window.open(url, '_blank', 'noopener'),
  hostFunctions: [/* createFunctionImplementation(...) do host (opcional) */],
})

transport.onMessage((env) => renderer.process(env))   // ou await renderer.processStream(asyncIterable)
renderer.capabilities()                                // a2uiClientCapabilities para o agente
Componente
<A2uiSurface :runtime="renderer" surface-id="chamado_7f3a" announce />
<!-- ou <A2uiSurfaces :runtime="renderer" /> para renderizar todas as surfaces ativas -->

Entrega

Todos os lotes do plano estão concluídos na versão 1.0.0.

  1. L0Núcleoconcluído

    @a2ui/web_core 0.15 dentro de Vue

    Resultado: D2 = web_core: MessageProcessor, Catalog, DataContext e SurfaceModel do core; o Vue lê um espelho reativo. lit é dependência do core e fica externo ao bundle

  2. L1Fundaçãoconcluído

    Pacote, createA2uiRenderer/createA2uiRuntime, A2uiSurface/A2uiSurfaces, fallback, UrlPolicy, limites, @accessibility, capabilities()

  3. L2Adapters Aconcluído

    Primitivos + exibição e layout

  4. L3Adapters Bconcluído

    Inputs, interação e dados (Table com templates e rowAction)

  5. L4Testes e conformanceconcluído

    Vitest (componentes, segurança, runtime, SSR) + YAMLs oficiais da v1.0 + Playwright/axe na doc

    Resultado: npm test no pacote; relatório em packages/a2ui/reports/conformance.json

  6. L5Catálogo, skills, CIconcluído

    --check dos geradores, skills, README, CHANGELOG, workflow de CI

  7. L6Documentaçãoconcluído

    /docs/ia (A2UI, catálogo, playground, galeria, decisões), skills

  8. L7Catálogo completoconcluído

    Componentes que dependiam de bind múltiplo, overlays e política de inputs sensíveis

    Resultado: unificados no catálogo v1 (77); o restante ficou fora com motivo final

Conformance

O pacote roda os casos oficiais da v1.0 (adapter_conformance, actions e accessibility) a cada npm test: 38 aprovados e 9 não aplicáveis a este renderer, cada um com o motivo.

Caso não aplicávelMotivo
multi_catalog_mixed_surface_renderingCatálogos customizados definidos no YAML: o renderer registra só o catálogo ui-nova e o básico (D4).
teardown_unmount_releases_subscriptionsA view não assina o modelo por nó: lê o espelho reativo do Vue, que o Vue limpa ao desmontar; não há contador de assinaturas para comparar.
delete_surface_unmounts_viewO caso conta assinaturas por nó, e a view lê o espelho reativo do Vue. O deleteSurface remove o espelho e as assinaturas do runtime (tests/runtime.test.ts).
removed_components_release_subscriptionsO caso conta assinaturas por nó, que esta view não cria. O componente removido some do espelho e da árvore (tests/runtime.test.ts).
media_components_bind_url_and_nameVideo e AudioPlayer do catálogo básico não têm componente na ui-nova; na compat (D4) viram fallback + error, sem player embutido.
agent_function_action_failure_reports_expression_errorCatálogo customizado com função do agente (callAgentFunction): o renderer não registra catálogos de terceiros.
test_action_event_with_data_bindingcaso v0.9 (bindings `path`/`call` sem @): o renderer implementa só a v1.0
test_action_event_with_relative_scopecaso v0.9 (bindings `path`/`call` sem @): o renderer implementa só a v1.0
test_accessibility_interactive_roles_and_statesNa compat (D4) ChoicePicker vira o Select da lib (combobox com listbox), não um radiogroup; o papel ARIA difere por decisão.

Por onde continuar

As 12 decisões de projeto estão em Decisões. A galeria mostra cada componente do catálogo renderizado, e os exemplos rodam fluxos completos no renderer.