> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Generative UI
> Agent-driven UI via structured output, AG-UI streaming, and optional A2UI declarative rendering
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(name="ui-assistant", instructions="Reply with concise text suitable for UI cards.")
agent.start("Show me a summary card for my project")
```
Agents can drive rich user interfaces — from plain text streaming to typed JSON schemas to live React components — by picking the right output tier for your client.
The user chats with the agent; generative UI renders cards, forms, or charts alongside the text reply.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
A[Agent] --> T{Which client?}
T -->|CLI / logs| T0[Tier 0: Markdown stream]
T -->|API / custom frontend| T1[Tier 1: Structured output]
T -->|CopilotKit / React| T2[Tier 2: AG-UI stream]
T -->|Flutter / cross-platform| T3[Tier 3: A2UI declarative]
T0 --> R0[Text chunks]
T1 --> R1[Pydantic / JSON]
T2 --> R2[SSE event stream]
T3 --> R3[JSON UI components]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef tier fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class T decision
class T0,T1,T2,T3 tier
class R0,R1,R2,R3 result
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant GenerativeUi
User->>Agent: Request
Agent->>GenerativeUi: Process
GenerativeUi-->>Agent: Result
Agent-->>User: Response
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from pydantic import BaseModel
from praisonaiagents import Agent
class Dashboard(BaseModel):
title: str
summary: str
metrics: list[dict]
agent = Agent(
name="Analyst",
instructions="Summarise sales data into a dashboard.",
output_pydantic=Dashboard
)
data = agent.start("Summarise Q1 sales from the attached report.")
print(data.title)
print(data.metrics)
```
Your frontend receives a typed object — map `Dashboard` fields to whatever React, Vue, or mobile components you already have.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, AGUI
from fastapi import FastAPI
agent = Agent(
name="Assistant",
instructions="Help users with research.",
)
agui = AGUI(agent=agent)
app = FastAPI()
app.include_router(agui.get_router())
```
Run: `uvicorn main:app --port 8002`
The agent streams text deltas and tool call events over Server-Sent Events to any AG-UI compatible frontend (CopilotKit, custom SSE client).
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Feature as Generative UI
User->>Agent: Request
Agent->>Feature: Process request
Feature-->>Agent: Result
Agent-->>User: Response
```
### Tier decision flow
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q1{Do you need live streaming?} -->|No| Q2{Do you have a custom frontend?}
Q1 -->|Yes| Q3{Cross-platform native UI?}
Q2 -->|No| T0[Tier 0: stdout / markdown stream]
Q2 -->|Yes| T1[Tier 1: output_pydantic or output_json]
Q3 -->|Yes| T3[Tier 3: A2UI — pip install praisonaiagents a2ui]
Q3 -->|No - React / web| T2[Tier 2: AGUI + FastAPI]
classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef tier fill:#189AB4,stroke:#7C90A0,color:#fff
class Q1,Q2,Q3 question
class T0,T1,T2,T3 tier
```
### Tier 0 — Markdown streaming
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[Agent] --> S[stream=True] --> C[CLI / chat widget]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class S step
class C result
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(name="Bot", instructions="Answer questions.")
for chunk in agent.start("Tell me about AI.", stream=True):
print(chunk, end="", flush=True)
```
### Tier 1 — Structured output
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[Agent] --> P[output_pydantic] --> J[JSON object] --> F[Frontend components]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef step fill:#6366F1,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class P step
class J,F result
```
Use `output_pydantic=YourModel` or `output_json=True` on the agent. The model formats its response to fit the schema, and you receive a validated Python object.
### Tier 2 — AG-UI stream
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[Agent] --> G[AGUI] --> SSE[SSE event stream] --> CK[CopilotKit / React]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class G step
class SSE step
class CK result
```
`AGUI` wraps any agent and exposes a `POST /agui` endpoint that emits text delta and tool call events per the AG-UI protocol.
### Tier 3 — A2UI declarative
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[Agent] --> AU[a2ui SDK] --> JSON[Declarative UI JSON] --> R[Flutter / React renderers]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class AU step
class JSON step
class R result
```
Requires `pip install praisonaiagents[a2ui]`. The agent emits A2UI JSON; platform-specific renderers (React, Flutter, Lit) turn it into native UI components.
***
## Configuration Options
**Tier 1 — Structured output parameters on `Agent`:**
| Parameter | Type | Description |
| ----------------- | ----------------- | ------------------------------------------------------------------------ |
| `output_pydantic` | `type[BaseModel]` | Pydantic model class — response is validated and returned as an instance |
| `output_json` | `bool` | Return raw JSON dict instead of a model instance |
**Tier 2 — `AGUI` constructor:**
| Parameter | Type | Default | Description |
| ------------- | ----------- | ---------- | ------------------------------ |
| `agent` | `Agent` | — | Single agent to expose |
| `agents` | `Agents` | — | Multi-agent workflow to expose |
| `name` | `str` | agent name | Name for the endpoint |
| `description` | `str` | agent role | Description for OpenAPI docs |
| `prefix` | `str` | `""` | URL prefix for the router |
| `tags` | `list[str]` | `["AGUI"]` | OpenAPI tags |
TypeScript AG-UI configuration
A2UI declarative UI protocol details
***
## Common Patterns
**Return a typed dashboard from a research agent:**
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from pydantic import BaseModel
from praisonaiagents import Agent
class ResearchReport(BaseModel):
title: str
summary: str
key_points: list[str]
sources: list[str]
agent = Agent(
name="Researcher",
instructions="Research topics and return structured reports.",
output_pydantic=ResearchReport
)
report = agent.start("Research the impact of AI on healthcare.")
for point in report.key_points:
print(f"• {point}")
```
**Expose a multi-agent workflow via AG-UI:**
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Agents, AGUI
from fastapi import FastAPI
researcher = Agent(name="Researcher", instructions="Research topics.")
writer = Agent(name="Writer", instructions="Write articles.")
workflow = Agents(agents=[researcher, writer])
agui = AGUI(agents=workflow)
app = FastAPI()
app.include_router(agui.get_router())
```
**Stream output to the terminal:**
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(name="Assistant", instructions="Be helpful.")
for chunk in agent.start("Write a poem about space.", stream=True):
print(chunk, end="", flush=True)
```
***
## Best Practices
Tier 1 covers 90% of use cases — a typed Pydantic response is easy to test, validate, and map to UI components. Only reach for Tier 2 or 3 when you genuinely need live streaming or cross-platform native rendering.
Broad schemas like `dict` defeat the purpose of structured output. Model exactly the fields your frontend needs — this makes validation strict and LLM prompting more reliable.
Use `praisonaiagents[a2ui]` for Tier 3 — do not create your own A2UI JSON structures. The official SDK ensures schema compliance across renderer versions.
For Tier 3, the React, Flutter, and Lit renderers are maintained in the Google A2UI repository. PraisonAI provides the agent side; you choose and update renderers independently.
***
## Related
Declarative cross-platform UI via A2UI JSON
Token-level streaming for real-time output