Skip to content

fix(adk): emit the canonical basic catalog id from A2UI Express - #3394

Open
NathanTarbert wants to merge 1 commit into
ag-ui-protocol:mainfrom
NathanTarbert:fix/issue-2869-adk-express-catalog-id
Open

NathanTarbert wants to merge 1 commit into
ag-ui-protocol:mainfrom
NathanTarbert:fix/issue-2869-adk-express-catalog-id

Conversation

@NathanTarbert

Copy link
Copy Markdown
Contributor

compile_a2ui_express now 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 older https://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_id still 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 same createSurface for the same config. The one change in _catalog_for_express is 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 at ag-ui-a2ui-toolkit 0.0.6 today.

Tests: tests/test_a2ui_google_sdk.py checks that compile_a2ui_express with no catalog emits the id BasicCatalog("v0.9") declares, pins that literal so drift on either side shows up, checks that a caller-supplied default_catalog_id is still stamped, and checks that no id at all keeps the basic catalog's own. tests/test_a2ui_protocol_versions.py checks that with no client catalog and a configured default_catalog_id, both Direct JSON and Express put that id on createSurface.

  • New compiler test fails on main and passes with this change
  • Full adk-middleware Python suite passes (1535 passed, 9 skipped)
  • No new ruff findings on changed files

@NathanTarbert
NathanTarbert requested a review from a team as a code owner November 13, 2026 14:59
@github-actions

Copy link
Copy Markdown
Contributor

Python Preview Packages

Version 0.0.0.dev1794581993 published to TestPyPI.

Warning: These packages are built from contributor code that may not yet have been vetted for correctness or security. Install at your own risk and do not use in production.

Install with uv

Add the TestPyPI index to your pyproject.toml:

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = true

Then 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 testpypi

Install with pip

pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  ag-ui-protocol==0.0.0.dev1794581993

Use --extra-index-url https://pypi.org/simple/ so pip can resolve
transitive dependencies (pydantic, fastapi, etc.) from real PyPI.


Commit: e862b3a

@pkg-pr-new

pkg-pr-new Bot commented Nov 13, 2026

Copy link
Copy Markdown

Open in StackBlitz

@ag-ui/a2a-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a-middleware@3394

@ag-ui/a2ui-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2ui-middleware@3394

@ag-ui/event-throttle-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/event-throttle-middleware@3394

@ag-ui/mcp-apps-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mcp-apps-middleware@3394

@ag-ui/mcp-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mcp-middleware@3394

@ag-ui/a2a

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a@3394

@ag-ui/adk-js

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/adk-js@3394

@ag-ui/adk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/adk@3394

@ag-ui/ag2

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/ag2@3394

@ag-ui/agno

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/agno@3394

@ag-ui/antigravity

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/antigravity@3394

@ag-ui/aws-strands

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/aws-strands@3394

@ag-ui/claude-agent-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/claude-agent-sdk@3394

@ag-ui/claude-managed-agents

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/claude-managed-agents@3394

@ag-ui/crewai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/crewai@3394

@ag-ui/langchain

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langchain@3394

@ag-ui/langgraph

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langgraph@3394

@ag-ui/llamaindex

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/llamaindex@3394

@ag-ui/mastra

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mastra@3394

@ag-ui/openai-agents

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/openai-agents@3394

@ag-ui/pydantic-ai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/pydantic-ai@3394

@ag-ui/vercel-ai-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/vercel-ai-sdk@3394

@ag-ui/watsonx

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/watsonx@3394

@ag-ui/a2ui-toolkit

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2ui-toolkit@3394

create-ag-ui-app

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/create-ag-ui-app@3394

@ag-ui/client

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/client@3394

@ag-ui/core

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/core@3394

@ag-ui/encoder

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/encoder@3394

@ag-ui/proto

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/proto@3394

commit: 977b4c6

@surlymochan surlymochan left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 pins cat://host), and the None path is covered by the create_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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants