app-intents

App Intents, Widgets & Live Activities

Expose your app's actions and surface them across the system — Siri, Shortcuts, Spotlight, widgets, Control Center, the Action button, and Live Activities. One App Intent powers all of them. Verify signatures against the apple-docs MCP (get_symbol, list_framework AppIntents); see ios26-api-reference for crash-prone API gotchas.

App Intents — the foundation

An AppIntent is a unit of app functionality the system can run. Define it once; reuse it in Shortcuts, Siri, widgets, and controls.

import AppIntents

struct StartFocusIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Focus Session"
    static let description = IntentDescription("Begins a focus session.")

    @Parameter(title: "Duration (minutes)")
    var minutes: Int

    // Bring the app to the foreground when run? Default false (runs in background).
    static let openAppWhenRun = false

    @MainActor
    func perform() async throws -> some IntentResult & ProvidesDialog {
        try await FocusEngine.shared.start(minutes: minutes)
        return .result(dialog: "Started a \(minutes)-minute session.")
    }
}

• perform() is async throws and returns some IntentResult. Compose result types: & ProvidesDialog, & ReturnsValue<T>, & OpensIntent, & ShowsSnippetView.
• @Parameter values can be requested interactively by Siri/Shortcuts when missing.
• Keep perform() fast and @MainActor only where it touches UI/model state (see ios-standards).

Entities & queries (let intents operate on your data)

struct Project: AppEntity {
    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Project"
    static let defaultQuery = ProjectQuery()
    var id: UUID
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(name)") }
    let name: String
}

struct ProjectQuery: EntityQuery {
    func entities(for ids: [UUID]) async throws -> [Project] { /* fetch */ }
    func suggestedEntities() async throws -> [Project] { /* recents */ }
}