Builder layouts
Build custom Live Activity layouts with constrained JSON nodes and bound data.
Customize a Live Activity with a small JSON layout: choose the visible fields, arrange them, and bind them to values from your task.
Start with a preset or a custom layout
For most updates, agentalerts_publish_live_activity chooses a layout from the semantic content kind. Browse Live Activity examples first.
Use the advanced agentalerts_send tool when you need direct layout control. It supports builder presets such as builder-funnel, builder-launch-console, and builder-document-preview, or a custom builderSpec with data.
A supplied presentationPreset takes precedence over conflicting presentation fields. For an intentional custom builder layout, omit the preset and set payload.template to builder.
Layout structure
A builder spec has version: 1 and a surfaces object. Supply lockScreen as the required fallback. You can also define compact, minimal, and expanded for Dynamic Island presentations.
Each surface contains a node. Supported node types are:
- Layout:
vstack,hstack,zstack,grid. - Content:
text,metric,chart,progress,documentPreview. - Supporting elements:
statusDot,imageSymbol,button,spacer,divider.
Stacks and grids contain children. Text and button nodes need text; metrics need value; charts need values; progress nodes need progress; image symbols need symbol. Document previews need text and value.
Visible values can be literals or bindings such as {"path":"checks"}, resolved from payload.data. Use fallback where appropriate for a missing binding. Keep unavailable measurements distinct from zero.
Minimal custom MCP example
This illustrative request displays a release check count. Replace the sample facts with your observed result before sending:
{
"activityId": "release-summary",
"updateMode": "upsert_single",
"surfaces": ["live_activity"],
"payload": {
"template": "builder",
"title": "Release checks",
"summary": "Five checks passed.",
"status": "good",
"sourceName": "Release workflow",
"builderSpec": {
"version": 1,
"surfaces": {
"lockScreen": {
"type": "vstack",
"spacing": "small",
"children": [
{"type": "text", "text": "Release checks", "role": "title"},
{"type": "metric", "label": "Passed", "value": {"path": "checks"}}
]
},
"compact": {"type": "text", "text": {"path": "checks"}, "role": "value"},
"minimal": {"type": "statusDot"}
}
},
"data": {"checks": "5"}
}
}
Reuse the same activityId with upsert_single to update the same subject. Omit an explicit event so the service can choose update-or-start routing. Inspect the send receipt and verify the result on your iPhone; acceptance by APNs is not proof of rendering.
Customize the presentation
- Spacing:
none,small,medium, orlarge. - Roles:
title,subtitle,caption,value,label,status,accent,muted,funnel, orhero. - Charts:
line,area, orbar; supply numericvaluesand optionalaxisLabels. - Progress:
linear,ring, orsegmented; provide a measured value in the supported 0–1 or 0–100 range. - Symbols: an SF Symbol name through
symbol, not a remote image URL. - Accent:
accentHex, such as#2E61EB, andglassOpacitybetween 0.25 and 1. - Navigation: set the report's
deepLinkto a verified destination. A builder button uses that destination; a node-levelurlis not a supported navigation field.
Document previews support up to four text children. The document-card data format can also carry up to four carousel cards, currentCardIndex, documentTitle, stateLabel, stateValue, lineOne through lineFour, itemStyle, and zero-based checkedLines. Carousel cycling and checkbox changes remain local to the Live Activity. They do not edit source documents or count as agent approval. Use Interactions when the agent needs a durable response.
Use the right format for your client
The example above is a remote MCP request envelope. The Swift CLI accepts content files containing builderSpec and data; gallery downloads are already prepared for that format. Do not assume a whole MCP request can be passed unchanged to agentalerts send --file.
Builder layouts render Live Activity surfaces. They do not replace the fixed layout of a Home Screen snapshot widget. See Widgets for snapshot delivery.
Limits and troubleshooting
Builder layouts use a constrained renderer, not arbitrary SwiftUI, HTML, CSS, or JavaScript. They cannot run scripts, fetch remote images, or perform network requests from the layout.
Current validation limits include nesting depth five, up to eight children per ordinary container, up to four document-preview lines, up to 16 builder chart values, and up to 96 characters for builder text values. Symbol names are limited to 64 characters. Top-level report fields have their own limits, including 32 characters for title and 96 for summary. Keep the entire request compact enough for push delivery; a structurally valid layout is not a guarantee of successful transport or a readable design.
- Rejected layout: check
version, the requiredlockScreen, node types, required node fields, nesting, and field budgets. Use the returned field path to find the issue. - Blank or missing value: confirm the path exists in
dataand resolves to the expected type. Use a truthful fallback for missing data. - Unexpected preset layout: remove
presentationPresetif you intend to use your own spec. - Button opens the wrong place: set
payload.deepLink; do not put a URL on the button node. - Crowded content: shorten the copy and simplify compact/minimal layouts. Do not rely on truncation to preserve meaning.
- Layout accepted but not visible: inspect delivery status and device registration, then check the phone. A schema-valid request is not an on-device rendering test.