ag-ui-protocol / ag-ui-protocol/ag-ui
[Feature]: Derive A2UIMiddleware prompt examples from the registered catalog (with override)
- Ngôn ngữ chính
- Python
- Star
- 15.9k
- Fork
- 1.4k
- Merge trung bình
- 1 ngày 17 giờ
- Pull request đã merge (30 ngày)
- 163
Mô tả
## 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
Hướng dẫn đóng góp
Đánh giá
Issue này chưa được đánh giá.