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 to customize a Live Activity through JSON.
Add a snapshot widget
- Install Agent Alerts, finish onboarding, and sign in to the account connected to your publishing client. Open the app and let device registration finish.
- 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.
- 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.
- 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:
{
"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 thatsurfacesincludeswidgetand its object contains bothwidgetIdandsnapshot. - Different layout than expected: snapshot widgets have fixed size-specific layouts. A custom
builderSpeccontrols Live Activity layouts, not the placed Home Screen widget's view hierarchy.
See Troubleshooting for connection and delivery checks.