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

Na manhã de 8 de fevereiro de 2026, pedi à Siri que registrasse 8 oz de água a partir do meu Apple Watch enquanto minhas mãos estavam embaixo da pia da cozinha. A água foi registrada. A caixa de diálogo do relógio dizia 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 controle 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 superfície de API mais quente que possuo.²

Aqui está a parte que levei um tempo para internalizar. App Intents não são um recurso da Siri. Eles são o contrato que os apps de terceiros assinam com o Apple Intelligence, a IA do sistema que a Apple começou a lançar no iOS 18 e continuou construindo ao longo do iOS 26.³ Se você lança um app iOS e ainda trata os App Intents como um recurso de voz “bom de se ter”, você está interpretando mal o que a Apple construiu. App Intents são a API que permite à IA da Apple agir como o seu app em nome do usuário. Todo o resto (Siri, Spotlight, Shortcuts, resumos do 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 chamada 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 o seu app pode fazer de uma forma tipada e estruturada que a IA da Apple consegue 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 o HealthKit, conversão de unidades sensível à localidade, resposta de diálogo estruturada para a 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; os App Intents continuam sendo a superfície canônica que a Siri / o Spotlight / o Apple Intelligence chamam entre apps. Mesma direção, dois contratos paralelos.
• Um app sem App Intents em 2026 é invisível para o Apple Intelligence. A malha de IA roteia pelos seus intents declarados ou roteia em volta do seu app, até um concorrente.
• A Apple vem nos dizendo isso há três anos. A nomenclatura (App Intents, App Shortcuts, Apple Intelligence) é intencional. 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 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 ainda mais o diálogo com uma 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 a Siri interpreta “registre 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.⁵

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

O 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 espera cada vez mais ProvidesDialog, ProvidesView ou ReturnsValue para que o resultado se componha na Siri, no Spotlight, no Watch e (no iOS 26) na cadeia de resposta do Apple Intelligence.⁷

O bloco AppShortcutsProvider ao 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 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 o Spotlight, o Shortcuts e o Apple Intelligence renderizam o ícone da ação.

O Apple Intelligence roteia os pedidos do usuário através dos 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

As APIs do iOS vêm em dois formatos. Algumas são sobre como o seu app se desenha (UIKit, SwiftUI, Metal). Algumas são sobre como o seu app se integra ao sistema (URL schemes, Universal Links, widgets). App Intents são um terceiro formato: são como a IA da Apple usa o seu app. Aquelas superfícies de widgets e Control Center são, elas mesmas, superfícies de App Intents, o mesmo intent renderizado em muitos lugares, algo que eu detalho em A superfície de widgets do iOS 26.

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

• iOS 10 (2016) introduziu os 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 corridas) com schemas rígidos.⁸
• iOS 12 (2018) ampliou a superfície com os 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 os apps pudessem responder a invocações de atalho sem ir para segundo plano na 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 o Apple Intelligence e começou a rotear os pedidos da Siri pelos App Intents sempre que possível. O recurso de “contexto pessoal” do Apple Intelligence lê das App Entities (a versão de dados dos App Intents).¹⁰ O iOS 27 leva isso mais longe com os App Schemas, que permitem à Siri raciocinar sobre e agir nas suas entidades em termos que ela já entende, sem nenhuma frase de treinamento, abordado aqui.
• iOS 26 (2025) introduziu o framework Foundation Models, o LLM on-device da Apple. O Foundation Models expõe um protocolo Tool separado para chamada de ferramentas dentro do app. Os App Intents continuam sendo a superfície canônica entre apps para o Apple Intelligence, enquanto o Tool é a superfície dentro do app para chamadas diretas ao LLM. Os dois contratos rodam em paralelo.⁴

O contrato vem se estendendo pela pilha a cada lançamento. Originalmente, o consumidor de um App Intent era uma pessoa tocando no Shortcuts. Depois a voz da Siri. Depois o Spotlight. Depois os resumos do Apple Intelligence. Agora as superfícies de sistema do Apple Intelligence apoiadas em LLM os usam para agir nos pedidos do usuário. A superfície de App Intent que você lança em 2026 é a que o Apple Intelligence 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 da Siri. Eles são a API de uso estruturado de ferramentas de toda a malha de IA da Apple. O SwiftUI foi a API de UI mais importante porque se tornou a única forma de escrever um app para visionOS, watchOS 10+ e iOS 17+. Os 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 chega em todo dispositivo elegível ao Apple Intelligence. O corte de hardware é a mesma lista do 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 mais recente, iPad Air com M1 ou mais recente, iPad mini com A17 Pro, Vision Pro com M2 ou mais recente, e Mac com M1 ou mais recente. Notavelmente ausentes: iPhone 15 / 15 Plus base.⁴¹²

A implicação: se as superfícies de sistema da Apple (Siri, Spotlight, Apple Intelligence) chamam o seu app, elas o chamam através dos App Intents e das App Entities. Não há uma API setSystemPrompt(...) para apps de terceiros na malha 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 (aquele que o Apple Intelligence e a Siri usam para encontrar o seu app) roda pelos App Intents.

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

Um app sem um App Intent relevante não é alcançável por um comando de voz da Siri na sua categoria. O Apple Intelligence roteia frases como “E aí, Siri, registre minha água” para os 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 favor dos 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 de pioneirismo nas declarações de intent se componha da mesma forma que aconteceu com outras APIs de aposta de plataforma da Apple (categorias do HealthKit, resultados ricos do Spotlight, tokens de Live Activities).

A personalização do Apple Intelligence lê das App Entities, não apenas dos intents. Uma AppEntity declara “este app tem dados deste formato”. Quando o usuário pergunta “qual foi o último livro que adicionei à minha lista de leitura”, o Apple Intelligence busca em toda AppEntity que casa com Book em todo app instalado. Se o seu app tem uma lista de leitura e nenhuma BookEntity declarada, seus dados são invisíveis para as superfícies de IA da Apple. O Apple Intelligence não consegue recuperar nem referenciar seus dados.¹¹

O formato de retorno IntentResult & ProvidesDialog é cada vez mais importante. O Apple Intelligence está compondo os resultados de intent em respostas mais longas na Siri, no Spotlight e no 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 gentileza opcional; são como a 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 mais cedo.

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 já bebi hoje” roteado para a IA genérica da Apple em vez de para os dados do meu app). Cada intent que falta é uma consulta que o Apple Intelligence roteia em volta de mim.

A string de diálogo não é o corpo de um e-mail. Eu tinha ProvidesDialog desde o começo, mas meu diálogo inicial era prosa. O usuário que a ouve pelo CarPlay ou pelos AirPods precisa de uma estrutura curta, concreta, liderada por fatos: “8 oz registradas. Faltam 32 oz.” A superfície do Watch, em particular, trunca de forma agressiva. Um diálogo conversacional é uma experiência pior do que um diálogo confiante e factual. Reescrevi o meu na semana 4.²

As App Entities importam mais do que eu pensava. Tenho um modelo SwiftData WaterEntry. Eu também deveria declarar uma WaterEntryEntity: AppEntity mais sua companheira WaterEntryQuery: EntityQuery para que o Apple Intelligence possa responder “me 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 de fetch do SwiftData. Para tornar as entradas individualmente expostas no Spotlight (para que usuários buscando “água” cheguem à entrada certa), faça a entidade conformar com IndexedEntity e doe atualizações de índice nas escritas. É isso que o pipeline do Spotlight da Apple espera, além da mera exposição de AppEntity.

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

Quando não lançar um App Intent

A recusa faz parte do design.

Se o seu app é puramente orientado a consumo (lendo as fotos do usuário, exibindo notícias, tocando áudio) sem nenhum estado mutável do usuário, os 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 é puro custo. Não lance um só para ter um.

Se a ação depende de elementos de UI difíceis de abstrair (uma ferramenta de canvas complexa com várias etapas, um app de edição 3D), o parameterSummary exigido pelo intent degenerará em uma pseudo-linguagem-natural vaga que ninguém de fato diz. A frase da Siri “edite minha foto com a ferramenta de desfoque na intensidade 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 o que custa quando existe uma frase que um usuário diria naturalmente e que dispara a ação. “Registre 8 oz de água” é essa frase. “Aplique desfoque gaussiano com sigma 2,4 na camada 3” não é. Se as ações do seu app se agrupam no segundo padrão, os intents não são a sua alavanca de conversão.

A conclusão

Por três anos a Apple vem sinalizando que a malha de IA de sistema do iOS passa pelos App Intents. A WWDC 2024 adicionou o roteamento do 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 a Siri / o Spotlight / o Apple Intelligence continuam usando. Todo sinal aponta na mesma direção: o App Intent tipado e declarativo é o contrato que os apps de terceiros agora assinam com o sistema.

A maioria dos apps iOS ainda trata os 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 do Apple Intelligence se estendem (já hoje pela Siri, pelo Spotlight, pelo Shortcuts e pelos resumos do Apple Intelligence), apps sem intents declarados provavelmente vão se encontrar fora do grafo de roteamento. A superfície de pioneirismo, pela minha experiência observando as outras apostas de plataforma da Apple, se compõe.

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 lançamento do Apple Intelligence.

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

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 de sistema da Apple. Ela 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. A Siri, o Spotlight, o Shortcuts e o 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 os App Intents diferem do antigo INIntent?

Os App Intents (introduzidos no iOS 16, 2022) substituíram o INIntent como o framework de intents primário 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 a Siri, o Spotlight, o Shortcuts e o Apple Intelligence chamam. O antigo INIntent ainda é suportado, mas não recebe nenhum trabalho de novos recursos.

Eu preciso do iOS 26 para lançar um App Intent?

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

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

Um App Intent é uma ação (verbo). Uma App Entity é o dado que o seu app conhece (substantivo). LogWaterIntent é um intent. WaterEntry virando um tipo consultável é uma entity. O Apple Intelligence usa ambos: os intents para tomar ações, as entities para recuperar e referenciar dados nas respostas.

Como os App Intents se relacionam com a chamada 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. Os App Intents continuam sendo a superfície canônica entre apps que o Apple Intelligence, a Siri e o Spotlight chamam. Mesma direção (uso de ferramentas tipado e declarativo); dois contratos paralelos. Um app que quer ser alcançável pelas superfícies de IA de sistema lança App Intents; um app que quer chamar seu próprio LLM on-device com ferramentas customizadas lança conformações 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 fica com a superfície; o app que o 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 ensaio é o ponto de entrada. Os outros quatro cobrem o resto da pilha de arquitetura:

• Dois ecossistemas de agentes, uma lista de compras: como o Get Bananas expõe os mesmos dados para o Apple Intelligence (App Intents) e para o Claude Desktop (MCP) através de um arquivo JSON no iCloud Drive.
• Liquid Glass no SwiftUI: três padrões de lançar o Return: padrões de produção para a camada visual do iOS 26.
• Cinco plataformas Apple, três arquivos compartilhados: a estratégia de lançamento multiplataforma, quando compartilhar código e quando bifurcar targets.
• HealthKit + SwiftUI no iOS 26: a camada de fonte de dados dos 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: Série Apple Ecosystem. Para o contexto mais amplo de iOS-com-agentes-de-IA, veja o guia de desenvolvimento de agentes iOS.

Referências