app-intents

name

app-intents

description

App Intents on iOS/iPadOS/macOS 26 (Swift 6.2) — expose app actions and content to Siri, Apple Intelligence, Shortcuts, Spotlight, Visual Intelligence, the Action Button, Control Center, and interactive widgets. Use when implementing or debugging AppIntent, AppEntity, AppEnum, EntityQuery, AppShortcutsProvider, SnippetIntent, IndexedEntity, assistant schemas (@AppIntent(schema:)), Spotlight indexing, or migrating from SiriKit/INIntent — or any "App Intents / App Shortcut / Siri phrase / Visual Intelligence" task.

App Intents — Siri, Shortcuts, Spotlight & Apple Intelligence

The App Intents framework exposes your app's actions and content to the system: Siri, Apple Intelligence, the Shortcuts app, Spotlight, Visual Intelligence, the Action Button (iPhone 15 Pro+/16+), the Apple Pencil Pro squeeze, Control Center / Lock Screen, and interactive widgets / Live Activities — all from plain Swift structs, no .intentdefinition files, no code generation.

• Platforms: iOS 26+, iPadOS 26+, macOS 26+, visionOS 26+, watchOS, tvOS (surface availability varies; Siri/Spotlight/Action-Button are iPhone/iPad/Mac).
• Import: import AppIntents.
• Three core types: AppIntent (an action), AppEntity (a dynamic value), AppEnum (a fixed set). Discoverability comes from AppShortcutsProvider and/or the @AppIntent(schema:) assistant-schema macro.

The one mental model that explains everything: build-time metadata

App Intents uses build-time metadata extraction. At compile time your Swift source is read into an .appintentsmetadata bundle inside your app. The system reads that bundle without running your app — which is why your intents, entities, and shortcuts are available the instant the app is installed, and why half the framework's constraints exist:

• Titles / type-display-representations / case-display-representations MUST be compile-time constants (static let, string literals). A computed property or function call fails to build with "Expression is not a string literal".
• Renaming an AppIntent/AppEntity struct is a BREAKING CHANGE. The struct name is the stable identity — renaming invalidates every Shortcut a user already built, and every donated Spotlight entry. Treat the name like a public API.
• Each target is processed independently. Share intent types across app + extension + Swift Package via AppIntentsPackage (see references/architecture-and-targets.md).

Carry this model first; it pre-empts most build errors.

When to use this skill

• Creating or modifying any AppIntent, AppEntity, AppEnum, or EntityQuery.
• Adding Siri, Shortcuts, Spotlight, or Apple Intelligence support.
• Building AppShortcutsProvider / App Shortcuts and Siri phrases.
• Implementing interactive snippets (SnippetIntent), Control Center controls, Action-Button capture, or Visual Intelligence image search.
• Deciding whether an intent should foreground the app (IntentModes).
• Migrating from SiriKit (INIntent / .intentdefinition).
• Debugging build errors, "intent not in Shortcuts", "entity not found", snippet crashes, dependency-nil crashes.

A minimum-viable intent (the shape of everything)

import AppIntents

struct AddToFavoritesIntent: AppIntent {
    static let title: LocalizedStringResource = "Add to Favorites"   // MUST be constant

    @Parameter(title: "Landmark", requestValueDialog: "Which landmark?")
    var landmark: LandmarkEntity

    @Dependency var store: FavoritesStore                            // injected, see below

    static var parameterSummary: some ParameterSummary {
        Summary("Add \(\.$landmark) to favorites")
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        try await store.addFavorite(landmark.id)                     // thin bridge — logic lives in the store
        return .result(dialog: "Added \(landmark.name) to favorites.")
    }
}

Register dependencies as early as possible — in App.init(), never onAppear:

@main struct MyApp: App {
    init() { AppDependencyManager.shared.add { FavoritesStore() } }
}

If you register too late, any intent that runs before that point crashes with a nil dependency. This is one of the most common production crashes — see references/troubleshooting.md.

Five rules that prevent the most common bugs

1. perform() is the ONLY place for side effects. Never mutate state in init; entities are constructed constantly (in queries + parameter resolution).
2. Entity IDs must be persistent and stable. var id: UUID { UUID() } is a bug — it mints a new id every read, so the system can never re-resolve a stored reference ("Entity not found"). Use a durable id (landmark.databaseID).
3. Let cancellation throw. When the user cancels requestConfirmation / requestChoice, the call throws — let it propagate. Catching it and returning .result(dialog: "Cancelled") is a documented bug that swallows the system's cancel semantics.
4. Every App Shortcut phrase must include \(.applicationName), with at most one @Parameter per phrase. (Full phrase rules: references/shortcuts-and-siri.md.)
5. Don't mutate state in a SnippetIntent.perform() — it runs multiple times per lifecycle. Snippet performs must be read-only. (Full update-cycle: references/interactive-snippets.md.)

Decision compass

Which protocol should my intent conform to?

Need	Protocol
A basic action	AppIntent
Open the app to show content	OpenIntent (+ TargetContentProvidingIntent for declarative nav)
Render an interactive view inline	SnippetIntent
Support the system undo gesture	UndoableIntent (iOS 26)
Control Center / Lock-Screen control	ControlConfigurationIntent (needs a Widget Extension)
Action-Button locked-camera capture	CameraCaptureIntent (needs a Locked Camera Capture Extension)
Audio capture	AudioRecordingIntent
Match an Apple-Intelligence domain	@AppIntent(schema:) macro (NOT protocol inheritance)

Which entity type? Fixed compile-time set → AppEnum. Dynamic set → AppEntity. Spotlight-searchable → AppEntity + IndexedEntity. A single global instance → UniqueAppEntity. A file → FileEntity. Image-searchable → AppEntity + Transferable + OpenIntent.

Which query type? All values fit in memory → EnumerableEntityQuery. Text search → EntityStringQuery. Property filtering (auto-enables Shortcuts' Find/Filter) → EntityPropertyQuery. ID-lookup only → EntityQuery (base). Visual-Intelligence image search → IntentValueQuery.

@Property vs @ComputedProperty vs @DeferredProperty?

Property type	When	Overhead
@Property	Value stored on the entity struct	Low
@ComputedProperty (iOS 26)	Derived from a source of truth (model, UserDefaults) — prefer this, no duplication	Low
@DeferredProperty (iOS 26)	Expensive (network / heavy I/O) — async getter, called only when the system asks	Lowest (lazy)

Load-bearing performance rule: entities must be cheap to create. Never do network work in init — push it into a @DeferredProperty. (Details: references/entities-and-queries.md.)

Does this intent need to open the app? → pick an IntentModes value (supportedModes). OpenIntent foregrounds automatically — do not set supportedModes on it. (Full mode table + continueInForeground: references/intent-fundamentals.md.)

iOS 26 currency flags (use these, not the deprecated forms)

• static let supportedModes: IntentModes replaces the old static var openAppWhenRun: Bool for foreground control. .background / .foreground / [.background, .dynamic] / [.background, .deferred].
• @AppIntent / @AppEntity / @AppEnum macros replace the deprecated @AssistantIntent / @AssistantEntity / @AssistantEnum.
• App Intents can live in Swift Packages and static libraries (no longer main-app-only).
• @ComputedProperty / @DeferredProperty are new iOS-26 entity property kinds.
• SnippetIntent (interactive), UndoableIntent, requestChoice, structured IntentDialog(full:supporting:), TargetContentProvidingIntent + .onAppIntentExecution, macOS-Spotlight inline execution — all iOS 26.

References

• references/intent-fundamentals.md — AppIntent, @Parameter, parameterSummary, return-type composition, dialog, IntentModes/supportedModes + continueInForeground, @Dependency, OpenIntent, UndoableIntent, requestChoice, requestConfirmation (+ conditions), requestValue, authenticationPolicy, custom errors, AppIntentError.
• references/entities-and-queries.md — AppEntity, AppEnum, the property-kind decision, the full EntityQuery family (Enumerable/String/Property), suggestedEntities(), Transferable, @UnionValue, FileEntity, UniqueAppEntity, URLRepresentableIntent/Entity.
• references/shortcuts-and-siri.md — AppShortcutsProvider, phrase rules, parameterized vs generic shortcuts, NegativeAppShortcutPhrases, updateAppShortcutParameters(), SiriTipView, ShortcutsLink, ShortcutTileColor, dialog/confirmation, surfaces (Action Button / Pencil Pro).
• references/spotlight-indexing.md — IndexedEntity, indexing-key tables, the two donation APIs, the donation lifecycle, OpenIntent-tap handling, auto-generated Find/Filter, macOS-Spotlight inline execution.
• references/interactive-snippets.md — SnippetIntent, the 6-step update cycle, Button(intent:)/Toggle(isOn:intent:), confirmation snippets, snippet chaining, reload(), the "model entities not values" + "read-only perform" rules.
• references/apple-intelligence-and-visual.md — the @AppIntent(schema:) macro, the full app-intent-domain catalog (Mail/Photos/Browser/… with action/entity/enum lists), Visual Intelligence image search (IntentValueQuery / SemanticContentDescriptor), on-screen entities for Siri/ChatGPT, PredictableIntent, AttributedString rich-text gotcha.
• references/system-integrations.md — ControlConfigurationIntent, CameraCaptureIntent, AudioRecordingIntent and their extension-target requirements.
• references/architecture-and-targets.md — intent-driven architecture (thin-bridge intents), TargetContentProvidingIntent + onAppIntentExecution declarative navigation, scene handling, AppDependencyManager, AppIntentsPackage cross-target sharing.
• references/migration-from-sirikit.md — INIntent / .intentdefinition / INObject / INShortcut → App Intents mapping, before/after Swift, coexistence.
• references/testing.md — unit-testing intents/queries as plain structs, mocking via AppDependencyManager, what can only be tested on device.
• references/troubleshooting.md — error→cause→fix for every build/runtime issue, the find …/*.appintentsmetadata + subsystem:com.apple.appintents Console workflow, and the diagnostics table.

WWDC: 2025-244 (Explore the App Intents framework), plus the assistant-schema and Visual-Intelligence sessions. Apple docs: /AppIntents, /AppIntents/app-intent-domains.