app-intents

# App Intents (iOS 26+)

Implement, review, and extend App Intents to expose app functionality to Siri,
Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence.

## Contents

- [Triage Workflow](#triage-workflow)
- [AppIntent Protocol](#appintent-protocol)
- [`@Parameter`](#parameter)
- [AppEntity](#appentity)
- [EntityQuery (4 Variants)](#entityquery-4-variants)
- [AppEnum](#appenum)
- [AppShortcutsProvider](#appshortcutsprovider)
- [Siri Integration](#siri-integration)
- [Interactive Widget Intents](#interactive-widget-intents)
- [Control Center Widgets (iOS 18+)](#control-center-widgets-ios-18)
- [Spotlight and IndexedEntity (iOS 18+)](#spotlight-and-indexedentity-ios-18)
- [iOS 26 Additions](#ios-26-additions)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Triage Workflow

### Step 1: Identify the integration surface

Determine which system feature the intent targets:

| Surface | Protocol | Since |
|---|---|---|
| Siri / Shortcuts | `AppIntent` | iOS 16 |
| Configurable widget | `WidgetConfigurationIntent` | iOS 17 |
| Control Center | `ControlConfigurationIntent` | iOS 18 |
| Spotlight search | `IndexedEntity` | iOS 18 |
| Apple Intelligence | `@AppIntent(schema:)` | iOS 18 |
| Interactive snippets | `SnippetIntent` | iOS 26 |
| Visual Intelligence | `IntentValueQuery` | iOS 26 |

### Step 2: Define the data model

- Prefer `AppEntity` shadow models for app data exposed to the system.
- Create `AppEnum` types for fixed parameter choices.
- Choose the right `EntityQuery` variant for resolution.
- Mark searchable entities with `IndexedEntity` and `indexingKey` metadata.

### Step 3: Implement the intent

- Conform to `AppIntent` (or a specialized sub-protocol).
- Declare `@Parameter` properties for all user-facing inputs.
- Implement `perform() async throws -> some IntentResult`.
- Add `parameterSummary` for Shortcuts UI.
- Register phrases via `AppShortcutsProvider`.

### Step 4: Verify

- Build and run in Shortcuts app to confirm parameter resolution.
- Test Siri phrases with the intent preview in Xcode.
- Confirm `IndexedEntity` instances are indexed in a named Spotlight index.
- Check widget configuration for `WidgetConfigurationIntent` intents.

## AppIntent Protocol

The system instantiates the struct via `init()`, sets parameters, then calls
`perform()`. Declare a `title` and `parameterSummary` for Shortcuts UI.

```swift
struct OrderSoupIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Soup"
    static var description = IntentDescription("Place a soup order.")

    @Parameter(title: "Soup") var soup: SoupEntity
    @Parameter(title: "Quantity", default: 1) var quantity: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Order \(\.$soup)") { \.$quantity }
    }

    func perform() async throws -> some IntentResult {
        try await OrderService.shared.place(soup: soup.id, quantity: quantity)
        return .result(dialog: "Ordered \(quantity) \(soup.name).")
    }
}
```

Optional members: `description` (`IntentDescription`), `openAppWhenRun` (`Bool`),
`isDiscoverable` (`Bool`), `authenticationPolicy` (`IntentAuthenticationPolicy`).

## `@Parameter`

Declare each user-facing input with `@Parameter`. Non-optional parameters are
required; the system requests values when needed. Defaults pre-fill a useful
value. Optional parameters are not requested automatically, so ask for them in
`perform()` when the intent cannot continue without a value.

```swift
// Required; the system asks for a value when needed
@Parameter(title: "Count")
var count: Int

// Required and pre-filled
@Parameter(title: "Count", default: 1)
var count: Int

// Optional; request it yourself if it becomes necessary
@Parameter(title: "Count")
var count: Int?
```

### Supported value types

Primitives: `Bool`, `Int`, `Double`, `String`, `Duration`, `Date`, `Decimal`,
`Measurement`, and `URL`. Collections: `Array` and `Set` of supported element
types. Framework: `IntentPerson`, `IntentFile`. Custom: any `AppEntity` or
`AppEnum`.

### Common initializer patterns

```swift
// Basic
@Parameter(title: "Name")
var name: String

// With default
@Parameter(title: "Count", default: 5)
var count: Int

// Numeric slider
@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
var volume: Int

// Options provider (dynamic list)
@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
var category: Category

// File with content types
@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
var document: IntentFile

// Measurement with unit
@Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false)
var distance: Measurement<UnitLength>
```

See [references/appintents-advanced.md](references/appintents-advanced.md) for all initializer variants.

## AppEntity

Prefer shadow models that mirror app data and expose only system-facing fields.
Direct model conformance is allowed when the model is lightweight, stable, and
appropriate for App Intents lifecycles.

```swift
struct SoupEntity: AppEntity {
    static let defaultQuery = SoupEntityQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"
    var id: String

    @Property(title: "Name") var name: String
    @Property(title: "Price") var price: Double

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)", subtitle: "$\(String(format: "%.2f", price))")
    }

    init(from soup: Soup) {
        self.id = soup.id; self.name = soup.name; self.price = soup.price
    }
}
```

Required: `id`, `defaultQuery` (static), `displayRepresentation`,
`typeDisplayRepresentation` (static). Mark properties with `@Property(title:)`
to expose for filtering/sorting. Properties without `@Property` remain internal.

## EntityQuery (4 Variants)

### 1. EntityQuery (base -- resolve by ID)

```swift
struct SoupEntityQuery: