A2UI ADK extension
a2ui-adk connects the A2UI agent SDK to the
Agent Development Kit (ADK). It
provides the a2ui.adk package.
Installation
# ADK tools only
pip install a2ui-adk
# With the ADK-to-A2A converters and A2A subagent orchestration
pip install "a2ui-adk[a2a]"
The a2a extra installs a2ui-a2a and
google-adk[a2a].
Contents
Available with the base install:
SendA2uiToClientToolsetis an ADK toolset that lets an agent send A2UI to the client through a tool call. It takes whether A2UI is enabled and the request'sA2uiRequestProcessor, or callbacks (A2uiEnabledProvider,A2uiProcessorProvider) that return them per context. The processor holds everything else: the catalogs, the example turns, the inference format, and theRendererStatebound to it for Canvas UIs. The toolset adds the processor's prompt to the model's instructions, compiles each tool call with the processor's parser, and validates the resulting A2UI JSON messages before they are sent.A2uiInstructionis an ADK instruction provider for an agent that writes A2UI in its text response. Pass it asLlmAgent.instructionwith the agent's own instruction and the same processor or callbacks as the toolset. It appends the processor's prompt to the agent's instruction. ADK reads{name}session state templates out of a string instruction, and the A2UI prompt holds braces that are not state keys (${expression}in the basic catalog, data bindings in the examples), so a string instruction fails withKeyError: "Context variable not found: 'expression'.". As a provider,A2uiInstructionis used as it is, while the agent's own instruction keeps its{name}templates.A2uiProcessorStorekeeps each session'sA2uiRequestProcessorin memory, since ADK's session services save state as JSON and can't hold one. Itsis_enabledandgetmethods are the callbacks for the toolset,A2uiInstructionandA2uiEventConverter.A2uiRendererCallsStorekeeps each session'sRendererFunctionCalls(froma2ui.rpc), which holds the agent's pendingcallRendererFunctioncalls. Itsgetmethod returns the session's instance, creating it on first use, andremovedisposes it when the session ends.
Available with the a2a extra:
A2uiPartConverterandA2uiEventConverter(also ina2ui.adk.a2a) convert ADK events and GenAI parts into A2A parts with A2UI data, using the request'sA2uiRequestProcessor.A2uiEventConvertergets the processor from itsa2ui_processorargument, such asA2uiProcessorStore.get. Pass it to ADK'sA2aAgentExecutor.a2ui_rpc_callback(also ina2ui.adk.a2a) returns abefore_agent_callbackthat answers the renderer's A2UI v1.0callAgentFunctionmessages without running the agent. When the request holds only such calls, it runs them through aRendererToAgentMessageProcessor(froma2ui.rpc) built from the agent's catalogs, and returns theagentFunctionResponsereplies as the agent's response. For any other request, including the renderer'saction,errorandrendererFunctionResponsemessages, it returns None, so the agent runs. WithA2aAgentExecutor, the replies reach the client as A2UI parts. Withrenderer_calls, its processor'son_renderer_function_responseis the session'sRendererFunctionCalls.resolve, which settles a response to a pending call and declines any other, such as one to a call the model wrote. The request is answered without the agent only when every message is handled. A request that goes to the agent still settles the pending calls its responses answer.a2ui_rpc_interceptor(also ina2ui.adk.a2a) returns anA2aAgentExecutorinterceptor that ends a taskcompletedwhen its request held onlycallAgentFunctionandrendererFunctionResponsemessages. ADK's executor would otherwise end a task with nothing to send back, such as one holding onlyrendererFunctionResponse, in theworkingstate.exclude_a2ui_rpc_from_prompt(also ina2ui.adk.a2a) is abefore_model_callbackthat removes thecallAgentFunctionandagentFunctionResponsemessages from the contents sent to the model. The session's events keep them, and other A2UI messages, such asaction,rendererFunctionResponseorcreateSurface, are kept.SendA2uiToClientToolsetdoes the same for its agent, so only agents without the toolset need the callback.A2uiSubagentMapandSurfaceIdAlreadyExistsError(also ina2ui.adk.orchestration) track which subagent owns each surface in an orchestrator that talks to its subagents over A2A.
Without the extra, import a2ui.adk still works. Reading one of these names
raises an ImportError that explains how to install the extra.
from a2ui.adk import A2uiEventConverter, A2uiInstruction, SendA2uiToClientToolset
To answer the renderer's agent function calls, pass the callback to the agent with the agent's catalogs, or with a provider that returns them per context. To keep a callback of your own, pass a list; ADK runs them in order until one returns content:
from a2ui.adk import A2uiProcessorStore, a2ui_rpc_callback
processors = A2uiProcessorStore()
def active_catalogs(ctx):
processor = processors.get(ctx)
return processor.active_catalogs if processor else None
agent = LlmAgent(
...,
before_agent_callback=[
a2ui_rpc_callback(catalogs=active_catalogs),
my_before_agent_callback,
],
)
agent_function_timeout (seconds) cancels an agent function that takes too
long, as for RendererToAgentMessageProcessor. A call that the processor
can't answer, such as one without a functionCallId or with a version other
than "1.0", is logged and dropped. A request whose calls are all dropped gets a
response with no parts, which A2aAgentExecutor ends in the working state.
To settle the agent's calls to renderer functions, also pass the session's
RendererFunctionCalls, and add the interceptor to the executor so a task that
held only responses ends completed:
from a2ui.adk import A2uiEventConverter, A2uiRendererCallsStore, a2ui_rpc_interceptor
renderer_calls = A2uiRendererCallsStore()
agent = LlmAgent(
...,
before_agent_callback=a2ui_rpc_callback(
catalogs=active_catalogs, renderer_calls=renderer_calls.get
),
)
config = A2aAgentExecutorConfig(
event_converter=A2uiEventConverter(a2ui_processor=processors.get),
execute_interceptors=[a2ui_rpc_interceptor()],
)
# In a tool
message, result = renderer_calls.get(tool_context).call(
catalog_id=CATALOG_ID, name="getLocation"
)
The pending calls live in this process's memory, so a deployment whose requests for one session may reach different replicas can't settle them this way.
ADK stores the calls and their replies in the session's events like any other
turn. SendA2uiToClientToolset removes them from the model's prompt; an agent
without the toolset passes before_model_callback=exclude_a2ui_rpc_from_prompt.
Running tests
From the repository root:
uv run pytest python/a2ui_adk/tests
The conformance cases are in
conformance/extensions/adk.
Building
From the python/a2ui_adk directory:
uv build
Metadata
Release files for a2ui-adk 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| a2ui_adk-0.3.0.tar.gz | 65.3 kB | With provenance | Details for a2ui_adk-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| a2ui_adk-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for a2ui_adk-0.3.0-py3-none-any.whl |
Total release size: 103.6 kB
Release files / a2ui_adk-0.3.0.tar.gz
| Download URL | a2ui_adk-0.3.0.tar.gz |
|---|---|
| Size | 65.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14e0d7a825aac9ec66df080765d137e6ac80f8d38e555db3e01992048411d962
|
|
BLAKE2b-256 checksum How to use checksums |
34585564ac6f3e023a0c4d2a7ebe711958f7f435eecc4435b94c69eb9842e296
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by Google Cloud, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / a2ui_adk-0.3.0-py3-none-any.whl
| Download URL | a2ui_adk-0.3.0-py3-none-any.whl |
|---|---|
| Size | 38.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cdd487568211456fb4bdb636b8dfd606d6380e2e46f4f2b8a578726c7fc29d60
|
|
BLAKE2b-256 checksum How to use checksums |
ca980f145199c181959513bf0d138720f935407c47a5e2183385294a7e745de9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by Google Cloud, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for a2ui-adk 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for a2ui_adk-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by Google Cloud, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.