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

[Bug]: ag-ui-a2ui-toolkit BASIC_CATALOG_ID does not match the A2UI v0.9 spec canonical catalog $id (surfaces rejected by @a2ui/react)

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

Descripción

## Summary

`ag_ui_a2ui_toolkit.BASIC_CATALOG_ID` (v0.0.4) is `https://a2ui.org/specification/v0_9/basic_catalog.json`, which does **not** match the canonical A2UI v0.9 basic catalog `\$id` used by the reference renderer `@a2ui/react`. Surfaces emitted with the toolkit's constant are rejected at render time with `A2uiStateError: Catalog not found`.

## Evidence

The A2UI v0.9 basic catalog published at the spec host declares its own `\$id`:

```
\$ curl -s https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json | head -5
{
"\$schema": "https://json-schema.org/draft/2020-12/schema",
"\$id": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json",
"title": "A2UI Basic Catalog",
...
}
```

The toolkit's URL does not resolve:

```
\$ curl -s -o /dev/null -w "%{http_code}\n" https://a2ui.org/specification/v0_9/basic_catalog.json
404
```

The reference renderer registers the catalog under the canonical spec path:

```js
// @a2ui/react/v0_9
basicCatalog.id === "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"
```

## Impact

A backend using `create_surface(surface_id, BASIC_CATALOG_ID)` from `ag_ui_a2ui_toolkit` produces a surface whose `catalogId` is `.../basic_catalog.json`. When the `@a2ui/react` `MessageProcessor` (initialized with `basicCatalog`) processes that surface, it throws:

```
A2uiStateError: Catalog not found: https://a2ui.org/specification/v0_9/basic_catalog.json
```

because no catalog is registered under that ID. The surface never renders.

## Expected

`BASIC_CATALOG_ID` should equal the canonical spec `\$id`:

```python
BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"
```

## Environment

- `ag-ui-a2ui-toolkit` 0.0.4 (PyPI)
- `@a2ui/react` (renderer, a2ui.org reference implementation)

## Workaround

Consumers currently hardcode the canonical spec URL instead of importing the constant:

```python
BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"
```

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.