Skip to content

fix(adk): give each new A2UI surface an id of its own - #3396

Open
AlemTuzlak wants to merge 2 commits into
mainfrom
fix/adk-unique-surface-id
Open

AlemTuzlak wants to merge 2 commits into
mainfrom
fix/adk-unique-surface-id

Conversation

@AlemTuzlak

@AlemTuzlak AlemTuzlak commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Every ADK A2UI dashboard in a thread used the same surface id, dynamic-surface. When the host sets no default_surface_id, each create without a target falls back to the toolkit default. CopilotKit 2.x shows one card per surface id, so each new dashboard replaced the previous one, and the user lost the earlier dashboard. Now a create without a target gets dynamic-surface-<tool call id> when the host sets no default_surface_id.

What changed

  1. Surface id per call. run_async picks the surface id once:
    • A call with target_surface_id uses it, as before.
    • An update without a target uses the default id, as before.
    • A create without a target gets <default>-<tool call id> when the host set no default_surface_id. Without a tool call id, it gets 8 random hex characters.
    • The tool call id makes the id the same on every replay, so a recorded fixture can name the surface. A random id cannot.
  2. A host default keeps its meaning. When the host passes default_surface_id, creates use it, as before. get_a2ui_tool records whether the host set one. The auto-injected tool sets none, so it gets the new ids.
  3. Both inference formats. The Express processor, the update lookup, the Express stream and the Direct JSON envelope default all use the same id.

Testing

Commands run

  • uv run --locked pytest in integrations/adk-middleware/python: 1536 pass, 9 skipped.

  • black --check on the changed files passes.

  • The two new tests fail without the source change and pass with it.

  • End to end: I installed this PR's TestPyPI preview of ag-ui-adk in the CopilotKit showcase google-adk app on CopilotKit 2.0.0-rc.46. The 4 dashboard pills in one thread gave 4 chat cards (dynamic-surface-call_d6_decl_dash_outer_001 and so on) and no error alert. For this run, the recorded Express fixtures named the new ids.

Manual test

  1. In the CopilotKit showcase, run google-adk:declarative-gen-ui on CopilotKit 2.x with ag-ui-adk 0.12.0. The second pill replaces the first dashboard, so the probe finds no new BarChart.
  2. Use this branch. Each pill keeps its own dashboard card.

How this PR makes testing easy: tests/test_a2ui_express_update_snapshots.py has two new tests: two creates without a host default get the ids of their tool calls, and a create with a host default keeps it.

Risk / rollback

  • Recorded fixtures. An Express recording that writes surface("dynamic-surface", update=true) must name the new id, dynamic-surface-<tool call id>.
  • New surface ids. Code that looked for the surface id dynamic-surface after a create no longer finds it. An update without a target still uses dynamic-surface, so it does not find a surface that a create made without a host default. Name the target, or set default_surface_id, for that flow.
  • Only ADK. The LangGraph, Strands and CrewAI tools take the surface id from the model's render_a2ui call, so this does not change them.
  • Rollback: revert the PR.

🤖 Generated with Claude Code

Every create without a target used the toolkit default surface id
dynamic-surface. A client that keys surfaces by id (CopilotKit 2.x) then
replaced the previous dashboard with each new one. Without a host
default_surface_id, a create now gets dynamic-surface-<8 hex>. An update
keeps the surface it targets, and a host default_surface_id keeps its
meaning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AlemTuzlak
AlemTuzlak requested a review from a team as a code owner November 13, 2026 15:23
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Python Preview Packages

Version 0.0.0.dev1794584479 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.dev1794584479' --index testpypi

# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1794584479' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1794584479' --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.dev1794584479' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1794584479' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1794584479' --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.dev1794584479

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


Commit: 10ee533

@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@3396

@ag-ui/a2ui-middleware

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

@ag-ui/event-throttle-middleware

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

@ag-ui/mcp-apps-middleware

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

@ag-ui/mcp-middleware

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

@ag-ui/a2a

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

@ag-ui/adk-js

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

@ag-ui/adk

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

@ag-ui/ag2

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

@ag-ui/agno

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

@ag-ui/antigravity

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

@ag-ui/aws-strands

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

@ag-ui/claude-agent-sdk

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

@ag-ui/claude-managed-agents

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

@ag-ui/crewai

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

@ag-ui/langchain

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

@ag-ui/langgraph

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

@ag-ui/llamaindex

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

@ag-ui/mastra

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

@ag-ui/openai-agents

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

@ag-ui/pydantic-ai

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

@ag-ui/vercel-ai-sdk

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

@ag-ui/watsonx

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

@ag-ui/a2ui-toolkit

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

create-ag-ui-app

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

@ag-ui/client

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

@ag-ui/core

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

@ag-ui/encoder

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

@ag-ui/proto

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

commit: 5e88874

A random id differed on every run, so a replayed run (a recorded
fixture) could never name the surface. The tool call id is unique for
each dashboard and the same on every replay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AlemTuzlak
AlemTuzlak enabled auto-merge (squash) November 13, 2026 16:27

@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.

Reviewed the diff and the two new tests (read the file at the PR head, 5e88874).

Verified:

  • The fix does what the title says: with no host default_surface_id, each create gets {default}-{function_call_id} (test pins dynamic-surface-first-call / dynamic-surface-second-call), so a CopilotKit client keying surfaces by id shows two dashboards instead of replacing the first. The host-default test pins ["report"], so a host default keeps its meaning, and an explicit target_surface_id still wins on both paths.
  • uuid is imported at line 23, so the fallback cannot NameError.

One gap worth a look: the comment says "The id comes from the tool call, so a replayed run (a recorded fixture) gets the same id", but that holds only when function_call_id is present. When it is None, the fallback is uuid.uuid4().hex[:8], which is random per run, so a replayed fixture without a call id gets a different surface id each time (and the test only covers the present-call-id path). Is function_call_id guaranteed non-None on this path in ADK? If not, either the comment should scope the replay guarantee to the present-call-id case, or the fallback should derive from something stable already in scope. Not blocking, just a determinism note.

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