Skip to main content

examples.tools.a2ui

A2UI generative-UI example tool.

This module exposes a single backend tool, :func:render_a2ui_surface, that turns a declarative field specification produced by the model into a fully validated A2UI v0.9 surface (createSurface + updateComponents + updateDataModel messages).

The frontend renders the returned messages inline in the chat (and in a main canvas) using the @a2ui/react renderer, giving the agent the ability to generate real, interactive user interfaces — forms, cards and lists — from a natural-language request.

The tool is referenced from a ToolSpec runtime block via package + method and registered on a pydantic_ai.Agent through register_agent_tools (which wires it with tool_plain).

A2uiOption Objects​

class A2uiOption(BaseModel)

A selectable option for a choice or multichoice field.

A2uiField Objects​

class A2uiField(BaseModel)

A single declarative field the agent wants rendered on the surface.

A2uiSummaryItem Objects​

class A2uiSummaryItem(BaseModel)

A read-only key/value chip shown in the surface header.

render_a2ui_surface​

async def render_a2ui_surface(
        title: str,
        intro: str,
        fields: list[A2uiField],
        submit_label: str = "Submit",
        summary_items: Optional[list[A2uiSummaryItem]] = None,
        surface_id: str = "a2ui-agent-surface") -> dict[str, Any]

Render an interactive A2UI surface from a declarative field spec.

Use this tool whenever the user asks for a form, intake, configurator, survey, booking, checklist or any other interactive UI. Provide a concise title, a one-sentence intro and a list of fields. The rendered surface is shown to the user directly — do not repeat the field contents in your text reply, just briefly confirm what you built.

Arguments:

  • title - Heading shown at the top of the surface.
  • intro - One-sentence description of what the surface is for.
  • fields - Ordered list of input fields to render. Supported type
  • 1 - text, longtext, email, choice, multichoice, checkbox, slider, date, datetime. choice/multichoicerequireoptions; slideracceptsmin/max. Set required=True`` on fields the user must fill in before submitting; the form blocks submission until they have a value.
  • ``4 - Label for the primary submit button.
  • ``5 - Optional read-only key/value chips shown in the header (for example detected priority or category).
  • ``6 - Stable surface identifier (defaults are fine).

Returns:

A dict with the surface id, catalog id and the ordered list of A2UI v0.9 messages the frontend renders.