Scaling catalogs beyond prompt size: exploring layered catalogs

[sarthak96agarwal]

Summary

A2UI's current catalog model assumes the negotiated catalog fits comfortably into the LLM's prompt. This works well for the Basic Catalog and small custom catalogs, but breaks down for federated catalogs — where many teams contribute components to a shared catalog and the total component count grows into the hundreds.

This discussion proposes layered catalogs, a generalization that preserves A2UI's negotiation, trust, and graceful-degradation properties while letting agents work with catalogs that exceed practical prompt sizes. It's informed by the "progressive disclosure skills" mention in the v0.9 announcement and tries to suggest a concrete shape for what that might look like.

I'd value input on whether this aligns with the direction maintainers are already considering, and whether the layered model captures the right primitive.

The problem

A2UI compiles the catalog into the agent server and includes it in the system prompt — that's what teaches the LLM what components exist. This is fine when catalogs are small.

It breaks for federated catalogs: a platform team owns a shared catalog, multiple product teams contribute domain-specific components, total count grows from tens to hundreds. At that scale, loading the whole catalog into the prompt eats context, dilutes attention, and degrades component-selection accuracy. This is the same failure mode that motivated progressive disclosure in agent skill systems, and that I believe is gestured at in the v0.9 announcement.

The existing escape valves don't really solve it: multi-catalog negotiation still loads each negotiated catalog whole, surface-level catalog selection is locked for the surface lifetime, and inline catalogs are discouraged for trust reasons.

What this draws on

Progressive disclosure is a well-established pattern for managing context in agent systems. Claude Agent Skills converged on a tiered loading model (lightweight metadata index → activated content → on-demand references) for exactly this problem one layer up the stack. The pattern has converged across the broader agent ecosystem because the underlying constraint — context windows are finite, catalogs of agent capabilities are not — is universal.

A2UI's own v0.9 announcement gestured at this with the mention of progressive disclosure "skills" for A2UI. This proposal tries to suggest a concrete shape for what that might look like, drawing on patterns that have converged elsewhere while preserving A2UI's distinctive properties (compiled-in catalogs, negotiation, graceful degradation).

Key insight: "compiled into the agent server" ≠ "loaded into the LLM prompt"

The current spec conflates two ideas because at small catalog sizes the distinction doesn't matter:

• Trust boundary: the catalog is compiled into the agent server, signed, predictable. Nothing fetched from untrusted sources at runtime.
• Prompt content: the catalog is in the system prompt so the model can generate valid output.

These don't have to be the same thing. A scaling proposal can preserve the trust property while relaxing the prompt-content one. The full catalog stays compiled into the agent server — only a relevant subset needs to be in the LLM prompt for any given turn.

This separation is the foundation everything else rests on.

Proposed primitive: layered catalogs

A catalog gains an optional layer structure. A layer is a self-contained subset of components, declared by the catalog publisher, with a natural-language description of when it applies.

catalog: example/v1
catalogId: https://example.com/catalogs/v1/catalog.json

layers:
  core:
    description: "Layout primitives and text. Always present."
    always_loaded: true
    components: [Row, Column, Card, Text, Button]

  research:
    when_to_load: "User asks about documents, articles, or citations."
    components: [DocumentList, DocumentCard, Citation]

  data_viz:
    when_to_load: "User asks for trends, comparisons, or numerical data."
    components: [Chart, DataTable, Sparkline, MetricCard]

  scheduling:
    when_to_load: "User wants to pick dates or manage time-based events."
    components: [DatePicker, Calendar, TimeSlotPicker]

The full catalog is the union of layers. The full catalog is still compiled into the agent server. Only a small core layer plus a lightweight layer index (just (layer_name, when_to_load) pairs) is always in the prompt — the bulk of the catalog stays out until needed.

When the agent decides a turn calls for a particular layer, it activates that layer for the surface, which loads its full schemas and examples into the prompt. Activation is the same kind of decision agents already make for tool selection. The LLM can only activate layers that exist in the negotiated catalog, so the trust boundary is preserved.

A non-layered catalog is equivalent to a single layer with always_loaded: true — so migration is smooth and backward compatibility is straightforward.

Negotiation extension

Client capability declaration extends naturally:

{
  "a2uiClientCapabilities": {
    "supportedCatalogIds": ["https://example.com/catalogs/v1/catalog.json"],
    "supportedLayers": {
      "https://example.com/catalogs/v1/catalog.json": ["core", "research", "data_viz"]
    }
  }
}

A client may support a catalog without supporting all its layers — for example, a mobile client might omit a heavyweight layer that doesn't fit its surface. A client that doesn't declare supportedLayers is treated as supporting all layers (backward compatibility).

Layer activation as a protocol message

The agent declares activated layers when creating a surface, mirroring how catalogId is locked today:

{
  "createSurface": {
    "surfaceId": "answer_1",
    "catalogId": "https://example.com/catalogs/v1/catalog.json",
    "activeLayers": ["core", "data_viz"]
  }
}

This becomes the contract for the surface — the agent will only emit components from active layers for its lifetime. Visible at the protocol level for audit, debugging, and renderer code-splitting.

Properties preserved

• Trust — layers are part of the compiled-in catalog. Nothing fetched at runtime.
• Negotiation — the existing handshake is extended, not replaced.
• Graceful degradation — component-level fallback applies; layer negotiation prevents most cases.
• Locked-per-surface semantics — active layers lock for surface lifetime, like catalogId.

Why layered, rather than per-component retrieval at generation time

Per-component retrieval (embed catalog, retrieve top-k per query) is a popular pattern but a worse protocol-level primitive: it weakens the "compiled in, signed" property, fragments compositional reasoning across components, and complicates versioning. Layers are publisher-declared and coarse-grained, which keeps the protocol clean. Per-component retrieval is fine as an implementation detail of how an agent picks which layers to activate — it just shouldn't be the protocol-level concept.

Open questions

I'm leaving these unresolved because they benefit from broader input:

1. Activation lifetime: Locked for surface lifetime (like catalogId), or evolvable as the conversation progresses?
2. Cross-layer composition: When two layers are active, can a component from one have children from the other? My intuition is yes, but the rules should be explicit.
3. Layer-level versioning: Independent within a catalog, or all moving with the catalog version?
4. Default for legacy clients: A client supporting a catalog but not declaring supportedLayers — all layers, or core only? I lean toward all layers.
5. Relationship to "skills" already being designed: If maintainers have an internal direction here, I'd much rather align with it than propose something parallel.

What I'd value from this discussion

• Whether maintainers have an internal design for "skills" already, and where it diverges from this.
• Whether the layered primitive feels right, or whether a different shape (templates, capability tags, something else) better fits A2UI's design philosophy.
• Concrete failure modes I haven't anticipated.
• Whether prototyping this against a real federated catalog and reporting back would be useful.

Happy to iterate on any of this. Thanks for reading.