App Intents 2.0 no iOS 26: Visual Intelligence, snippets interativos e propriedades adiadas

App Intents foi lançado no iOS 16 como a API de ações estruturadas da Apple para Atalhos, Siri e Spotlight; o iOS 17 expandiu o framework para widgets baseados em App Intents; o iOS 18 o tornou o contrato para a superfície de ações da Apple Intelligence. O iOS 26 estende App Intents para Visual Intelligence (resultados de busca por imagem de apps de terceiros), snippets interativos (pequenas janelas pop-up de UI que se compõem em contextos do sistema), anotações de visualização de entidades (como uma entidade é renderizada inline) e @DeferredProperty (propriedades de entidade computadas de forma assíncrona)¹. As extensões não mudam o modelo central de App Intents; elas adicionam novas superfícies de participação que um app pode adotar.

O post percorre as adições do iOS 26 com base na documentação da Apple. O enfoque é “quais novas superfícies uma adoção existente de App Intents ganha ao adicionar as conformidades do iOS 26”, porque a maioria dos apps com App Intents já tem os tipos fundamentais implementados, e o trabalho do iOS 26 trata de estender esses tipos para novos contextos.

TL;DR

• IntentValueQuery é o novo protocolo para integração com Visual Intelligence. A query aceita um SemanticContentDescriptor (o contexto visual do usuário) e retorna um array de instâncias de AppEntity que o app considera relevantes².
• @DeferredProperty declara uma propriedade de entidade cujo valor é computado de forma assíncrona. A propriedade é carregada quando o sistema realmente precisa dela, evitando custo antecipado para entidades com muitos campos baratos de exibir + alguns caros de computar.
• Snippets interativos de App Intents permitem que um app apresente uma pequena janela pop-up (com botões, texto, controles) dentro de contextos do sistema como Spotlight, Visual Intelligence ou a superfície de resposta da Siri. O snippet é uma view SwiftUI vinculada ao resultado do App Intent.
• Anotações de visualização de entidades permitem que um app declare como uma AppEntity deve ser renderizada em diferentes contextos do sistema (uma linha compacta no Spotlight, um cartão de destaque no Visual Intelligence, um widget no estilo Live Activity).
• O post App Intents do cluster cobriu o modelo fundamental; este post o estende para as novas superfícies de participação do iOS 26. O post App Intents vs MCP Tools do cluster cobre a questão de roteamento entre a superfície de intent da Apple Intelligence e as ferramentas MCP de agentes gerais.

Visual Intelligence: IntentValueQuery e SemanticContentDescriptor

A adição estrela de App Intents do iOS 26 é a integração com Visual Intelligence². O fluxo:

1. O usuário tira uma foto, captura um screenshot ou aponta a câmera para um objeto.
2. A camada de Visual Intelligence do sistema extrai o contexto visual + semântico (o que está na imagem, o que o usuário pode querer sobre ela).
3. O sistema consulta cada app que registrou um IntentValueQuery com aquele contexto semântico.
4. Cada app retorna instâncias relevantes de AppEntity; o sistema agrega e apresenta na UI do Visual Intelligence.
5. O usuário toca em uma entidade para entrar no app de origem no contexto certo.

A superfície do desenvolvedor é uma struct conforme a IntentValueQuery com um método values(for:) que recebe um SemanticContentDescriptor:

import AppIntents

struct ProductLookupQuery: IntentValueQuery {
    func values(for descriptor: SemanticContentDescriptor) async throws -> [Product] {
        // descriptor.labels: detected category and content labels
        // descriptor.pixelBuffer: the visual content as a CVReadOnlyPixelBuffer
        //                        (use VideoToolbox/CoreImage to convert if needed)
        let candidates = try await catalog.search(labels: descriptor.labels)
        return candidates.map(Product.init)
    }
}

O SemanticContentDescriptor carrega dois campos que o sistema preenche: labels (um array de tags de categoria e conteúdo detectados, como “wine bottle”, “pinot noir”, “label text”, etc.) e pixelBuffer (os dados subjacentes da imagem como um CVReadOnlyPixelBuffer para apps que queiram rodar seus próprios modelos de visão sobre o conteúdo). O trabalho do app é mapear esses sinais para seus próprios dados e retornar as entidades correspondentes.

O padrão de adoção certo: um app de compras implementa a query contra seu catálogo de produtos (contexto visual → produtos correspondentes), um app de vinhos contra seu banco de garrafas (imagem do rótulo → registro do vinho), um app de receitas contra sua biblioteca de receitas (foto do ingrediente → receitas correspondentes).

@DeferredProperty: valores assíncronos de entidade

Tipos AppEntity existentes declaram suas propriedades de forma estática. Toda propriedade deve ser computada antes de a entidade ser retornada. Para entidades com propriedades de custo misto (título/subtítulo/imagem rápidos, descrição detalhada lenta vinda do servidor), a computação tudo-ou-nada é desperdício.

@DeferredProperty (iOS 26+) declara uma propriedade como computada de forma assíncrona³:

import AppIntents

struct Recipe: AppEntity {
    static var typeDisplayRepresentation = TypeDisplayRepresentation(...)
    static var defaultQuery = RecipeQuery()

    @Property(title: "Title")
    var title: String

    @Property(title: "Cuisine")
    var cuisine: String

    @DeferredProperty(title: "Detailed Instructions")
    var instructions: String {
        get async throws {
            try await loadInstructionsFromBackend(id: id)
        }
    }
}

O getter da propriedade adiada é assíncrono; ele só roda quando o sistema realmente precisa do valor (por exemplo, quando a entidade é selecionada para exibição de detalhes). Para entidades retornadas de uma query e usadas apenas para a UI de seleção, a propriedade adiada nunca é computada.

O padrão é certo para qualquer entidade com campos rápidos de construir (id, título, resumo) mais campos caros de construir (corpo completo, métricas computadas, dados buscados no servidor). Sem @DeferredProperty, o desenvolvedor ou computa tudo (desperdício) ou computa apenas os campos baratos e adiciona um intent separado de “carregar detalhe” (mais complexo).

Snippets interativos e SnippetIntent

O iOS 26 introduz o protocolo dedicado SnippetIntent para interações no formato de snippet, ao lado do padrão existente de AppIntent conforme a ShowsSnippetView de releases anteriores⁴. SnippetIntent adiciona um método estático reload() que o sistema pode chamar para atualizar o conteúdo do snippet sem uma reinvocação completa do intent:

struct WeatherSnippet: SnippetIntent {
    static var title: LocalizedStringResource = "Weather Snippet"

    @Parameter(title: "City")
    var city: City

    func perform() async throws -> some IntentResult & ShowsSnippetView {
        let forecast = try await weatherService.forecast(for: city)
        return .result(view: ForecastSnippet(forecast: forecast))
    }

    static func reload() async throws {
        // Triggered by the system when it wants fresh snippet data
        // (e.g., after the data source signals an update)
    }
}

Para intents não específicos de snippet que querem anexar uma view de snippet à sua resposta, o padrão existente de AppIntent + ShowsSnippetView continua funcionando:

struct WeatherForecastIntent: AppIntent {
    static var title: LocalizedStringResource = "Weather Forecast"

    @Parameter(title: "City")
    var city: City

    func perform() async throws -> some IntentResult & ProvidesDialog & ShowsSnippetView {
        let forecast = try await weatherService.forecast(for: city)

        return .result(
            dialog: "Here's the forecast for \(city.name).",
            view: ForecastSnippet(forecast: forecast)
        )
    }
}

struct ForecastSnippet: View {
    let forecast: Forecast
    var body: some View {
        VStack(alignment: .leading) {
            Text(forecast.headline).font(.headline)
            HStack {
                ForEach(forecast.days) { day in
                    DayCell(day: day)
                }
            }
            Button("Open in App") {
                // App-launching action wired via App Intents
            }
        }
        .padding()
    }
}

A conformidade ShowsSnippetView no tipo de resultado diz ao sistema para renderizar a view SwiftUI ao lado do diálogo. O snippet é interativo: botões dentro dele podem disparar outros App Intents, o usuário pode rolar, a view participa da camada de interação do sistema.

Os casos que justificam um snippet interativo: previsões do tempo, eventos de calendário, horários de transporte, placares esportivos, rastreamento de encomendas. Onde quer que o usuário queira mais do que uma resposta de diálogo de uma linha vinda da superfície do sistema.

Anotações de visualização de entidades

Anotações de visualização de entidades permitem que um app declare como uma AppEntity deve ser renderizada em diferentes contextos do sistema⁵. O mecanismo estende DisplayRepresentation com múltiplas variantes:

struct Recipe: AppEntity {
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(
            title: "\(title)",
            subtitle: "\(cuisine) - \(time) min",
            image: .init(named: imageName)
        )
    }
}

O modelo clássico retorna uma única DisplayRepresentation. O iOS 26 permite que entidades forneçam variantes específicas de contexto para o sistema escolher com base em onde está renderizando (lista compacta, cartão de destaque, resultado do Spotlight, painel do Visual Intelligence). O framework escolhe a variante certa por contexto; o app declara cada uma.

O padrão atende apps que precisam que a renderização de entidade difira entre, digamos, uma lista compacta do Spotlight e uma resposta de cartão único do Visual Intelligence. As variantes se compõem sem que o app precise detectar o contexto.

Composição com App Intents existentes

As adições do iOS 26 se compõem com as primitivas existentes de App Intents:

• O AppShortcutsProvider de um app (coberto em Acessibilidade como plataforma) registra atalhos para voz, action button e Spotlight.
• Cada AppShortcut referencia um AppIntent, que tem propriedades @Parameter resolvidas a partir da requisição do usuário.
• O método AppIntent.perform() retorna um tipo de resultado que pode incluir uma view de snippet (ShowsSnippetView) ou um diálogo (ProvidesDialog).
• Tipos AppEntity referenciados pelos parâmetros do intent agora suportam @DeferredProperty e anotações de visualização de entidades.
• Novos tipos IntentValueQuery permitem que as mesmas entidades apareçam no Visual Intelligence.

A forma: o modelo existente é preservado; o trabalho do iOS 26 é adicionar novos tipos (queries) e novas anotações (deferred, variantes de view) à mesma superfície de entidade.

Falhas comuns

Três padrões de falhas na adoção de App Intents 2.0:

IntentValueQuery retornando resultados sem escopo. Uma query que retorna todo produto correspondente aos termos de busca do descriptor, independentemente de relevância, dilui a experiência do Visual Intelligence. Correção: dê escopo à query (top-N por relevância, ponderado por recência, personalizado para o usuário) para que cada entidade retornada mereça seu lugar na UI do sistema.

@DeferredProperty para valores rápidos. O mecanismo deferred é para computação genuinamente cara. Marcar uma propriedade rápida em memória como deferida adiciona overhead assíncrono sem benefício. Correção: reserve @DeferredProperty para propriedades que de fato compensam quando adiadas (buscas no servidor, computações grandes, invocações de modelo de ML).

Snippets interativos que são apps inteiros. Um snippet é uma superfície de UI compacta; tratá-lo como um mini-app produz snippets que parecem apertados ou são lentos para renderizar. Correção: mantenha snippets focados na resposta imediata e em uma ou duas ações relacionadas; use o botão “Open in App” para passar fluxos complexos para o app completo.

O que esse padrão significa para apps iOS 26+

Três conclusões.

1. Adicione IntentValueQuery para qualquer app com conteúdo visual. Compras, receitas, produtos, locais, objetos identificáveis. A integração com Visual Intelligence é a nova superfície de descoberta; apps que não participam ficam invisíveis ali.

2. Use @DeferredProperty para campos caros de entidade. Descrições detalhadas, métricas computadas, dados buscados no servidor. O padrão async-por-padrão combina com código Swift moderno e mantém rápidos os retornos de entidade baratos de construir.

3. Adote snippets interativos para tipos de query de alto valor. Tempo, calendário, transporte, esportes, rastreamento de encomendas. A UI de snippet mantém os usuários na superfície de resposta do sistema para os casos em que um diálogo de uma linha não é suficiente, mas abrir o app inteiro é exagero.

O cluster Apple Ecosystem completo: App Intents tipados; servidores MCP; a questão de roteamento; Foundation Models; a distinção de runtime vs tooling LLM; três superfícies; o padrão single source of truth; Two MCP Servers; hooks para desenvolvimento Apple; Live Activities; o contrato de runtime do watchOS; internals do SwiftUI; o modelo mental espacial do RealityKit; disciplina de schema do SwiftData; padrões Liquid Glass; shipping multi-plataforma; a matriz de plataformas; Vision framework; Symbol Effects; Core ML inference; API de Writing Tools; Swift Testing; Privacy Manifest; Acessibilidade como plataforma; tipografia SF Pro; padrões espaciais visionOS; Speech framework; migrações SwiftData; focus engine do tvOS; internals do @Observable; protocolo Layout do SwiftUI; SF Symbols customizados; HDR no AVFoundation; ciclo de vida de workout no watchOS; sobre o que me recuso a escrever. O hub está em Apple Ecosystem Series. Para contexto mais amplo de iOS-com-agentes-de-IA, veja o guia de iOS Agent Development.

FAQ

Preciso de Apple Intelligence habilitado para testar IntentValueQuery?

Para testes completos de Visual Intelligence, sim. Visual Intelligence requer hardware compatível com Apple Intelligence (iPhone 15 Pro ou mais novo, Mac M1 ou mais novo) com iOS 26+ e Apple Intelligence habilitado. Para desenvolvimento, você pode testar a query em testes unitários construindo um SemanticContentDescriptor diretamente e chamando o método values(for:) da query sem a stack completa do sistema.

@DeferredProperty pode lançar exceções?

Sim. A assinatura do getter assíncrono é get async throws, e exceções se propagam para o sistema. O sistema lida com a falha exibindo a entidade sem o valor da propriedade adiada (ou mostrando um estado de erro em alguns contextos). Apps devem falhar graciosamente e retornar estados de erro significativos em vez de quebrar.

O conteúdo de snippet interativo suporta animações?

Sim, com as primitivas padrão de animação do SwiftUI. A view do snippet roda na superfície de resposta do sistema, que suporta a mesma infraestrutura de animação que o SwiftUI dentro do app. Vá ao post Symbol Effects do cluster para o vocabulário de animação que combina com as convenções da plataforma.

Como anotações de visualização de entidades interagem com widgets?

Widgets são uma superfície separada do WidgetKit; anotações de visualização de entidades se aplicam dentro de contextos de App Intents (Spotlight, Visual Intelligence, respostas da Siri). Para um app que expõe os mesmos dados como uma AppEntity e como um widget, as duas superfícies exigem declarações de UI separadas. Apps geralmente compartilham o modelo de dados subjacente e escrevem views finas de apresentação por superfície.

Qual é a relação disso com ferramentas MCP?

App Intents são a superfície de intent da Apple Intelligence; ferramentas MCP são o protocolo agente-servidor para LLMs gerais. O iOS 26 adiciona Visual Intelligence ao App Intents (a superfície da Apple). Para agentes não-Apple (Claude, classe GPT), ferramentas MCP rodando localmente ou remotamente cobrem o mesmo território conceitual. O post App Intents vs MCP Tools do cluster cobre a questão de roteamento.

IntentValueQuery pode ser combinado com EntityQuery?

Sim. Eles servem superfícies diferentes: EntityQuery é para quando o usuário digita ou fala um nome de entidade (Spotlight, Siri); IntentValueQuery é para quando o usuário está no Visual Intelligence com contexto de imagem. A AppEntity de um app pode ter ambas as queries registradas; o sistema escolhe a certa para o contexto.

Referências