Skip to main content

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:

  • SendA2uiToClientToolset is 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's A2uiRequestProcessor, or callbacks (A2uiEnabledProvider, A2uiProcessorProvider) that return them per context. The processor holds everything else: the catalogs, the example turns, the inference format, and the RendererState bound 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.
  • A2uiInstruction is an ADK instruction provider for an agent that writes A2UI in its text response. Pass it as LlmAgent.instruction with 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 with KeyError: "Context variable not found: 'expression'.". As a provider, A2uiInstruction is used as it is, while the agent's own instruction keeps its {name} templates.
  • A2uiProcessorStore keeps each session's A2uiRequestProcessor in memory, since ADK's session services save state as JSON and can't hold one. Its is_enabled and get methods are the callbacks for the toolset, A2uiInstruction and A2uiEventConverter.
  • A2uiRendererCallsStore keeps each session's RendererFunctionCalls (from a2ui.rpc), which holds the agent's pending callRendererFunction calls. Its get method returns the session's instance, creating it on first use, and remove disposes it when the session ends.

Available with the a2a extra:

  • A2uiPartConverter and A2uiEventConverter (also in a2ui.adk.a2a) convert ADK events and GenAI parts into A2A parts with A2UI data, using the request's A2uiRequestProcessor. A2uiEventConverter gets the processor from its a2ui_processor argument, such as A2uiProcessorStore.get. Pass it to ADK's A2aAgentExecutor.
  • a2ui_rpc_callback (also in a2ui.adk.a2a) returns a before_agent_callback that answers the renderer's A2UI v1.0 callAgentFunction messages without running the agent. When the request holds only such calls, it runs them through a RendererToAgentMessageProcessor (from a2ui.rpc) built from the agent's catalogs, and returns the agentFunctionResponse replies as the agent's response. For any other request, including the renderer's action, error and rendererFunctionResponse messages, it returns None, so the agent runs. With A2aAgentExecutor, the replies reach the client as A2UI parts. With renderer_calls, its processor's on_renderer_function_response is the session's RendererFunctionCalls.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 in a2ui.adk.a2a) returns an A2aAgentExecutor interceptor that ends a task completed when its request held only callAgentFunction and rendererFunctionResponse messages. ADK's executor would otherwise end a task with nothing to send back, such as one holding only rendererFunctionResponse, in the working state.
  • exclude_a2ui_rpc_from_prompt (also in a2ui.adk.a2a) is a before_model_callback that removes the callAgentFunction and agentFunctionResponse messages from the contents sent to the model. The session's events keep them, and other A2UI messages, such as action, rendererFunctionResponse or createSurface, are kept. SendA2uiToClientToolset does the same for its agent, so only agents without the toolset need the callback.
  • A2uiSubagentMap and SurfaceIdAlreadyExistsError (also in a2ui.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)

Source distribution for a2ui-adk 0.3.0
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)

Table of built distributions (wheels) for a2ui-adk 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page