Federated from workspace · PL-002 · zaixos-design-system/docs/experience/ai-agent/BLOCK_SCHEMA.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

Agent Response Block Schema

Version: 1.0
Enum: Zaixos\DesignSystem\Experience\Agent\AgentResponseBlockType

All blocks are JSON-serializable arrays with a required type field matching the enum value.

---

Common rules

• Unknown type values are silently dropped by AgentBlockNormalizer
• Empty optional strings are omitted in rendering
• URLs must be product-scoped and authorization-checked before inclusion in blocks
• Blocks render in array order

---

header

{
  "type": "header",
  "title": "Today at a glance",
  "meta": "Cliniczos · 2026-07-04"
}

Field	Type	Required
title	string	Yes
meta	string	No

---

text

{
  "type": "text",
  "content": "Operational summary ready.",
  "variant": "body"
}

Field	Type	Required	Values
content	string	Yes
variant	string	No	body, lead

---

metric_grid

{
  "type": "metric_grid",
  "items": [
    {
      "label": "New leads",
      "value": "12",
      "foot": "Today",
      "url": "/admin/leads",
      "tone": "default"
    }
  ]
}

Item field	Type	Required	Values
label	string	Yes
value	string	Yes
foot	string	No
url	string	No	Makes card clickable
tone	string	No	default, warn, success

---

section

{
  "type": "section",
  "title": "Critical items",
  "tone": "critical",
  "count": 2,
  "items": [
    { "text": "3 overdue follow-ups", "why": "Revenue at risk", "url": "/admin/leads?filter=overdue" }
  ]
}

Field	Type	Required	Values
title	string	Yes
tone	string	No	default, critical, warning
count	int	No	Badge count
items	array	Yes	See list item

List item: text, why (optional), url (optional)

---

recommended

{
  "type": "recommended",
  "title": "Recommended actions",
  "items": ["Review ad spend", "Call hot leads"]
}

Field	Type	Required
title	string	No
items	string[]	Yes

---

actions

{
  "type": "actions",
  "items": [
    {
      "label": "Open leads",
      "url": "/admin/leads",
      "icon": "heroicon-o-arrow-top-right-on-square",
      "tone": "success"
    }
  ]
}

Item field	Type	Required	Values
label	string	Yes
url	string	No
icon	string	No	Heroicon name
tone	string	No	success, error, default

---

alert

{
  "type": "alert",
  "tone": "warning",
  "title": "Access limited",
  "body": "You can view summaries but not financial drill-down."
}

Field	Type	Required	Values
tone	string	No	info, warning, error, success
title	string	Yes
body	string	No

---

media

{
  "type": "media",
  "kind": "image",
  "src": "https://cdn.example.com/chart.png",
  "alt": "Weekly trend",
  "caption": "Lead volume — last 7 days"
}

Field	Type	Required	Values
kind	string	No	image, video, embed
src	string	Yes
alt	string	No
caption	string	No
poster	string	No	Video poster URL

---

divider

{ "type": "divider" }

No additional fields.