App Intents
Expose app actions and entities to Siri, Shortcuts, Spotlight search, interactive widgets, Control Center, and Apple Intelligence using the AppIntents framework. Targets Swift 6.4 / iOS 26+.
Contents
Triage Workflow
- Select core actions: Expose 1–3 high-value user tasks that make sense outside the app.
- Define AppEntity models: Create identifiable shadow models (
AppEntity) for domain data referenced by the intent.
- Implement AppIntent: Define parameters with
@Parameter, implement perform() async throws -> some IntentResult.
- Register voice phrases: Provide natural voice invocations with
AppShortcutsProvider.
- Verify system surface: Test discovery in Shortcuts, Spotlight search, and widget configuration.
System Surface Integration Matrix
| System Surface |
Protocol / Attribute |
Purpose |
| Siri & Shortcuts |
AppIntent |
Direct voice and shortcut automation |
| Configurable Widgets |
WidgetConfigurationIntent |
Supplies parameters to widget timelines |
| Control Center |
ControlConfigurationIntent |
Powers Control Center buttons and toggles |
| Spotlight Search |
IndexedEntity |
Indexes domain items into on-device Spotlight |
| Apple Intelligence |
@AppIntent(schema:) |
Assistant semantic reasoning and tooling |
| Interactive Snippets |
SnippetIntent |
In-line system confirmation views (iOS 26+) |
AppEntity and EntityQuery
Expose domain data to intents using AppEntity:
struct OrderEntity: AppEntity {
static var defaultQuery = OrderQuery()
static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Order")
var id: UUID
var displayRepresentation: DisplayRepresentation {
DisplayRepresentation(title: "\(orderNumber)")
}
}
Implement EntityQuery to resolve identifiers (entities(for:)) and provide suggested choices (suggestedEntities()).
AppShortcuts and Voice Phrases
Expose voice triggers without requiring user setup via AppShortcutsProvider:
- Register app shortcut phrases using
\(.applicationName) token.
- Provide clean fallback phrases for Siri matching.
Route by Task
For @Parameter types, AppEntity declarations, and EntityQuery variants, read Parameters and Entity Queries.
For widget controls, interactive snippets, and Lock Screen integrations, read System Surfaces.
For Siri voice matching, confirmation dialogs, and authentication policies, read Assistant Focus and Intent Behavior.
For Spotlight search indexing, deep link routing, and IndexedEntity, read URL and Spotlight Integration.
For iOS 27 on-screen annotations, new intent and entity protocols (SyncableEntity, LongRunningIntent, OwnershipProvidingEntity), and AppIntentsTesting, read iOS 27 Annotations and Testing.
Common Mistakes
- Performing UI navigation or view presentation directly inside
perform() without returning an OpenURLIntent or navigation result.
- Forgetting to provide an
EntityQuery for custom @Parameter entity types, breaking Shortcuts parameter selection.
- Hardcoding the app name in
AppShortcut phrases instead of using \(.applicationName).
- Running long network calls in
perform() without checking Task.isCancelled or providing progress dialogs.
- Omitting
typeDisplayRepresentation on AppEntity conformances.
Review Checklist
References
- Parameters and entity query implementations
- System surfaces: widgets, controls, and snippets
- Assistant focus, voice dialogs, and intent behavior
- URL and Spotlight search indexing
- iOS 27 annotations, new protocols, and AppIntentsTesting
- App Intents documentation
- AppIntent
1---2name: app-intents3description: "Implement App Intents for Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence on iOS. Covers AppIntent actions, AppEntity and EntityQuery models, AppShortcutsProvider phrases, IndexedEntity Spotlight indexing, WidgetConfigurationIntent, SnippetIntent, and assistant schemas. Use when exposing app actions or entities to system surfaces."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/app-intents6---78# App Intents910Expose app actions and entities to Siri, Shortcuts, Spotlight search, interactive widgets, Control Center, and Apple Intelligence using the `AppIntents` framework. Targets Swift 6.4 / iOS 26+.1112## Contents1314- [Triage Workflow](#triage-workflow)15- [System Surface Integration Matrix](#system-surface-integration-matrix)16- [AppEntity and EntityQuery](#appentity-and-entityquery)17- [AppShortcuts and Voice Phrases](#appshortcuts-and-voice-phrases)18- [Route by Task](#route-by-task)19- [Common Mistakes](#common-mistakes)20- [Review Checklist](#review-checklist)21- [References](#references)2223## Triage Workflow24251. **Select core actions**: Expose 1–3 high-value user tasks that make sense outside the app.262. **Define AppEntity models**: Create identifiable shadow models (`AppEntity`) for domain data referenced by the intent.273. **Implement AppIntent**: Define parameters with `@Parameter`, implement `perform() async throws -> some IntentResult`.284. **Register voice phrases**: Provide natural voice invocations with `AppShortcutsProvider`.295. **Verify system surface**: Test discovery in Shortcuts, Spotlight search, and widget configuration.3031## System Surface Integration Matrix3233| System Surface | Protocol / Attribute | Purpose |34|---|---|---|35| Siri & Shortcuts | `AppIntent` | Direct voice and shortcut automation |36| Configurable Widgets | `WidgetConfigurationIntent` | Supplies parameters to widget timelines |37| Control Center | `ControlConfigurationIntent` | Powers Control Center buttons and toggles |38| Spotlight Search | `IndexedEntity` | Indexes domain items into on-device Spotlight |39| Apple Intelligence | `@AppIntent(schema:)` | Assistant semantic reasoning and tooling |40| Interactive Snippets | `SnippetIntent` | In-line system confirmation views (iOS 26+) |4142## AppEntity and EntityQuery4344Expose domain data to intents using `AppEntity`:45```swift46struct OrderEntity: AppEntity {47 static var defaultQuery = OrderQuery()48 static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Order")4950 var id: UUID51 var displayRepresentation: DisplayRepresentation {52 DisplayRepresentation(title: "\(orderNumber)")53 }54}55```5657Implement `EntityQuery` to resolve identifiers (`entities(for:)`) and provide suggested choices (`suggestedEntities()`).5859## AppShortcuts and Voice Phrases6061Expose voice triggers without requiring user setup via `AppShortcutsProvider`:62- Register app shortcut phrases using `\(.applicationName)` token.63- Provide clean fallback phrases for Siri matching.6465## Route by Task6667- For `@Parameter` types, `AppEntity` declarations, and `EntityQuery` variants, read [Parameters and Entity Queries](references/parameters-and-entity-queries.md).68- For widget controls, interactive snippets, and Lock Screen integrations, read [System Surfaces](references/system-surfaces.md).69- For Siri voice matching, confirmation dialogs, and authentication policies, read [Assistant Focus and Intent Behavior](references/assistant-focus-and-intent-behavior.md).70- For Spotlight search indexing, deep link routing, and `IndexedEntity`, read [URL and Spotlight Integration](references/url-and-spotlight-integration.md).7172- For iOS 27 on-screen annotations, new intent and entity protocols (`SyncableEntity`, `LongRunningIntent`, `OwnershipProvidingEntity`), and AppIntentsTesting, read [iOS 27 Annotations and Testing](references/ios27-annotations-and-testing.md).7374## Common Mistakes7576- Performing UI navigation or view presentation directly inside `perform()` without returning an `OpenURLIntent` or navigation result.77- Forgetting to provide an `EntityQuery` for custom `@Parameter` entity types, breaking Shortcuts parameter selection.78- Hardcoding the app name in `AppShortcut` phrases instead of using `\(.applicationName)`.79- Running long network calls in `perform()` without checking `Task.isCancelled` or providing progress dialogs.80- Omitting `typeDisplayRepresentation` on `AppEntity` conformances.8182## Review Checklist8384- [ ] Intent conforms to `AppIntent` or specialized surface protocol85- [ ] Parameters have clear titles and valid default/suggested values86- [ ] Entities implement `EntityQuery` with `entities(for:)` and `suggestedEntities()`87- [ ] `perform()` returns an appropriate `IntentResult` (e.g. `.result()`, `.result(dialog:)`)88- [ ] Shortcuts phrases use `\(.applicationName)` macro89- [ ] Destructive actions declare `requestConfirmation()` before executing90- [ ] Sensitive actions require device authentication where appropriate9192## References9394- [Parameters and entity query implementations](references/parameters-and-entity-queries.md)95- [System surfaces: widgets, controls, and snippets](references/system-surfaces.md)96- [Assistant focus, voice dialogs, and intent behavior](references/assistant-focus-and-intent-behavior.md)97- [URL and Spotlight search indexing](references/url-and-spotlight-integration.md)98- [iOS 27 annotations, new protocols, and AppIntentsTesting](references/ios27-annotations-and-testing.md)99- [App Intents documentation](https://sosumi.ai/documentation/appintents)100- [AppIntent](https://sosumi.ai/documentation/appintents/appintent)