ag-ui-protocol / ag-ui-protocol/ag-ui

[Feature]:AGUI.A2UI: NuGet release plan, and why components are node-based?

Abierto
#2,610 0 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement
Lenguaje dominante
Python
Estrellas
15.9k
Forks
1.4k
Merge medio
1 d 17 h
PR fusionados (30 d)
163

Descripción

### Pre-flight Checklist

- [x] I have searched existing issues and this hasn't been requested yet.

### Problem or Motivation

### Context
We're building on MAF + `Microsoft.Agents.AI.Hosting.AGUI.AspNetCore` and evaluating
A2UI support. We pulled `sdks/dotnet/src/AGUI.A2UI` + `AGUI.A2UI.Toolkit` from `main`
since they're not on NuGet yet. Two questions before we commit to an architecture.

---

### 1. Release plan

NuGet currently has the core SDK packages at `0.0.6` under the `ag-ui-protocol` owner:

- `AGUI.Abstractions`, `AGUI.Server`, `AGUI.Client`, `AGUI.Formatting`, `AGUI.Protobuf`

...but **not** `AGUI.A2UI` or `AGUI.A2UI.Toolkit`.

- Is there a release plan / rough timeframe for the two A2UI packages?
- Are they intentionally held back (e.g. blocked on A2UI v1.0, which is RC upstream
while the Toolkit is pinned to v0.9)?
- Until then, is building from `main` the recommended path, or too unstable to depend on?

---

### 2. Why are A2UI components node-based?

`AGUI.A2UI` / `AGUI.A2UI.Toolkit` model components as `JsonNode` and take the catalog
as a runtime JSON Schema (`A2UIValidationCatalog`). We're trying to understand whether
that's a deliberate permanent design or just the current state — because the rest of
the SDK solves the same problem differently.

**The AG-UI core in this very repo is strongly typed** — `AGUI.Abstractions` is ~104
files: 50 event classes, 28 message classes, 14 capability classes, with a polymorphic
`BaseEventJsonConverter`. And `BaseEvent.cs` carries this comment:

```csharp
// Keep in sync with sdks/typescript/packages/core/src/events.ts
```

So strong typing and three-SDK wire compatibility already coexist here — which is why
the A2UI choice isn't obvious to us.

The "open component set" concern (clients ship custom catalogs) also looks already
solved by the existing pattern: known shapes are typed, unknown ones fall back to
`JsonElement` (`BaseEvent.RawEvent`, `BaseEvent.Metadata`, `CustomEvent.Value`).

So, concretely:

- Is the node-based model for A2UI **deliberate and permanent**, or simply where it
landed and open to revisiting?
- If deliberate: what drove it — catalog openness, A2UI v1.0 churn, or something the
A2UI surface has that the AG-UI event model doesn't?
- Would typed built-ins (from the basic catalog) + `JsonElement` for custom catalog
entries be compatible with your direction, or does that conflict with it?

---

### Proposed Solution

To be clear: we're not proposing to implement this ourselves — we'd like to know
whether this is the direction the SDK is heading, so we can plan around it either way.

The shape that would work for us:

1. **Typed model for the built-in catalog.** A2UI components (Text, Column, Row,
Card, Button, TextField, …) as real C# types — a `Component` base with
per-component derived types — matching how `AGUI.Abstractions` already models
events: `BaseEvent` + ~50 typed event classes + `BaseEventJsonConverter`.

2. **Keep the escape hatch for open catalogs.** Components outside the known set
fall back to `JsonElement`/`JsonNode`, exactly as `CustomEvent.Value` and
`BaseEvent.Metadata` already do. Custom client catalogs keep working unchanged.

3. **No wire change.** The JSON crossing AG-UI stays identical, so TS and Python
remain compatible. This is already proven in-repo: `BaseEvent.cs` carries
"Keep in sync with sdks/typescript/packages/core/src/events.ts" — typed models
and three-SDK wire compat already coexist there.

4. **Validation stays catalog-driven.** `A2UIComponentValidator` +
`A2UIValidationCatalog` remain the source of truth; a typed layer sits alongside
them rather than replacing them.

If none of this fits the SDK's direction, that's a perfectly fine answer — we mainly
need to know, so we can decide whether to build and maintain this layer ourselves.

### Alternatives Considered

- Build and maintain a typed model + renderer as a third-party package (what we do
today). Works, but duplicates the component catalogue and risks drifting from the
SDK as A2UI moves to v1.0.
- Consume `JsonNode` directly and do string dispatch in the renderer. Rejected:
silent failures on typos, poor trimming behaviour.

### Additional Context

_No response_

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.