a2ui-project / a2ui-project/a2ui

Modularize SchemaManager class into Catalog-focused components

Offen
#1,923 3 Kommentare 0 Reaktionen 1 zugewiesene Person Beansprucht von @nan-yu Auf GitHub ansehen
component: agent_sdk P2 status: first-line-handled type: feature/enhancement
Vorherrschende Sprache
TypeScript
Sterne
16.4k
Forks
1.3k
Ø Merge
3 T. 15 Std.
Gemergte PRs (30 T.)
134

Beschreibung

## Overview

Currently, `A2uiSchemaManager` in `agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py` combines multiple responsibilities:
1. Loading and holding raw schema dictionaries and component catalog files.
2. Negotiating client capabilities (`supportedCatalogIds` and `inlineCatalogs`).
3. Performing component, message, and schema reachability pruning.
4. Loading and validating catalog example payloads.
5. Assembling and rendering system prompt instructions for LLMs.

We want to move away from a stateful schema manager as the primary representation of catalogs in A2UI Python SDKs, favoring the pure `Catalog` data object in `agent_sdks/python/a2ui_core/src/a2ui/core/catalog/catalog.py`.

## Proposed Component Breakdown

To improve modularity and testability, `A2uiSchemaManager` will be split into single-responsibility classes:

* **`CatalogRepository`**: Manages specification-version schemas (`server_to_client.json`, `common_types.json`) and registered pristine `Catalog` instances.
* **`CatalogResolver`**: Negotiates client capabilities (`a2uiClientCapabilities`) to select matching discrete `Catalog` instances (well-known or inline) according to protocol specification.
* **`CatalogTransformer`**: Abstract interface and pipeline implementations (e.g. `PruningTransformer`, `ComponentAliasTransformer`) performing bidirectional schema and message transformations.
* **`ExampleManager`**: Loads example JSON files and validates them against catalog schemas.
* **`PromptGenerator`**: Formats `Catalog` data objects, workflow rules, and examples into system instruction text. Supports optional schema relaxation (`relax_strict_validation=True`) for LLM prompt rendering without mutating base catalog objects.
* **`A2uiValidator`**: Handles payload and example validation with initializer-level strictness settings (`strict=True\|False`).
* **`A2uiSchemaManager` (Backward Compatibility Facade)**: Retains existing API signatures for existing callers and tests by delegating internally to the new components.

## Sample Integration (`samples/agent/adk/restaurant_finder`)

In sample agents like `samples/agent/adk/restaurant_finder/agent.py`, initializing catalogs and generating prompts becomes clear and explicit:

```python
# 1. Initialize repository and helpers
repository = CatalogRepository(
version=version,
catalogs=[BasicCatalog.get_config(version=version)],
)
example_manager = ExampleManager({repository.default_catalog().catalog_id: f"examples/{version}"})
prompt_generator = PromptGenerator(relax_strict_validation=True)

# 2. Get target Catalog data object
catalog = repository.default_catalog()

# 3. Generate system prompt directly from Catalog data object
instruction = prompt_generator.generate_prompt(
catalog=catalog,
role_description=ROLE_DESCRIPTION,
ui_description=UI_DESCRIPTION,
examples=example_manager.load_examples(catalog, validate=True),
include_schema=True,
)
```

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Die Hauptdatei ist agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py. Überprüfe die aktuelle A2uiSchemaManager-Klasse und das Catalog-Datenobjekt in agent_sdks/python/a2ui_core/src/a2ui/core/catalog/catalog.py. Verstehe die vorgeschlagene Aufteilung der Komponenten und wie sie miteinander interagieren. Die Beispielintegration in samples/agent/adk/restaurant_finder/agent.py zeigt die beabsichtigte Verwendung. Beginne damit, die vorhandenen Tests zu untersuchen, um das aktuelle Verhalten zu verstehen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
backend-api-design
Issue-Typ
Refactoring
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Ruhig
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

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