ag-ui-protocol / ag-ui-protocol/ag-ui
Publish machine-readable JSON Schema definitions for AG-UI event types
- Dominant language
- Python
- Stars
- 15.9k
- Forks
- 1.4k
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 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.
Contributor guide
Assessment
This issue has not been assessed yet.