# 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](/agent-alerts/docs/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:

```json
{
  "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`, or `large`.
- **Roles:** `title`, `subtitle`, `caption`, `value`, `label`, `status`, `accent`, `muted`, `funnel`, or `hero`.
- **Charts:** `line`, `area`, or `bar`; supply numeric `values` and optional `axisLabels`.
- **Progress:** `linear`, `ring`, or `segmented`; 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`, and `glassOpacity` between 0.25 and 1.
- **Navigation:** set the report's `deepLink` to a verified destination. A builder button uses that destination; a node-level `url` is 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](/agent-alerts/docs/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](/agent-alerts/docs/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](/agent-alerts/docs/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 required `lockScreen`, 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 `data` and resolves to the expected type. Use a truthful fallback for missing data.
- **Unexpected preset layout:** remove `presentationPreset` if 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.


Source: https://www.andreas.ink/agent-alerts/docs/builder-layouts
