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

[Feature]: Derive A2UIMiddleware prompt examples from the registered catalog (with override)

オープン
#2,010 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement
主要言語
Python
スター
15.9k
フォーク
1.4k
平均マージ
1日 17時間
マージ済み PR(30日)
163

説明

## Problem or Motivation

`A2UIMiddleware` (`@ag-ui/a2ui-middleware`) teaches the agent how to call the render tool using a fixed, generic prompt. When `injectA2UITool` is enabled, the middleware injects `RENDER_A2UI_TOOL_GUIDELINES`, whose worked example is a single generic "Minimal Working Example" (a button) — regardless of the catalog/schema the app has actually registered.

Surface generation quality depends heavily on the examples in the prompt. An app with a custom catalog (custom component names, props, composition conventions) gets surfaces generated against a generic button example rather than examples that match its real components. The only workaround today is to fork the middleware or post-process its injected context.

Notably, the middleware **already receives the catalog** — `A2UIMiddlewareConfig.schema` (the inline catalog) is injected into context via `injectSchemaContext`. So the information needed to produce catalog-accurate examples is already present; it just isn't used to build the worked example.

## Proposed Solution

**Primary: auto-derive the worked example from the registered catalog.**
Instead of always emitting the hardcoded generic button example, have `injectToolGuidelines()` build the example from the components in the configured `schema` (component names, required props, child/slot wiring). Apps that register a catalog then get examples that match their real components with **zero extra config**.

**Secondary: allow an explicit override** for apps that want hand-curated examples.
Mirror the `A2UIGuidelines` shape introduced for the toolkit in #1894 so the two paths stay consistent:

```ts
interface A2UIMiddlewareConfig {
schema?: A2UIInlineCatalogSchema | A2UIComponentSchema[];
injectA2UITool?: boolean | string;
a2uiToolNames?: string[];
defaultCatalogId?: string;

// NEW
guidelines?: {
generationGuidelines?: string;
designGuidelines?: string;
compositionGuide?: string;
};
}
```

**Resolution order for the worked example:**
1. Explicit `guidelines` override, if provided
2. Else derived from the registered `schema`/catalog
3. Else fall back to the current generic built-in example (back-compat)

This keeps existing callers working (they fall through to step 3), fixes the root cause for the common case, and still allows full control when needed.

## Alternatives Considered

**Post-process the injected context manually** — strip the guidelines context entry after `run()` and replace it. Works but is fragile and requires every consumer to know the internal `description` key (`"A2UI render tool usage guide — how to call {toolName} with valid arguments."`).

**Fork the middleware** — the current only real workaround; obviously not sustainable for library consumers.

**Why the toolkit fix (#1894 / OSS-248) doesn't cover this** — #1894 made guidelines configurable (`generationGuidelines` / `designGuidelines` / `compositionGuide`) but only in the `@ag-ui/a2ui-toolkit` + LangGraph tool-factory path. Its scope note states explicitly: *"Out of scope (by design): middleware config prop. Tool-factory surface only; middleware untouched."* Apps consuming A2UI through `A2UIMiddleware` still have no way to get catalog-accurate or overridable examples.

## Additional Context

**Acceptance criteria:**
- When a `schema`/catalog is registered, `A2UIMiddleware` derives the worked example from it instead of the generic built-in
- Apps can still override the examples/guidelines explicitly (no fork required)
- Callers that register no schema keep the current generic example (back-compat)
- Override field semantics match the toolkit `A2UIGuidelines` from #1894

**References:**
- #1894 (OSS-248) — made guidelines configurable in the toolkit, explicitly leaving the middleware out of scope

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。