> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# A2UI

A2UI lets an agent return **rich, interactive UI** — cards, forms, row/column layouts — rendered natively by the frontend, instead of plain text only. It suits naturally visual answers: status cards, summaries, option lists, and small forms.

<Note>
  A2UI needs the optional component package: `pip install "veadk-python[a2ui]"`.
</Note>

## Project setup

Complete [model configuration](/productions/veadk/preview/en/components/agent/model) and use a tool-capable model with the ADK runtime. Create the files below; use the next example for `agent.py` and put `from . import agent` in `__init__.py`

```text theme={null}
agents/
└── ui_agent/
    ├── __init__.py
    └── agent.py
```

## Enable

Set `enable_a2ui=True` when creating the agent, and it can reply with UI when appropriate. It uses a built-in basic component set by default (card, text, button, divider, and other common components):

```python title="agent.py" lines theme={null}
from veadk import Agent

root_agent = Agent(
    name="ui_agent",
    instruction="When the answer is naturally visual (a status card, summary, options, a small form), reply with rich UI; otherwise reply in plain text.",
    enable_a2ui=True,
)
```

The model decides whether to return UI based on the `instruction` — stating *when* to use UI works best.

## See it rendered

Run from the parent directory of `agents`:

```bash theme={null}
veadk frontend --dev --agents-dir ./agents --open
```

Select `ui_agent` and ask for three tasks displayed as cards. A successful response includes a structured card. If only text appears, check whether the model called the A2UI tool and whether the frontend recognized its components. Models do not guarantee UI output on every turn

A2UI is rendered by the frontend. Launch [VeADK Frontend](/productions/veadk/preview/en/components/frontend/veadk-frontend) and chat with the agent to see the returned cards and other components.

## Custom components

Beyond the built-in set, you can add your own components (a revenue chart, an order card, …). A custom component has two parts:

* **Backend**: declare a component catalog that tells the model which components are available;
* **Frontend**: provide a renderer for each component.

Pass your catalog to the agent's `a2ui_catalog` to enable it. For the frontend renderer, see [VeADK Frontend · Add enterprise components](/productions/veadk/preview/en/components/frontend/veadk-frontend#adding-a-custom-enterprise-component).

<Note>
  Components without a renderer fall back to a collapsible JSON view, so a mismatch never breaks the UI.
</Note>

### Catalog example

Save this script as `create_catalog.py` and run it in `agents/ui_agent`. It adds `RevenueChart` to the basic catalog and writes `catalog.json`, which the agent discovers at startup

```python title="create_catalog.py" lines theme={null}
import copy
import json
from pathlib import Path
from veadk.a2ui.catalog import get_basic_catalog

catalog, _ = get_basic_catalog()
schema = copy.deepcopy(catalog.catalog_schema)
schema["$id"] = "https://example.com/catalogs/finance.json"
schema["catalogId"] = "https://example.com/catalogs/finance.json"
schema["components"]["RevenueChart"] = {
    "type": "object",
    "properties": {
        "id": {"type": "string"},
        "component": {"const": "RevenueChart"},
        "series": {"type": "array", "items": {"type": "number"}},
    },
    "required": ["id", "component", "series"],
    "additionalProperties": False,
}
Path("catalog.json").write_text(json.dumps(schema, indent=2), encoding="utf-8")
```

Replace the sample catalog ID with your own identifier. Register a matching `RevenueChart` renderer in Frontend and rebuild it. A catalog does not install frontend components; the JSON fallback for unknown components is diagnostic output, not successful component rendering

| Parameter | Type | Default | Description |
| - | - | - | - |
| `enable_a2ui` | `bool` | `False` | Attach the A2UI toolset |
| `a2ui_catalog` | Path, `BaseA2UICatalog`, `A2uiCatalog`, or `(A2uiCatalog, examples)` | `None` | Discovers `catalog.json` in the agent directory, otherwise uses the basic catalog; relative paths resolve from the agent directory |