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

Publish machine-readable JSON Schema definitions for AG-UI event types

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

Descripción

## Request

AG-UI currently uses TypeScript types via `@ag-ui/core` as the canonical definition for its event types (`RUN_STARTED`, `INTERRUPT`, `STATE_SNAPSHOT`, etc.). This works well for TypeScript consumers, but leaves a gap for tooling that needs machine-readable JSON Schema definitions — specifically for `$schema` references in agent manifests and for non-TypeScript implementations.

## Why this matters

Agent manifests that want to declare AG-UI-compatible fields (e.g. renderer hints in `INTERRUPT` payloads, or event capability declarations) cannot reference a stable schema URL today:

```json
{
"hitlScreens": {
"$schema": "https://agui.dev/schemas/renderer-registry/v1.json",
"renderers": ["@my-agent:review-form"]
}
}
```

No such URL exists. This means:

- Tooling authors must duplicate type definitions manually
- Non-TypeScript agent implementations (Python, Go, etc.) have no machine-readable contract to validate against
- Agent manifests cannot declare provenance of AG-UI-derived fields

## Proposal

Publish JSON Schema definitions for at minimum:

- All 16 core AG-UI event types (`AgUiEvent` union and each member)
- The `INTERRUPT` event payload shape (including `xRenderer`, `schema`, `values`, `reviewTaskId`)
- The `Message`, `State`, and `Context` models

The TypeScript types remain canonical. JSON Schema can be generated from them (e.g. via `typescript-json-schema` or `ts-json-schema-generator`) and published as a derived artifact at a stable URL, with a note that the TypeScript types are authoritative in case of conflict.

A stable URL pattern like `https://docs.ag-ui.com/schemas/{version}/{type}.json` would enable `$schema` references in agent tooling.

## Context

We are building an AI agent platform that implements AG-UI for runtime HITL interaction. We want agent manifests to declare which fields follow the AG-UI standard via `$schema` — making interoperability explicit — but cannot do so without published schema URLs.

The absence of a stated reason for this gap in the docs suggests it may simply not have been prioritized yet rather than being a deliberate design decision.

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.