A2A Transport

A2UI's wire is transport-agnostic, so the same validated A2UI messages can ride an A2A exchange instead of the built-in REST adapter. The autogen.beta.a2ui.a2a submodule wraps a plain autogen.beta.Agent in an A2UIAgentExecutor, plugs it into a standard A2AServer, and carries each turn's A2UI messages as a canonical A2A DataPart.

How It Maps#

The executor splits each completed turn into a text Part (the conversational prose) plus a single A2UI DataPart whose data is the JSON array of validated messages — the canonical A2A v1.0 encoding for A2UI.

Public API#

1
2
3
4
5
6
7

from autogen.beta.a2ui.a2a import (
    A2UIAgentExecutor,        # the A2A executor wrapping a plain Agent
    get_a2ui_agent_extension, # build the AgentExtension for the card
    create_a2ui_parts,        # wrap A2UI messages into A2A Parts
    get_a2ui_data,            # decode an A2UI DataPart's payload
    is_a2ui_part,             # check whether a Part carries A2UI data
)

Minimal Server#

Wrap a plain Agent in A2UIAgentExecutor (with the same flat A2UI kwargs as A2UIServer, including actions= for clickable buttons), pass it to A2AServer via executor=, and advertise A2UI support on the card with a card_modifier that appends the extension:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

import uvicorn
from a2a.types import AgentCard

from autogen.beta import Agent
from autogen.beta.a2a import A2AServer
from autogen.beta.a2ui import a2ui_action
from autogen.beta.a2ui.a2a import A2UIAgentExecutor, get_a2ui_agent_extension
from autogen.beta.config import AnthropicConfig

@a2ui_action(description="Book the selected dinner reservation")
def book_table(time: str) -> str:
    return f"booked a table for {time}"

def build_app():
    agent = Agent(name="ui_agent", config=AnthropicConfig(model="claude-sonnet-4-6"))
    # Buttons are declared on the executor via actions=, just like A2UIServer —
    # the agent stays plain.
    executor = A2UIAgentExecutor(agent, actions=[book_table], protocol_version="v0.9")

    async def advertise_a2ui(card: AgentCard) -> AgentCard:
        card.capabilities.extensions.append(get_a2ui_agent_extension(version=executor.protocol_version))
        return card

    server = A2AServer(agent, executor=executor, card_modifier=advertise_a2ui)
    return server.build_jsonrpc(url="http://127.0.0.1:8000")

app = build_app()

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

A client connects by pointing A2AConfig(card_url=...) at the card URL, exactly as for any A2A agent — see the A2A client page.

Reading A2UI From the Client#

The A2UI messages ride a DataPart on the finalization message. Use is_a2ui_part to find it and get_a2ui_data to decode the payload (a list of canonical A2UI messages):

1
2
3
4
5
6

from autogen.beta.a2ui.a2a import get_a2ui_data, is_a2ui_part

# `message` is the A2A agent message from the completed task.
for part in message.parts:
    if is_a2ui_part(part):
        messages = get_a2ui_data(part)  # list[dict] — createSurface, updateComponents, ...

get_a2ui_data decodes both the canonical v1.0 form (a JSON array in one DataPart) and the legacy form (one object per DataPart), returning None for any part that is not A2UI-typed.

The Click Round-Trip#

A button click is sent back as an inbound A2UI DataPart on the next request message — an action envelope, or a functionResponse (v1.0) for a server-initiated callFunction. A click on a registered @a2ui_action runs that handler on the server (its messages lead the DataPart, the agent is not invoked); a click on any other button — plus error and functionResponse envelopes — is rewritten into the turn's prompt so the agent continues. A turn carrying only registered server-action clicks finalizes without invoking the agent. See Actions for the envelope shapes.

Manually Building Parts#

If you serialize A2UI messages onto an A2A message yourself (outside the executor), create_a2ui_parts wraps one or many messages into DataParts:

1
2
3
4

from autogen.beta.a2ui.a2a import create_a2ui_parts

parts = create_a2ui_parts(messages)                    # one DataPart, data = [msg, ...]
parts = create_a2ui_parts(messages, legacy_split=True) # one DataPart per message (pre-v1.0 renderers)