Repository navigation
fix(adk): emit the canonical basic catalog id from A2UI Express - #3394
NathanTarbert wants to merge 1 commit into
Conversation
Python Preview PackagesVersion
Install with uvAdd the TestPyPI index to your [[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = trueThen install the packages you need: # Core SDK
uv add 'ag-ui-protocol==0.0.0.dev1794581993' --index testpypi
# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1794581993' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1794581993' --index testpypi
# NOTE: ag-ui-agent-spec depends on pyagentspec (git-only, not on PyPI).
# You will need to install pyagentspec separately from its git repo.
uv add 'ag-ui-agent-spec==0.0.0.dev1794581993' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1794581993' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1794581993' --index testpypiInstall with pippip install \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
ag-ui-protocol==0.0.0.dev1794581993
Commit: e862b3a |
@ag-ui/a2a-middleware
@ag-ui/a2ui-middleware
@ag-ui/event-throttle-middleware
@ag-ui/mcp-apps-middleware
@ag-ui/mcp-middleware
@ag-ui/a2a
@ag-ui/adk-js
@ag-ui/adk
@ag-ui/ag2
@ag-ui/agno
@ag-ui/antigravity
@ag-ui/aws-strands
@ag-ui/claude-agent-sdk
@ag-ui/claude-managed-agents
@ag-ui/crewai
@ag-ui/langchain
@ag-ui/langgraph
@ag-ui/llamaindex
@ag-ui/mastra
@ag-ui/openai-agents
@ag-ui/pydantic-ai
@ag-ui/vercel-ai-sdk
@ag-ui/watsonx
@ag-ui/a2ui-toolkit
create-ag-ui-app
@ag-ui/client
@ag-ui/core
@ag-ui/encoder
@ag-ui/proto
commit: |
surlymochan
left a comment
There was a problem hiding this comment.
Verified the two code changes against the tests and the rest of the repo (code search, default branch):
Verified:
- The new default matches what the Python a2ui SDK declares: the test pins
BasicCatalog("v0.9").to_json()["catalogId"]to the new URL, so the ADK default now agrees with the SDK instead of stamping the old pre-v0.9 URL that a renderer registered under the new id cannot resolve. - The
if default_catalog_id:guard is right: a caller-chosen id still wins (test pinscat://host), and theNonepath is covered by thecreate_express_processor(None, default_catalog_id=None, ...)case, which keeps the catalog's own id instead of failing. - Both inference formats are covered by the parametrized test in test_a2ui_protocol_versions.py.
One cross-SDK inconsistency to check before merge: the old URL is still the v0.9 basic catalog id in two other places — sdks/typescript/packages/a2ui-toolkit/src/index.ts:17 (BASIC_CATALOG_ID) and middlewares/a2ui-middleware/src/protocol.ts (basicCatalogId("v0.9")). If a host renderer registers the basic catalog under either of those, a surface stamped with this PR's new id will not resolve there, which is the same failure mode this PR fixes, just moved to the TS side. Is the old URL still the correct id in those places (e.g. a fetch URL rather than the declared id), or do they need the same update to the new URL? If they are out of scope for this PR, a follow-up issue would be worth filing so the two SDKs do not disagree on the v0.9 id.
compile_a2ui_expressnow defaults to the catalog id the official basic catalog declares for itself,https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json. Its previous default was the olderhttps://a2ui.org/specification/v0_9/basic_catalog.json, which the spec host answers with a 404, so a fixed-layout surface compiled without a catalog could not be resolved by a renderer that registers the basic catalog under its declared id.Part of #2869. The other places that issue lists are covered by open PRs: #2786 for the A2UI middleware, #2771 from @manjunathshiva for the .NET toolkit, and #2696 from @Jokasa7 for the Python and TypeScript toolkits.
This builds on @contextablemark's #3374, which made Express follow the catalog's protocol version. A configured
default_catalog_idstill wins when Express falls back to the basic catalog. That id has to match what the host renderer registered, and Direct JSON already uses it in the same situation, so the two formats keep giving the samecreateSurfacefor the same config. The one change in_catalog_for_expressis for the case where no id is given at all. The basic catalog now keeps its own id there instead of failing.The A2UI tool gets its default from the toolkit's
BASIC_CATALOG_ID, so this PR leaves that constant and the TypeScript middleware alone. The tool follows once #2696 is released and the adk-middleware lock picks up the new toolkit, which is pinned atag-ui-a2ui-toolkit0.0.6 today.Tests:
tests/test_a2ui_google_sdk.pychecks thatcompile_a2ui_expresswith no catalog emits the idBasicCatalog("v0.9")declares, pins that literal so drift on either side shows up, checks that a caller-supplieddefault_catalog_idis still stamped, and checks that no id at all keeps the basic catalog's own.tests/test_a2ui_protocol_versions.pychecks that with no client catalog and a configureddefault_catalog_id, both Direct JSON and Express put that id oncreateSurface.