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

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

未關閉
#2,610 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement
主要語言
Python
星號
15.9k
分支
1.4k
平均合併
1 天 17 小時
30 天內合併 PR
163

描述

### 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_

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。