Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Integrate A2UI with Your Frontend

Use this guide when building your own chat app, dashboard, or canvas — not only PraisonAIUI. PraisonAI core emits A2UI via the agent tool send_a2ui_messages. Your frontend detects the payload and renders with Google A2UI renderers or a custom mapper.
Core SDK documents the contract (A2UIToolResultProtocol). Detection helpers for rich UI live in PraisonAIUI a2ui_utils as the reference UI implementation — do not expect parsing logic in praisonaiagents core.

​
Prerequisites

pip install praisonaiagents[a2ui]
Optional React renderer: 
npm install @a2ui/react @a2ui/web_core

​
Four-step contract

​
1. Agent with the A2UI tool

from praisonaiagents import Agent
from praisonaiagents.tools.a2ui_tools import send_a2ui_messages

agent = Agent(
    name="assistant",
    instructions=(
        "When the user asks for UI, call send_a2ui_messages with valid A2UI v0.9 JSON."
    ),
    tools=[send_a2ui_messages],
)

​
2. Tool output shape (integrator contract)

send_a2ui_messages returns: 
{
    "mime_type": "application/json+a2ui",
    "messages": [  # A2UI v0.9 message list
        {"createSurface": {"surfaceId": "main", "catalogId": "basic"}, ...}
    ],
    "a2ui_part": ...  # A2A-wrapped payload
}
Type hint in core (zero runtime cost): 
from praisonaiagents.ui.a2ui import A2UI_MIME_TYPE, A2UIToolResultProtocol
from praisonaiagents.ui.protocols import A2UI_MIME_TYPE  # same constant

​
3. Detect in your UI (minimum)

def handle_tool_result(result):
    if isinstance(result, dict) and result.get("mime_type") == "application/json+a2ui":
        messages = result["messages"]
        # → pass to @a2ui/react or your renderer
        return messages
    return None
For richer normalisation (surface id, version fields), use PraisonAIUI a2ui_utils.py as a reference — copy or vendor that file in your UI layer.

​
4. Render and handle user actions

React (Google renderer): 
import { A2uiSurface, basicCatalog } from '@a2ui/react/v0_9'
// Process messages with MessageProcessor, render A2uiSurface
Wire button clicks back to your agent (POST user action → new agent turn).

​
Transport options

TransportEntry pointA2UI delivery
Tool result JSONYour WebSocket/SSEParse mime_type on TOOL_CALL_COMPLETED
AG-UIAGUI(agent).get_router() → POST /aguiTOOL_CALL_RESULT (JSON string) + CUSTOM event name: "a2ui"
A2AA2A(agent) → POST /a2acreate_a2ui_part() / is_a2ui_part()
PraisonAIUIaiui run app.pyReference impl — surfaces, canvas, chat preview

​
AG-UI CUSTOM event

When a tool returns A2UI, the AG-UI bridge emits an additive event: 
{
  "type": "CUSTOM",
  "name": "a2ui",
  "value": {
    "mime_type": "application/json+a2ui",
    "messages": [...],
    "surface_id": "main"
  }
}
The existing TOOL_CALL_RESULT with stringified JSON is unchanged for backward compatibility.

​
Tiers (pick the simplest)

See Generative UI for the full tier list:
TierUse when
0Markdown streaming only
1Your frontend owns component mapping (output_pydantic)
2CopilotKit / AG-UI client
3Cross-platform A2UI catalog (this guide)

​
Reference implementation

PraisonAIUI example 29 — A2UI canvas demonstrates chat + live surface preview.