ag-ui-protocol / ag-ui-protocol/ag-ui
[Feature]:AGUI.A2UI: NuGet release plan, and why components are node-based?
- 主要言語
- Python
- スター
- 15.9k
- フォーク
- 1.4k
- 平均マージ
- 1日 17時間
- マージ済み PR(30日)
- 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 はまだ評価されていません。