# Widgets

Place Home Screen and Lock Screen snapshot widgets, publish updates, and understand refresh behavior.

Keep a recent report on your Home Screen or Lock Screen, and use Live Activities for richer dashboard layouts.

## Choose the right kind of widget

Snapshot widgets show the latest received widget report. Add them through the iPhone's widget gallery. Home Screen sizes are small and medium; Lock Screen options are inline, circular, and rectangular.

A Live Activity appears on the Lock Screen and, on supported iPhones, Dynamic Island. Its lifecycle and layout are separate from a placed snapshot widget. Use [Builder layouts](/agent-alerts/docs/builder-layouts) to customize a Live Activity through JSON.

## Add a snapshot widget

1. Install Agent Alerts, finish onboarding, and sign in to the account connected to your publishing client. Open the app and let device registration finish.
2. To add a Home Screen widget, touch and hold the Home Screen, open its widget picker, search for Agent Alerts, and choose small or medium.
3. For a Lock Screen widget, customize the Lock Screen and choose Agent Alerts from the widget picker. Choose a size that fits the available space.
4. Send a widget update from a connected client, then check the placed widget on the iPhone.

The current snapshot widget shows the latest received report. It does not offer a per-instance report picker. Sending different widget IDs does not make each placed copy display an independently selected report.

## Publish a widget snapshot

Use the advanced remote MCP tool, `agentalerts_send`, for widget delivery. Add `widget` to `surfaces` and include a matching `widget` object with `widgetId` and `snapshot`. The snapshot uses the report content fields, such as `title`, `summary`, `status`, and metric fields.

This illustrative widget-only request does not start a Live Activity or request a visible notification:

```json
{
  "activityId": "release-summary",
  "surfaces": ["widget"],
  "payload": {
    "title": "Release checks",
    "summary": "Five checks passed.",
    "status": "good"
  },
  "widget": {
    "widgetId": "release-summary",
    "snapshot": {
      "title": "Release checks",
      "summary": "Five checks passed.",
      "status": "good",
      "sourceName": "Release workflow",
      "primaryLabel": "Checks passed",
      "primaryValue": "5"
    }
  }
}
```

Replace sample values with observed results. Use small, non-secret content because widgets can be visible while the phone is locked. The publishing connection needs the appropriate sending access; `agentalerts_status` reports linked-account readiness and limits.

The normal `agentalerts_publish_live_activity` tool is for Live Activities. Use the advanced send tool when you explicitly need a widget surface. A widget refresh does not create a recurring data collection schedule.

## Refresh and troubleshooting

The app stores an incoming snapshot and asks WidgetKit to reload. iOS controls refresh timing and can combine or delay reload requests. A successful service send is not proof that a placed widget has repainted.

- **No widget appears:** add it through the iPhone's widget picker.
- **Old or sample content:** open Agent Alerts, check the connected account and device registration, and send a fresh widget snapshot. The widget shows preview content until a snapshot is available.
- **Wrong report:** the placed widget uses the latest received snapshot, including reports sent with another widget ID.
- **Missing update:** check `status`, `failureCode`, `nextAction`, and target counts in the send response. Confirm that `surfaces` includes `widget` and its object contains both `widgetId` and `snapshot`.
- **Different layout than expected:** snapshot widgets have fixed size-specific layouts. A custom `builderSpec` controls Live Activity layouts, not the placed Home Screen widget's view hierarchy.

See [Troubleshooting](/agent-alerts/docs/troubleshooting) for connection and delivery checks.


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