App Intents são a nova API da Apple para o seu app

Na manhã de 8 de fevereiro de 2026, pedi para a Siri registrar 8 oz de água do meu Apple Watch enquanto minhas mãos estavam embaixo da pia da cozinha. A água foi registrada. O diálogo do relógio mostrou 32 oz restantes. Eu não havia tocado em nenhuma tela.¹

Onze semanas antes, eu havia adicionado um único arquivo Swift ao Water, meu app iOS de monitoramento de hidratação: LogWaterIntent.swift, 80 linhas de AppIntent mais um AppShortcutsProvider declarando três variantes de frase para a Siri. Esse arquivo é agora a API mais quente que eu tenho.²

Aqui está a parte que demorou um tempo para eu internalizar. App Intents não são um recurso da Siri. Eles são o contrato que apps de terceiros assinam com a Apple Intelligence, as superfícies de IA do sistema que a Apple começou a lançar no iOS 18 e continuou desenvolvendo até o iOS 26.³ Se você lança um app iOS e ainda está tratando App Intents como um recurso de voz “bom de ter”, você está interpretando errado o que a Apple construiu. App Intents são a API que permite que a IA da Apple aja como o seu app em nome do usuário. Todo o resto (Siri, Spotlight, Shortcuts, resumos da Apple Intelligence, as superfícies do Watch e do Vision Pro) é resultado desse contrato. Foundation Models, o LLM on-device que veio com o iOS 26, expõe um protocolo Tool separado para chamadas de ferramentas dentro do app; ele roda em paralelo aos App Intents, e não através deles.

TL;DR

• App Intents declaram o que seu app pode fazer de uma forma tipada e estruturada que a IA da Apple pode chamar diretamente. Eles são a API de uso de ferramentas da Apple para apps de terceiros.
• Um exemplo real de produção: LogWaterIntent no Water. 80 linhas, escrita completa no SwiftData, sincronização com HealthKit, conversão de unidades sensível ao locale, resposta de diálogo Siri estruturada.
• O iOS 26 adicionou o Foundation Models, o LLM on-device da Apple. O Foundation Models expõe seu próprio protocolo Tool para uso de ferramentas dentro do app; App Intents permanecem como a superfície canônica que Siri / Spotlight / Apple Intelligence chamam entre apps. Mesma direção, dois contratos paralelos.
• Um app sem App Intents em 2026 é invisível para a Apple Intelligence. O tecido de IA roteia através dos seus intents declarados ou roteia ao redor do seu app para um concorrente.
• A Apple vem nos dizendo isso há três anos. A nomenclatura (App Intents, App Shortcuts, Apple Intelligence) é proposital. O contrato sobe um nível na pilha a cada WWDC.

O que um App Intent realmente é

O código-fonte completo do LogWaterIntent como foi lançado no commit e398c58 em 8 de fevereiro de 2026:²

import AppIntents
import SwiftData

struct LogWaterIntent: AppIntent {
    static var title: LocalizedStringResource = "Log Water"
    static var description: IntentDescription = "Log a glass of water to your daily intake"

    @Parameter(title: "Amount", default: 8)
    var amount: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Log \(\.$amount) oz of water")
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        let container = try ModelContainer(for: WaterEntry.self, DailyLog.self, UserSettings.self)
        let context = ModelContext(container)

        let settingsDescriptor = FetchDescriptor<UserSettings>(
            predicate: #Predicate { $0.id == "user-settings" }
        )
        let settings = try context.fetch(settingsDescriptor).first ?? UserSettings()

        let amountMl: Double
        if settings.unitSystem == .imperial {
            amountMl = Double(amount) * 29.5735
        } else {
            amountMl = Double(amount)
        }

        let todayKey = DailyLog.todayKey()
        let logDescriptor = FetchDescriptor<DailyLog>(
            predicate: #Predicate { $0.dateKey == todayKey }
        )
        let log: DailyLog
        if let existing = try context.fetch(logDescriptor).first {
            log = existing
        } else {
            log = DailyLog(date: .now, goalAmount: settings.dailyGoal)
            context.insert(log)
        }

        let entry = WaterEntry(amount: amountMl)
        log.entries.append(entry)
        try context.save()

        if settings.healthKitEnabled {
            try? await HealthKitService.shared.logWater(amount: amountMl, date: entry.timestamp)
        }

        let unit = settings.unitSystem == .imperial ? "oz" : "mL"
        let totalDisplay = settings.formatAmount(log.totalAmount)
        return .result(dialog: "Logged \(amount) \(unit). Today's total: \(totalDisplay)")
    }
}

struct WaterShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: LogWaterIntent(),
            phrases: [
                "Log water in \(.applicationName)",
                "Add water in \(.applicationName)",
                "Drink water in \(.applicationName)",
            ],
            shortTitle: "Log Water",
            systemImageName: "drop.fill"
        )
    }
}

(A versão de produção atual desse arquivo no Water itera mais o diálogo com uma condicional de meta-atingida/quantidade-restante. O código de 8 de fevereiro acima é o que testei na pia da cozinha.)

Três coisas aqui valem ser nomeadas porque a maioria dos “tutoriais de App Intents” passa por cima delas.

O @Parameter é o schema. A IA da Apple vê amount: Int com padrão de 8. Quando a Siri analisa “registrar 12 oz de água” ela produz LogWaterIntent(amount: 12) e chama perform(). Não há parsing de string do meu lado. O sistema de tipos é o schema.⁵

parameterSummary é o reflexo em linguagem natural do parâmetro. A Apple usa para renderizar a ação na UI do Shortcuts, no diálogo e cada vez mais nos painéis de confirmação da Apple Intelligence. O resumo é lido em voz alta para o usuário. Erre nele e o usuário ouve uma frase feia; acerte e a superfície parece nativa.⁶

perform() retorna IntentResult & ProvidesDialog. Esse é o retorno estruturado: a superfície de IA recebe de volta não apenas sucesso/falha, mas uma string de diálogo que o usuário ouve. A Apple está cada vez mais esperando ProvidesDialog, ProvidesView ou ReturnsValue para que o resultado se componha na Siri, Spotlight, no Watch e (no iOS 26) na cadeia de respostas da Apple Intelligence.⁷

O bloco AppShortcutsProvider no final é o que registra as frases da Siri. O token \(.applicationName) é onde a Siri insere “Water” automaticamente. Três variantes de frase com o mesmo intent dão ao parser de NL da Apple mais espaço para combinar com a fraseologia do usuário sem que você precise manter um dicionário de frases. O systemImageName é um nome real de SF Symbols; é assim que o Spotlight, Shortcuts e Apple Intelligence renderizam o ícone da ação.

Por que esta é a API iOS mais importante desde o SwiftUI

APIs do iOS vêm em duas formas. Algumas são sobre como seu app se desenha (UIKit, SwiftUI, Metal). Algumas são sobre como seu app se integra com o sistema (URL schemes, Universal Links, Widgets). App Intents são uma terceira forma: eles são como a IA da Apple usa seu app.

A progressão vale a pena ser traçada.

• iOS 10 (2016) introduziu SiriKit Intents (INIntent), a primeira vez em que apps de terceiros podiam ser acionados por voz. A superfície era estreita: uma lista fixa de domínios (mensagens, pagamentos, reserva de carros) com schemas rigorosos.⁸
• iOS 12 (2018) ampliou a superfície com Siri Shortcuts: qualquer app podia doar um NSUserActivity ou INIntent e torcer para que a Siri o sugerisse.
• iOS 13 (2019) adicionou o tratamento de intents dentro do app para que apps pudessem responder a invocações de shortcuts sem voltar para a UI da Siri do sistema.
• iOS 16 (2022) introduziu o framework App Intents: tipado, declarativo, com @Parameter e AppShortcutsProvider. O predecessor INIntent foi efetivamente substituído para novos desenvolvimentos.⁹
• iOS 18 (2024) introduziu a Apple Intelligence e começou a rotear solicitações da Siri através de App Intents sempre que possível. O recurso de “contexto pessoal” da Apple Intelligence lê de App Entities (a versão de dados dos App Intents).¹⁰
• iOS 26 (2025) introduziu o framework Foundation Models, o LLM on-device da Apple. O Foundation Models expõe um protocolo Tool separado para chamadas de ferramentas dentro do app. App Intents permanecem como a superfície canônica entre apps para a Apple Intelligence, enquanto Tool é a superfície dentro do app para chamadas diretas ao LLM. Os dois contratos rodam em paralelo.⁴

O contrato vem se estendendo um nível acima na pilha a cada release. Originalmente o consumidor de um App Intent era uma pessoa tocando em Shortcuts. Depois a voz da Siri. Depois o Spotlight. Depois resumos da Apple Intelligence. Agora as superfícies do sistema da Apple Intelligence apoiadas em LLM os usam para agir em solicitações do usuário. A superfície de App Intent que você lança em 2026 é a que a Apple Intelligence vai chamar no iOS 27, 28, 29.

O padrão acima é o que quero dizer quando digo que App Intents não são um recurso da Siri. Eles são a API de uso estruturado de ferramentas para todo o tecido de IA da Apple. SwiftUI foi a API de UI mais importante porque se tornou a única maneira de escrever um app para visionOS, watchOS 10+ e iOS 17+. App Intents estão seguindo o mesmo arco no lado da IA: a superfície onde a Apple está colocando todas as suas apostas.

O que muda agora que o Foundation Models foi lançado

O Foundation Models é o framework que vem em todos os dispositivos elegíveis para a Apple Intelligence. O corte de hardware é a mesma lista da Apple Intelligence: iPhone 15 Pro e 15 Pro Max (A17 Pro), linha iPhone 16, linha iPhone 17, iPhone Air, iPhone 17e, iPad Pro com M1 ou posterior, iPad Air com M1 ou posterior, iPad mini com A17 Pro, Vision Pro com M2 ou posterior e Mac com M1 ou posterior. Notavelmente ausentes: iPhone 15 / 15 Plus base.⁴¹²

A implicação: se as superfícies de sistema da Apple (Siri, Spotlight, Apple Intelligence) chamam seu app, elas o chamam através de App Intents e App Entities. Não há API setSystemPrompt(...) para apps de terceiros no tecido de IA do sistema. Há o registro de intents. O Foundation Models adiciona uma superfície Tool paralela dentro do app para desenvolvedores que querem seus próprios recursos de LLM on-device. O contrato entre apps (o que a Apple Intelligence e a Siri usam para encontrar seu app) passa pelos App Intents.

Três consequências concretas para desenvolvedores de apps:

Um app sem um App Intent relevante não é alcançável a partir de um comando de voz da Siri em sua categoria. A Apple Intelligence roteia frases como “Hey Siri, registre minha água” para apps que declararam o intent correspondente primeiro. Lancei o intent do Water em fevereiro de 2026. Minha leitura da direção do framework: apps de hidratação que lançarem o intent em 2027 estarão entrando em um mercado onde os pesos de roteamento já se acumularam em direção aos pioneiros. A mesma lógica se aplica a listas de compras, registro de treinos, entradas de calendário, buscas de fotos. Espero que a vantagem do pioneiro nas declarações de intents se acumule da mesma forma que aconteceu com outras APIs estratégicas da plataforma Apple (categorias do HealthKit, resultados ricos do Spotlight, tokens de Live Activities).

A personalização da Apple Intelligence lê de App Entities, não apenas de intents. Um AppEntity declara “este app tem dados desta forma”. Quando o usuário pergunta “qual foi o último livro que adicionei à minha lista de leitura”, a Apple Intelligence procura em todo AppEntity que corresponda a Book em todos os apps instalados. Se seu app tem uma lista de leitura e nenhum BookEntity declarado, seus dados são invisíveis para as superfícies de IA da Apple. A Apple Intelligence não consegue recuperar ou referenciar seus dados.¹¹

A forma de retorno IntentResult & ProvidesDialog é cada vez mais importante. A Apple Intelligence está compondo resultados de intents em respostas mais longas pela Siri, Spotlight e o Watch. Um perform() que apenas retorna sucesso sem um diálogo estruturado é mais difícil para o sistema compor em uma resposta coerente. ProvidesDialog e ProvidesView não são gentilezas opcionais; é como sua ação se torna uma citação na superfície de IA do usuário.

O que eu construiria de forma diferente

Onze semanas de logs de produção no Water me dizem três coisas que eu deveria ter feito antes.

Lance mais intents do que você acha que precisa. Lancei um. Eu deveria ter lançado quatro: LogWaterIntent, CheckTodaysProgressIntent, AdjustGoalIntent, ShowHistoryIntent. Cada um mapeia para uma frase da Siri que os usuários realmente tentam (“quanta água eu bebi hoje” roteado para a IA genérica da Apple em vez de para os dados do meu app). Cada intent perdido é uma consulta que a Apple Intelligence roteia ao redor de mim.

A string de diálogo não é o corpo de um e-mail. Eu tinha ProvidesDialog desde o início, mas meu diálogo inicial era prosa. O usuário ouvindo isso através do CarPlay ou AirPods precisa de estrutura curta, concreta e baseada em fatos: “8 oz registrados. Faltam 32 oz.” A superfície do Watch em particular trunca agressivamente. Diálogo conversacional é uma experiência de usuário pior do que diálogo confiante baseado em fatos. Reescrevi o meu na semana 4.²

App Entities importam mais do que eu pensava. Tenho um modelo SwiftData WaterEntry. Eu também deveria declarar um WaterEntryEntity: AppEntity mais seu companheiro WaterEntryQuery: EntityQuery para que a Apple Intelligence possa responder “mostre quando bebi água ontem”. A ponte mínima:¹¹

struct WaterEntryEntity: AppEntity {
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Water Entry"
    static var defaultQuery = WaterEntryQuery()
    var id: UUID
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(amount) oz at \(timestamp.formatted())")
    }
    var amount: Int
    var timestamp: Date
}

struct WaterEntryQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [WaterEntryEntity] {
        // Fetch matching entries from SwiftData
    }
    func suggestedEntities() async throws -> [WaterEntryEntity] {
        // Recent entries Apple Intelligence can suggest
    }
}

Dois pequenos tipos Swift mais a cola de fetch do SwiftData. Para tornar entradas individualmente exibíveis no Spotlight (para que usuários buscando “água” cheguem na entrada certa), faça a entity conformar com IndexedEntity e doe atualizações de índice nas escritas. É isso que o pipeline do Spotlight da Apple espera além da exposição básica de AppEntity.

A mesma forma se aplica em outros lugares dos meus apps. Get Bananas, meu app de lista de compras, já tem um @Model ShoppingItem SwiftData com @Attribute(.unique) var id: UUID, name, amount, section, isChecked, mais um campo lastModified para sincronização via iCloud Drive.¹³ Envolvê-lo como ShoppingItemEntity: AppEntity e lançar um par de intents (AddShoppingItem, CheckOffItem, ShowList) exporia a mesma camada de persistência para a Apple Intelligence que o Get Bananas já expõe ao Claude Desktop através do seu servidor MCP .mcpb.¹⁴ Dois ecossistemas de LLM, dois contratos diferentes, mesma lista de compras. Essa é a tese de contratos paralelos como um único app lançado: o modelo SwiftData é o dado, App Intents são o contrato da Apple, MCP é o contrato da Anthropic, ambas as superfícies operam sobre a mesma fonte da verdade.

Quando não lançar um App Intent

A recusa é parte do design.

Se seu app é puramente orientado a consumo (lendo as fotos do usuário, exibindo notícias, tocando áudio) sem estado mutável do usuário, App Intents podem não ter nada para expor. O framework da Apple suporta OpenIntent (apenas abre o app em um contexto), mas se a única ação útil é “abrir o app”, o intent é overhead. Não lance um só por lançar.

Se a ação depende de affordances de UI difíceis de abstrair (uma ferramenta de canvas multi-passo complexa, um app de edição 3D), o parameterSummary necessário do intent vai degradar para uma pseudo-linguagem-natural vaga que ninguém fala de fato. A frase Siri “edite minha foto com a ferramenta de blur com força 7” é tecnicamente possível, mas nenhum humano vai pronunciá-la. A superfície do intent é um imposto sem retorno.

A regra certa: um App Intent vale a pena quando existe uma frase que um usuário diria naturalmente para acionar a ação. “Registrar 8 oz de água” é essa frase. “Aplicar blur Gaussiano com sigma 2.4 na camada 3” não é. Se as ações do seu app se agrupam no segundo padrão, intents não são sua alavanca de conversão.

A conclusão

Por três anos a Apple vem sinalizando que o tecido de IA do sistema do iOS passa pelos App Intents. A WWDC 2024 adicionou o roteamento da Apple Intelligence através deles. A WWDC 2025 adicionou o Foundation Models ao lado como uma superfície separada de chamada de ferramentas dentro do app, deixando os App Intents como o contrato entre apps que Siri / Spotlight / Apple Intelligence continuam usando. Cada sinal aponta para a mesma direção: o App Intent tipado e declarativo é o contrato que apps de terceiros agora assinam com o sistema.

A maioria dos apps iOS ainda trata App Intents como Siri Shortcuts: um recurso para lançar se você tiver tempo. Minha leitura é que esse enquadramento vai envelhecer mal. À medida que as superfícies de sistema da Apple Intelligence se estendem (já através de Siri, Spotlight, Shortcuts e resumos da Apple Intelligence hoje), apps sem intents declarados provavelmente vão se encontrar fora do grafo de roteamento. A superfície do pioneiro, na minha experiência observando outras apostas de plataforma da Apple, se acumula.

O Water tem o LogWaterIntent lançado há onze semanas. A quantidade de código que lança um App Intent é pequena o suficiente para caber em um único arquivo. O custo de não lançá-lo cresce a cada release da Apple Intelligence.

Se você lança um app iOS em 2026 e não declarou pelo menos um App Intent, seu roadmap tem um item faltando. Adicione.

FAQ

O que é um App Intent no desenvolvimento iOS?

Um App Intent é uma estrutura Swift tipada e declarativa que expõe uma das ações do seu app para as superfícies de IA do sistema da Apple. Ela declara parâmetros via @Parameter, um resumo em linguagem natural via parameterSummary e um corpo perform() async que executa o trabalho e retorna um resultado estruturado. Siri, Spotlight, Shortcuts e Apple Intelligence da Apple podem chamá-lo. O Foundation Models (o LLM on-device da Apple) usa um protocolo Tool separado para chamadas diretas de ferramentas dentro do app.

Como App Intents é diferente do INIntent mais antigo?

App Intents (introduzido no iOS 16, 2022) substituiu INIntent como o framework principal de intents da Apple. O framework mais novo é totalmente nativo em Swift, usa property wrappers como @Parameter, suporta consultas de entidade type-safe via AppEntity e é a superfície que Siri, Spotlight, Shortcuts e Apple Intelligence chamam. O INIntent mais antigo ainda é suportado, mas não recebe trabalho em novos recursos.

Preciso do iOS 26 para lançar um App Intent?

Não. App Intents estão disponíveis a partir do iOS 16. O iOS 26 adiciona o framework Foundation Models ao lado, mas as próprias declarações de App Intent funcionam no iOS 16+. O código de exemplo acima usa SwiftData (iOS 17+), então o target de deploy depende do que o corpo do seu perform() importa. App Intents básicos funcionam até o iOS 16; os apoiados em SwiftData precisam do iOS 17.

Qual é a diferença entre um App Intent e um App Entity?

Um App Intent é uma ação (verbo). Um App Entity são os dados que seu app conhece (substantivo). LogWaterIntent é um intent. WaterEntry se tornando um tipo consultável é uma entity. A Apple Intelligence usa ambos: intents para realizar ações, entities para recuperar e referenciar dados em respostas.

Como App Intents se relacionam com as chamadas de ferramentas do Foundation Models?

O Foundation Models expõe seu próprio protocolo Tool para chamadas diretas de ferramentas de LLM dentro do app. App Intents permanecem como a superfície canônica entre apps que a Apple Intelligence, Siri e Spotlight chamam. Mesma direção (uso tipado e declarativo de ferramentas); dois contratos paralelos. Um app que quer ser alcançável pelas superfícies de IA do sistema lança App Intents; um app que quer chamar seu próprio LLM on-device com ferramentas customizadas lança conformidades com Tool. Muitos apps vão lançar ambos.

App Intents não são um recurso. Eles são o contrato. O app que lança o intent primeiro ganha a superfície; o app que lança depois encontra a superfície já roteada para outro lugar. Onze semanas atrás lancei um no Water. O efeito composto já começou.

Referências