When AppEnum Breaks in App Intents — Designing EntityQuery so Siri Can Pick From a Catalog That Grows Every Day

Without String Search, a Large Catalog Is Unusable

suggestedEntities() is only the first set of candidates. When you have hundreds of collections, the user will want to narrow by name. To match when someone says to Siri, "open the Kyoto Nights collection," implement EntityStringQuery.

struct WallpaperCollectionQuery: EntityStringQuery {
    func entities(for identifiers: [String]) async throws -> [WallpaperCollection] {
        let all = await CollectionStore.shared.load()
        let map = Dictionary(uniqueKeysWithValues: all.map { ($0.id, $0) })
        return identifiers.compactMap { map[$0] }
    }
 
    func suggestedEntities() async throws -> [WallpaperCollection] {
        let all = await CollectionStore.shared.load()
        return Array(all.sorted { $0.lastUsedAt > $1.lastUsedAt }.prefix(10))
    }
 
    // (3) Narrow by what Siri heard; fold case differences away
    func entities(matching string: String) async throws -> [WallpaperCollection] {
        let all = await CollectionStore.shared.load()
        let needle = string.lowercased()
        return all.filter { $0.name.lowercased().contains(needle) }
    }
}

Where I actually stumbled was leaving entities(matching:) unimplemented and relying on suggestedEntities() alone. Any collection outside the top ten suggestions couldn't be picked even by saying its exact name. Trying to open "the one I added yesterday" by voice, if it wasn't in the suggestions, it would never surface. For a dynamic catalog, presenting (suggested) and searching (matching) are separate responsibilities and you need both — that's my current conclusion.

The Intent Itself Just Rides on the Query

Once the design is this far, the Intent itself becomes remarkably thin. Specify an AppEntity on the @Parameter and the OS handles both suggestion and search through your EntityQuery.

struct OpenCollectionIntent: AppIntent {
    static var title: LocalizedStringResource = "Open Collection"
    static var openAppWhenRun = true  // hand display work back to the app
 
    @Parameter(title: "Collection")
    var collection: WallpaperCollection
 
    @MainActor
    func perform() async throws -> some IntentResult {
        AppRouter.shared.open(collectionID: collection.id)
        return .result()
    }
}

Back when I used AppEnum, I rewrote the enum cases every time the options changed. After moving to this shape, adding a single record to the data store made both Siri and Shortcuts candidates follow automatically. The Intent code is written once and never touched again. Only the data grows — reaching that state was the real payoff.

Using an Array Index as the Identifier Fails Silently

The most common accident in AppEntity design is how you assign id. Not just Antigravity — generated code tends to grab whatever value is at hand for the identifier, and array offsets or loop counters slip in. For a dynamic catalog this is fatal.

If the sort order changes, or one item in the middle is deleted, an index-based ID points somewhere else. A shortcut the user saved by specifying "Kyoto Nights" opens a different collection the next day. And because it doesn't crash, it's hard to notice — entities(for:) simply returns "a different entity that happened to match."

The fix is simple: always use the persistent ID the data itself owns. In my wallpaper apps, each collection carries a stable slug assigned at creation time. Reorder or delete all you want; the ID of a living collection never changes. When you receive generated code, it's worth checking with your own eyes what the id derives from before anything else.

// Bad: the target shifts when ordering changes
let entities = collections.enumerated().map {
    WallpaperCollection(id: "\($0.offset)", name: $0.element.name, itemCount: $0.element.count)
}
 
// Good: use a stable, data-derived ID
let entities = collections.map {
    WallpaperCollection(id: $0.stableSlug, name: $0.name, itemCount: $0.count)
}

To catch this kind of mix-up before push in an agent workflow, the same idea from the static check in gating agent-written App Intents with a confirmation step applies. Distrust the output and mechanically verify where the identifier comes from — that one extra step prevents most of these re-resolution accidents.

For Spotlight, Add IndexedEntity

With the new intelligence framework widening assistant exposure, you'll want to open collections from Spotlight search too. Conform your AppEntity to IndexedEntity and the entity itself becomes a Spotlight index target.

import CoreSpotlight
 
extension WallpaperCollection: IndexedEntity {
    var attributeSet: CSSearchableItemAttributeSet {
        let attrs = CSSearchableItemAttributeSet(contentType: .content)
        attrs.title = name
        attrs.contentDescription = "\(itemCount)-image collection"
        return attrs
    }
}

The thing to watch here is that the responsibility for updating the index stays with the app. If you don't update CSSearchableIndex when a collection is added or removed, Spotlight's results diverge from the real data. App Intents makes it tempting to feel that "the OS just handles it," but the freshness of a dynamic catalog is still yours to maintain. Until I automated this, I shipped inconsistencies more than once where deleted collections lingered in search.

The basic steps for introducing App Intents are in implementing iOS App Intents with Antigravity. This piece focuses on the design specific to when the catalog is dynamic.

The Branch Point When You're Unsure

To close, let me distill the decision you make before writing any code. If the parameter's options are "a finite set of settings that can't grow without an app update," use AppEnum. If they are "data that grows on the user or server side," use AppEntity + EntityQuery, and implement EntityStringQuery too when you want name-based selection. Use a stable, data-derived identifier, and if you put it in Spotlight, pair IndexedEntity with index updates.

Start by picking just one parameter in your own app and putting into words whether it's a fixed menu or a dynamic catalog. Once that's clear, which type to choose decides itself. Thank you for reading.