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

Na manhã de 8 de fevereiro de 2026, pedi ao Siri para registrar 8 oz de água a partir do meu Apple Watch enquanto minhas mãos estavam embaixo da pia da cozinha. A água foi registrada. O diálogo no 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 do Siri. Esse arquivo é agora a superfície de API mais quente que possuo.²

Aqui está a parte que levou um tempo para eu internalizar. App Intents não são um recurso do 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 construindo até o iOS 26.³ Se você lança um app iOS e ainda trata App Intents como um recurso de voz “bom de ter”, está interpretando mal 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. Tudo o mais (Siri, Spotlight, Shortcuts, resumos da Apple Intelligence, as superfícies do Watch e do Vision Pro) deriva desse contrato. O Foundation Models, o LLM on-device que chegou no iOS 26, expõe um protocolo Tool separado para chamadas de ferramentas dentro do app; ele opera em paralelo aos App Intents, e não através deles.

TL;DR

• App Intents declaram o que seu app pode fazer de 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 unidade ciente do locale, resposta de diálogo estruturada do Siri.
• 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 continuam sendo 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. A malha de IA roteia através dos seus intents declarados ou contorna seu app em direção a 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.

Imagem de referência do framework App Intents da documentação do Apple Developer.⁵

O que é, de fato, um App Intent

O código completo de 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 atual de produção desse arquivo no Water itera o diálogo ainda mais com um condicional de meta-atingida/quantidade-restante. O código lançado em 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 um padrão de 8. Quando o Siri analisa “log 12 oz of water”, ele 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 isso 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 de volta em voz alta para o usuário. Erre 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 no Siri, Spotlight, Watch e (no iOS 26) na cadeia de respostas da Apple Intelligence.⁷

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

A Apple Intelligence roteia as solicitações do usuário através de App Intents para entregar recursos de IA on-device. Fonte: apple.com/apple-intelligence.

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). Outras são sobre como seu app se integra ao sistema (esquemas de URL, Universal Links, Widgets). App Intents são uma terceira forma: eles são como a IA da Apple usa seu app.

Vale a pena rastrear a progressão.

• iOS 10 (2016) introduziu os SiriKit Intents (INIntent), a primeira vez em que apps de terceiros podiam ser endereçados por voz. A superfície era estreita: uma lista fixa de domínios (mensagens, pagamentos, reserva de corridas) com schemas estritos.⁸
• iOS 12 (2018) ampliou a superfície com Siri Shortcuts: qualquer app podia doar um NSUserActivity ou INIntent e torcer para o Siri sugeri-lo.
• iOS 13 (2019) adicionou tratamento de intent dentro do app, para que apps pudessem responder a invocações de shortcut sem ir ao background para a UI do Siri do sistema.
• iOS 16 (2022) introduziu o framework App Intents: tipado, declarativo, com @Parameter e AppShortcutsProvider. O antecessor INIntent foi efetivamente substituído para novos desenvolvimentos.⁹
• iOS 18 (2024) introduziu a Apple Intelligence e começou a rotear solicitações do Siri através de App Intents sempre que possível. O recurso de “contexto pessoal” da Apple Intelligence lê dos 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 pilha acima a cada release. Originalmente, o consumidor de um App Intent era uma pessoa tocando no Shortcuts. Depois, a voz do Siri. Depois, o Spotlight. Depois, os resumos da Apple Intelligence. Agora, as superfícies do sistema da Apple Intelligence sustentadas por LLM os usam para agir nas solicitações do usuário. A superfície de App Intent que você lança em 2026 é a que a Apple Intelligence vai estar chamando no iOS 27, 28, 29.

O padrão acima é o que quero dizer quando afirmo que App Intents não são um recurso do Siri. Eles são a API de uso de ferramentas estruturado para toda a malha 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 todo dispositivo elegível para 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 existe uma API setSystemPrompt(...) para apps de terceiros na malha de IA do sistema. Existe o registro de intents. O Foundation Models adiciona uma superfície paralela Tool dentro do app para desenvolvedores que querem seus próprios recursos de LLM on-device. O contrato entre apps (aquele que a Apple Intelligence e o Siri usam para encontrar seu app) passa pelos App Intents.

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

Um app sem um App Intent relevante não é alcançável por um comando de voz do Siri em sua categoria. A Apple Intelligence roteia frases como “Hey Siri, log my water” 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 primeiros movedores. A mesma lógica se aplica a listas de compras, registro de treinos, entradas de calendário, buscas em fotos. Espero que a vantagem de primeiro movedor nas declarações de intent se componha da forma como aconteceu com outras APIs de aposta de plataforma da Apple (categorias do HealthKit, resultados ricos do Spotlight, tokens de Live Activities).

A personalização da Apple Intelligence lê dos App Entities, não apenas dos 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 pesquisa todo AppEntity que casa com Book em todo app instalado. 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 pode recuperar nem referenciar seus dados.¹¹

A forma de retorno IntentResult & ProvidesDialog está cada vez mais importante. A Apple Intelligence está compondo resultados de intent em respostas mais longas no Siri, Spotlight e 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; são como sua ação se torna uma citação na superfície de IA do usuário.

O que eu faria 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 do Siri que os usuários realmente tentam (“quanta água eu tomei hoje” foi roteada para a IA genérica da Apple em vez de para os dados do meu app). Cada intent ausente é uma consulta que a Apple Intelligence contorna em vez de me chamar.

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 via CarPlay ou AirPods precisa de uma estrutura curta, concreta e factual: “8 oz logged. 32 oz to go.” A superfície do Watch em particular trunca agressivamente. Diálogo conversacional é uma experiência pior do que diálogo confiante e factual. 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())")
    }
    @Property(title: "Amount") var amount: Int
    @Property(title: "Timestamp") 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 do fetch do SwiftData. Para tornar entradas individualmente exibíveis no Spotlight (de modo que usuários buscando “água” cheguem na entrada certa), conforme a entidade a IndexedEntity e doe atualizações de índice nas escritas. É isso que o pipeline de Spotlight da Apple espera além da exposição básica de AppEntity.

A mesma forma se aplica em outros lugares dos meus apps. O Get Bananas, meu app de lista de compras, já tem um @Model ShoppingItem no SwiftData com @Attribute(.unique) var id: UUID, name, amount, section, isChecked, mais um campo lastModified para sincronização via iCloud Drive.¹³ Encapsulá-lo como ShoppingItemEntity: AppEntity e lançar alguns 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 dos contratos paralelos como um único app lançado: o modelo SwiftData são os dados, 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 faz parte do design.

Se seu app é puramente impulsionado por consumo (lendo as fotos do usuário, exibindo notícias, tocando áudio) sem estado mutável de usuário, App Intents podem não ter nada a expor. O framework da Apple suporta OpenIntent (apenas abrir 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 multietapa complexa, um app de edição 3D), o parameterSummary exigido do intent vai degradar para um pseudo-natural-vago que ninguém realmente diz. A frase no Siri “edite minha foto com a ferramenta blur na intensidade 7” é tecnicamente possível, mas nenhum humano vai pronunciá-la. A superfície do intent vira um imposto sem retorno.

A regra certa: um App Intent justifica seu lugar quando existe uma frase que um usuário diria naturalmente que dispara a ação. “Log 8 oz of water” é 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 leitura final

Por três anos a Apple vem sinalizando que a malha 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. Todo sinal aponta na 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 sobrar tempo. Minha leitura é que esse enquadramento vai envelhecer mal. À medida que as superfícies de sistema da Apple Intelligence se estendem (já hoje através de Siri, Spotlight, Shortcuts e resumos da Apple Intelligence), apps sem intents declarados provavelmente vão se encontrar fora do grafo de roteamento. A superfície do primeiro movedor, na minha experiência observando outras apostas de plataforma da Apple, se compõe.

O Water tem LogWaterIntent lançado há onze semanas. A quantidade de código que lança um App Intent é pequena o bastante 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 ao 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 às superfícies de IA do sistema da Apple. Ele declara parâmetros via @Parameter, um resumo em linguagem natural via parameterSummary, e um corpo perform() assíncrono que faz 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 antigo INIntent?

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

Eu 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 implantação depende do que seu corpo perform() importa. App Intents puros funcionam até o iOS 16; os com SwiftData precisam de 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 entidade. A Apple Intelligence usa ambos: intents para tomar ações, entidades para recuperar e referenciar dados nas 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 a superfície canônica entre apps que Apple Intelligence, Siri e Spotlight chamam. Mesma direção (uso de ferramentas tipado e declarativo); dois contratos paralelos. Um app que quer ser alcançável por 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. São o contrato. O app que lança o intent primeiro fica com 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. A composição já começou.

Mais da série Apple Ecosystem

Este texto é o ponto de entrada. Os outros quatro cobrem o resto da pilha de arquitetura:

• Two Agent Ecosystems, One Shopping List: como o Get Bananas expõe os mesmos dados à Apple Intelligence (App Intents) e ao Claude Desktop (MCP) através de um arquivo JSON no iCloud Drive.
• Liquid Glass in SwiftUI: Three Patterns From Shipping Return: padrões de produção para a camada visual do iOS 26.
• Five Apple Platforms, Three Shared Files: a estratégia de envio multiplataforma, quando compartilhar código e quando bifurcar targets.
• HealthKit + SwiftUI on iOS 26: a camada de fonte de dados de fluxos de autorização, tipos de amostra e a armadilha que tranca os usuários para fora do seu app.

Ou pule para o hub completo: Apple Ecosystem Series. Para o contexto mais amplo de iOS com agentes de IA, veja o iOS Agent Development guide.

Referências