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

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

Offen
#2,010 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
Vorherrschende Sprache
Python
Sterne
15.9k
Forks
1.4k
Ø Merge
1 T. 17 Std.
Gemergte PRs (30 T.)
163

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.