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

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

Abierto
#2,010 2 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement
Lenguaje dominante
Python
Estrellas
15.9k
Forks
1.4k
Merge medio
1 d 17 h
PR fusionados (30 d)
163

Descripción

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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.