How do you design App Intents for safe, cross-device, reversible actions?

1. Scenario, goals, and boundaries

A collaboration app contains projects, comments, and tasks. A user may invoke “complete task,” “share project,” or “delete comment” through Siri, Spotlight, Shortcuts, or Apple Intelligence. Each entry point must preserve the same authorization and outcome, and a task should be resumable on another device.

Set the boundary first: App Intents are discoverable interfaces for actions and entities. They must not bypass existing server authorization, audit, or transactions. System suggestions increase reach but do not make an invocation trustworthy; treat every intent as a public call surface.

2. The product value of App Intents

Apple’s AppIntent protocol makes app actions discoverable to Siri, Spotlight, Shortcuts, and Apple Intelligence. The June 2026 App Intents updates also describe app schemas, stable cross-device entity identity through SyncableEntity, ownership confirmation for sensitive or destructive actions through OwnershipProvidingEntity, and IntentFile for receiving content supplied by other apps as parameters.

These capabilities solve discovery and semantic interoperability. They do not decide business authorization, conflict handling, or undo policy. Separate “what the user wants,” “whether the system may safely perform it,” and “how the user recovers from failure.”

3. Model actions and entities

For each intent, define inputs, visibility, preconditions, result, and side effects. A display name may change, but the business ID must be stable, verifiable, and bound to the current user and tenant. Do not use list position, title, or a local database key as a cross-device identity.

struct CompleteTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Complete task"
    @Parameter(title: "Task")
    var task: TaskEntity

    func perform() async throws -> some IntentResult {
        try await TaskService.complete(taskID: task.id)
        return .result()
    }
}

If entity resolution fails, permissions changed, or versions are incompatible, return an understandable choice or sign-in path. Never guess a similar project and execute it.

4. Design stable cross-device identity

If a task can continue on multiple devices, its entity must expose stable identity semantics, and the server must guarantee that the same entity ID refers to the same resource on each device. The sync layer still handles deletion, archiving, tenant moves, and stale offline caches; resolution rechecks that the current user can access the resource.

Do not treat SyncableEntity as a synchronization database. It expresses that identity can remain stable across devices; data synchronization, conflict resolution, and undo remain backend responsibilities. Keep alias mappings and audit records through merges or migrations so an old Shortcut cannot target the wrong entity.

5. Confirm sensitive actions and ownership

Deleting, publicly sharing, or transferring access should confirm that the user owns the entity or has the required operation permission. Use OwnershipProvidingEntity to express ownership and make the confirmation explain the object, impact, and reversibility. Bind confirmation to the current request, user, and resource version rather than reusing an old confirmation.

For team-owned or public entities, the server must return the ownership decision; local cache is not sufficient. Keep “do not ask again” preferences narrow, and retain confirmation and audit for high-risk actions.

6. Authorization, idempotency, and side effects

The system may retry an intent, and a Shortcut may be run twice. Every state-changing intent should carry an idempotency key and resource version. After authorization, the server performs a conditional update and returns the same business result for a duplicate request. Read-only actions can be faster, but still enforce visibility.

Do not encode permission in natural-language parameters. Reauthorize from the session, tenant, entity ownership, and current version, and record the entry point (Siri, Spotlight, Shortcuts, or the app), caller device, and result. Distinguish expired login, forbidden access, changed entity, and temporary service failure in the response.

7. Discovery, observability, and recovery

Choose app schemas and discoverable actions by user value rather than exposing every internal API. For each intent, measure resolution success, authorization denial, confirmation abandonment, duplicate execution, cross-device recovery, and completion rate. Compare entry points by conversion, not just invocation count.

Show a summary before execution and an outcome with an undo path afterward. On a network interruption, persist a retryable request state but never replay a destructive action indefinitely in the background. If the entity is deleted or its version conflicts, return alternatives and a human-handling path while retaining an audit event.

8. Rubric and follow-ups

Must explain

• Treat App Intents as public product interfaces that still require server authorization, audit, idempotency, and version checks.
• Distinguish stable entity identity from actual data synchronization, including deletion, migration, offline state, and conflicts.
• Design ownership confirmation, narrowly scoped skip-confirmation preferences, undo, and failure recovery for sensitive actions.

Follow-up questions

• A user confirms deletion on a phone, then an offline Shortcut on a tablet runs it again. How does the server guarantee one consistent result?
• A shared team project has no single owner. Who can confirm a permission transfer?
• How do you decide that an intent deserves system suggestions instead of adding noisy, low-value actions?

Scoring guide

An excellent answer connects discovery, identity, authorization, confirmation, idempotency, and recovery into one product chain: system entry points express intent, the server makes the final decision, and the user can understand impact and continue after failure.