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

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

未關閉
#1,570 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement proposal
主要語言
Python
星號
15.9k
分支
1.4k
平均合併
1 天 17 小時
30 天內合併 PR
163

描述

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

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。