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

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

Ouverte
#1,570 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
enhancement proposal
Langage dominant
Python
Étoiles
15.9k
Forks
1.4k
Merge moyen
1 j 17 h
PR mergées (30 j)
163

Description

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

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.