Rork Max のアプリ機能を Apple Intelligence に開く — App Intents Assistant Schemas の設計と、収まらない機能の逃がし方

スキーマ準拠の App Intent を書く

準拠は @AssistantIntent(schema:) マクロで宣言します。スキーマが要求するパラメータや戻り値の型は、コンパイラが検査します。必須のプロパティを欠くとビルドが通らないため、「宣言はしたが Apple Intelligence の期待に合っていない」という中途半端な状態を早い段階で潰せます。

import AppIntents
 
@AssistantIntent(schema: .photos.openAsset)
struct OpenWallpaperIntent: OpenIntent {
    static let title: LocalizedStringResource = "壁紙を開く"
 
    // スキーマが target を要求する。型は AssistantEntity 準拠が必須。
    @Parameter(title: "壁紙")
    var target: WallpaperEntity
 
    func perform() async throws -> some IntentResult {
        // 自分のアプリの実処理。ここは Rork Max が吐いた
        // 表示ロジックを呼び出すだけに留めるのが安全です。
        await WallpaperRouter.shared.present(id: target.id)
        return .result()
    }
}

対象を表すエンティティも、対応するスキーマに準拠させます。@AssistantEntity(schema:) を付けると、Apple Intelligence がこのエンティティを「写真アセット」として扱えるようになります。

@AssistantEntity(schema: .photos.asset)
struct WallpaperEntity: IndexedEntity {
    let id: String
 
    // スキーマ側が要求する表示名。命名はユーザーの言葉に寄せます。
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(title)")
    }
 
    let title: String
    let assetURL: URL
}

perform() の中で表示ロジックを厚く書かない、というのは実運用での戒めです。Apple Intelligence 経由の呼び出しはアプリが前面にない状態でも走ります。UI 状態に依存した処理を Intent 側に持たせると、バックグラウンドからの起動で崩れます。Intent はルーティングの入り口に留め、実処理は既存のルーターに委譲する。この分離を最初から守ると、後の事故が目に見えて減りました。

固定スキーマに収まらない機能の逃がし方

現実には、12ドメインのどれにも当てはまらない機能が必ず出ます。壁紙アプリで言えば「今日の一枚をシャッフルする」のような、写真を開くでも探すでもない独自操作です。

ここで無理に photos スキーマへ押し込むと、Apple Intelligence が誤った文脈で呼ぶ危険があります。「写真を開いて」と言ったユーザーにシャッフルが走れば、体験としては壊れています。収まらない機能は、素直にカスタム App Intent として書き、AppShortcuts で露出させるのが安全です。

struct ShuffleWallpaperIntent: AppIntent {
    static let title: LocalizedStringResource = "壁紙をシャッフル"
    static let openAppWhenRun = false
 
    func perform() async throws -> some IntentResult {
        try await WallpaperStore.shared.shuffleToday()
        return .result()
    }
}
 
struct WallpaperShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: ShuffleWallpaperIntent(),
            phrases: [
                "\(.applicationName) で壁紙をシャッフル",
                "\(.applicationName) の壁紙を切り替えて"
            ],
            shortTitle: "シャッフル",
            systemImageName: "shuffle"
        )
    }
}

判断軸はひとつです。その操作が Apple の語彙で自然に言い表せるなら Assistant Schema、言い表せない独自価値ならカスタム Intent。スキーマは「アプリをまたぐ共通操作」のための共通語であって、アプリ固有の魅力を無理に翻訳する場所ではない、と捉えると迷いません。

エンティティとクエリ — 対象を見つける導線

Apple Intelligence が「あの壁紙」を特定するには、候補を返す EntityQuery が要ります。ここを雑に作ると、対象の解決に失敗して操作全体が不発になります。

struct WallpaperQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [WallpaperEntity] {
        try await WallpaperStore.shared.load(ids: identifiers)
    }
 
    // 曖昧なときに提示する候補。件数を絞ると解決が速くなります。
    func suggestedEntities() async throws -> [WallpaperEntity] {
        try await WallpaperStore.shared.recent(limit: 10)
    }
}

suggestedEntities() の返す件数は、体感速度に直結します。全件を返すと解決が重くなり、Siri の応答が目に見えて遅れます。直近や人気順で10件程度に絞ると、実機での待ち時間が短くなりました。対象が一意に定まらないときは、Apple Intelligence がこの候補から選ばせる導線を出します。ここで表示名が曖昧だと、ユーザーがどれを選べばよいか分からなくなります。displayRepresentation の命名は、内部 ID ではなくユーザーが口にする言葉に寄せる。この一手間が、曖昧性解消の質を決めます。

可用性フォールバック — 非対応端末で機能を死なせない

Assistant Schemas と Apple Intelligence は、対応端末と対応 OS でしか動きません。個人開発で複数アプリを回していると、古い端末のユーザーも一定数います。スキーマ準拠 Intent を入れたことで、非対応端末で機能そのものが消えては本末転倒です。

設計の勘所は、Intent の登録と機能の提供を分けることです。Assistant Schema は「呼ばれ方の追加経路」であって、機能の本体ではありません。本体はアプリ内 UI に必ず残し、Assistant 経由はその上に重ねる副経路として扱います。

enum AssistantAvailability {
    static var canUseSchemas: Bool {
        if #available(iOS 18.2, *) { return true }
        return false
    }
}

この分離を守れば、非対応端末でもアプリ内から同じ操作ができます。Apple Intelligence 対応を「あれば嬉しい上乗せ」に位置づけ、可用性チェックの結果でアプリ内導線を出し分ける。落とし穴は、対応を前提に UI から本体ボタンを消してしまうことです。そうすると古い端末で機能が丸ごと失われます。

実機での確認 — Shortcuts と Siri の両輪で見る

シミュレータでは Apple Intelligence の挙動を十分に再現できません。確認は実機で、二段階に分けると漏れが減りました。

まず Shortcuts アプリで、Intent がアクションとして現れるかを見ます。ここに出なければ、そもそも App Intents の登録に失敗しています。ビルド構成やターゲットメンバーシップの取りこぼしを、この段階で潰します。

次に Siri へ自然な言い回しで話しかけ、スキーマ経由で呼ばれるかを確かめます。登録フレーズそのままではなく、あえて崩した言い方で試すのが要点です。フレーズ一致ではなく意味推論が働いているかは、崩した言い方でしか分かりません。

Rork Max の Swift に後付けするときの段取り

Rork Max は自然言語からネイティブ Swift を生成します。表示や保存の処理は、たいてい既に手元のコードにあります。Assistant Schemas の後付けは、その既存処理を Intent の perform() から呼び出す薄い層を重ねる作業です。

私自身が守っている順番は、機能本体を触らないことから始めます。まず既存のルーターや Store をそのままにして、Intent とエンティティだけを新しいファイルとして足します。Rork Max が吐いたコードに手を入れ始めると、再生成のたびに差分が壊れます。Assistant 対応は独立したファイル群として分け、生成コードには「呼び出される口」だけを最小限で開ける。この境界を最初に引くと、ツールの再生成と自分の実装が衝突しません。

順を追うと、次のようになります。第一に、機能を Apple の語彙に翻訳できるか棚卸しする。第二に、翻訳できるものはスキーマ準拠 Intent、できないものはカスタム Intent と AppShortcuts に振り分ける。第三に、エンティティとクエリを用意し、候補件数を絞る。第四に、可用性チェックでアプリ内導線を残す。第五に、実機で二段階の確認を回す。

運用して見えたこと

対応を入れて実感したのは、Apple Intelligence 対応が集客の魔法ではないことです。話しかけて呼ばれる機能が増えても、それだけでダウンロードが跳ねるわけではありません。効いてきたのは、既存ユーザーが操作にたどり着く経路が一本増えたことでした。メニューの奥にあった操作を声で呼べるようになると、その機能の利用そのものが少し増える。派手ではありませんが、静かに効く種類の改善です。

ネイティブ機能に手が届くのが Rork Max の値打ちだとすると、Assistant Schemas はその値打ちを最も実感しやすい入り口のひとつだと感じています。写真を開く、探す、といった共通操作を Apple の語彙で宣言し、独自価値はカスタム Intent として素直に残す。その線引きを丁寧に引くほど、Apple Intelligence はアプリの意図を正しく汲んでくれます。

まだ手探りの部分も多い領域ですが、実装の勘所が誰かの一歩を軽くできれば嬉しいです。お読みいただきありがとうございました。