Três superfícies: humano, Apple Intelligence, agente

Toda funcionalidade significativa em um app iOS no iOS 26+ agora enfrenta até três superfícies a partir das quais pode ser invocada. A mesma função Swift que registra um copo de água pode ser acionada por um humano tocando em um botão, pelo Apple Intelligence roteando uma solicitação do Siri, ou por um agente externo (Claude Code, Cursor, ChatGPT) chamando uma ferramenta MCP. Três chamadores diferentes, três obrigações diferentes, três superfícies de renderização diferentes. A funcionalidade é a mesma; as superfícies, não.

Muitos erros de arquitetura iOS vêm de projetar para uma superfície e depois encaixar à força a funcionalidade nas outras. Fluxos de UI vazam para respostas do Siri; ferramentas de agente que são corretas para um desenvolvedor se tornam riscos para usuários finais; recursos de LLM no dispositivo presumem contexto de nível cloud. O cluster vem mapeando essas superfícies em posts individuais. O post atual é a síntese: as três superfícies, suas diferenças, a regra de roteamento, e como a camada de domínio de um app precisa ser estruturada para servir as três sem comprometer nenhuma.

O modelo mental: escolha uma funcionalidade de domínio. Pergunte qual das três superfícies deveria poder invocá-la. Pergunte qual pode. Pergunte do que cada superfície precisa da funcionalidade e o que a funcionalidade deve em troca. As respostas moldam a arquitetura.

TL;DR

• Três superfícies: humana (views SwiftUI, toques, gestos, tela), Apple Intelligence (App Intents, Siri, Shortcuts, Spotlight), agente (servidores MCP, hosts LLM externos).
• Cada superfície tem obrigações diferentes: postura de confiança, orçamento de latência, local de renderização, semântica de persistência, tratamento de erros, requisitos de acessibilidade.
• A arquitetura correta é uma camada de domínio abaixo das superfícies. Cada superfície é um adaptador fino sobre as mesmas funções Swift; a função recebe um argumento Caller tipado para que possa ramificar em regras transversais às superfícies (rate limits, auditoria, confirmações) sem conhecer detalhes de protocolo da superfície.
• Nem toda funcionalidade serve às três superfícies. A decisão de qual superfície é uma escolha de design. Esconder funcionalidades das superfícies que não deveriam tê-las é uma decisão de produto tanto quanto expô-las às superfícies que deveriam.

Superfície um: humana

A superfície humana é a tela. O usuário olha para o app, toca, rola, arrasta, desliza, digita. O framework é SwiftUI (ou UIKit, ou para algumas cargas de trabalho, RealityKit no visionOS). A renderização acontece no dispositivo do usuário, no processo do app, contra o esquema de cores, tamanho de Dynamic Type e configurações de acessibilidade escolhidos pelo usuário.¹

Do que a superfície humana precisa de uma funcionalidade:

• Um affordance visual. Um botão, uma linha de lista, um gesto de deslizar, um menu contextual. A funcionalidade tem que ser descobrível através da navegação do app e estilizada de forma consistente com o resto da UI.
• Feedback em tempo real. Toda interação precisa de uma resposta visível imediata. Um botão que dispara uma operação longa tem que mostrar um indicador de progresso, um estado habilitado/desabilitado, uma animação.
• Acessibilidade. Rótulos de VoiceOver, suporte a Dynamic Type, contraste de cores, alternativas de controle motor. A superfície humana é a que tem os requisitos de acessibilidade mais exigentes porque o usuário está interagindo diretamente com a renderização.
• Visibilidade de erros. Erros aparecem na view do usuário. Um salvamento falho mostra um alerta; um timeout de rede mostra uma opção de tentar novamente; uma negação de permissão mostra um link para configurações.

O que a superfície humana deve em troca à funcionalidade:

• Intenção do usuário inequívoca. O usuário tocou em um botão específico; a funcionalidade sabe exatamente o que foi solicitado. Não há camada de inferência.
• Orçamento de latência apertado. Um toque que demora mais que algumas centenas de milissegundos para responder visivelmente parece quebrado. A funcionalidade tem que ser ou rápida ou projetada para mostrar progresso imediatamente.
• Nenhuma autoridade externa. O usuário está no app; o usuário é o agente no sentido mais amplo (o humano é quem está dirigindo a ação). Nenhum LLM de terceiros, nenhum agente do sistema, apenas as mãos do usuário.

A superfície humana é a mais antiga das três. Todo framework iOS, padrão de design e regra de acessibilidade que a plataforma acumulou desde o iOS 7 está a serviço dessa superfície. As outras duas superfícies são recentes o suficiente para que os padrões ainda estejam se assentando.

Superfície dois: Apple Intelligence

A superfície Apple Intelligence é o agente do sistema. Siri, Shortcuts, Spotlight, a pilha de sugestões do sistema. O usuário fala, digita no Spotlight ou encadeia uma ação no Shortcuts; o sistema roteia a solicitação através do framework App Intents, encontra um AppIntent que corresponde, resolve os parâmetros e executa o corpo perform() do intent. O framework é App Intents.²

Do que a superfície Apple Intelligence precisa de uma funcionalidade:

• Um schema tipado. Tipos AppIntent declaram propriedades @Parameter; tipos AppEntity fornecem identidade persistente para coisas sobre as quais o sistema pode falar; tipos AppEnum nomeiam conjuntos fechados de opções. O sistema lê o schema no momento da instalação.
• Identidade que sobrevive ao processo do app. Um registro de água que o usuário fez via Siri ontem deveria ser referenciável via Siri hoje. O modelo AppEntity dá ao sistema uma forma estável de falar sobre objetos entre sessões.
• Tratamento silencioso de erros. Erros não aparecem na view do usuário; aparecem em uma resposta do Siri, em uma saída de Shortcuts, ou em um resultado do Spotlight. O formato de erro que o sistema espera é estruturado (AppIntentError da Apple mais throws conformes a LocalizedError), não visual.
• Idempotência sob nova tentativa. O sistema pode reinvocar um intent durante uma cadeia de Shortcut ou após uma falha parcial. Funcionalidades que mutam estado precisam ser seguras sob chamadas repetidas ou expor uma semântica clara de “já feito”.

O que a superfície Apple Intelligence deve em troca à funcionalidade:

• A identidade real do usuário. O sistema sabe quem é o usuário, autenticou-o via SO e executa o intent no contexto dele. A funcionalidade não precisa verificar identidade além do que o SO fornece.
• Renderização em nível de sistema. O resultado que o intent retorna é formatado pelo sistema no chrome apropriado (banner da Tela Bloqueada, cartão de resposta do Siri, saída de Shortcuts). O app não controla como a resposta é apresentada.
• Descoberta sem que seu código esteja rodando. App Intents podem ser invocados quando seu app não está em execução. O sistema lê o schema e expõe a funcionalidade proativamente.

A postura de confiança: o Apple Intelligence é o agente de primeira parte da Apple. O usuário não o configurou; o sistema sim. O usuário confia no SO; o SO confia no schema de App Intents que seu app entregou através da revisão. A cadeia de confiança é SO → app. App Intents suportam requestConfirmation(...) e confirmações em modo foreground, então funcionalidades que precisam de um “tem certeza?” podem tecnicamente viver lá; o julgamento de produto, não a restrição de plataforma, é se confirmações de alto risco pertencem dentro de uma interação com o Siri ou na própria tela do app. Qualquer coisa irreversível (exclusão de conta, edições em massa destrutivas, pagamento) geralmente é mais segura na superfície humana, mesmo que App Intents possam solicitar confirmação.³

Superfície três: agente

A superfície de agente é todo outro sistema movido por LLM que quer operar o domínio do app. Claude Desktop, Claude Code, Cursor, o app desktop do ChatGPT, Codex CLI, harnesses de agentes customizados. O framework é o Model Context Protocol: um servidor MCP expõe o domínio do app através de métodos tools/call JSON-RPC; o host LLM descobre ferramentas no início da sessão e as chama por nome com um payload JSON.⁴

Do que a superfície de agente precisa de uma funcionalidade:

• Um contrato JSON-RPC. Nome da ferramenta, descrição, inputSchema, outputSchema opcional. O agente lê a descrição para decidir se chama; segue o schema para formatar argumentos.
• Uma descrição útil. O modelo decide quando usar a ferramenta com base em sua descrição. Trate a descrição como uma docstring que você espera que outro desenvolvedor (o modelo) leia. Descrições vagas produzem seleção errada de ferramentas.
• Erros com duas formas. Erros de execução de ferramenta retornam como um bloco de conteúdo mais isError: true no resultado da ferramenta que o modelo lê. Erros de nível de protocolo (requisição malformada, ferramenta ausente, falha de transporte) retornam como respostas error JSON-RPC padrão que o host trata. O autor da ferramenta detém o primeiro; o protocolo detém o segundo.
• Semântica sem estado ou com estado explícito. MCP tem estado na camada de protocolo (ciclo de vida da sessão, IDs de sessão em Streamable HTTP), mas a identidade durável de domínio é responsabilidade do lado do servidor, não uma garantia de nível de protocolo. Se o mesmo identificador deve significar a mesma coisa entre sessões, o servidor tem que impor isso.

O que a superfície de agente deve em troca à funcionalidade:

• A autenticação do host, não a do usuário. A confiança vem de quem implantou o servidor MCP. Stdio local do desenvolvedor: as próprias permissões de sistema de arquivos do desenvolvedor. HTTP acessível pela internet: qualquer auth que o servidor imponha. A funcionalidade tem que assumir que a reivindicação de identidade é o que o servidor lhe deu.
• Tolerância a latência variável. O host pode esperar mais que a superfície humana ou a superfície Apple Intelligence. Uma chamada de ferramenta que leva trinta segundos é aceitável na superfície de agente e inaceitável nas outras.
• Nenhuma superfície de renderização. O resultado é texto ou dados estruturados que o modelo interpreta. Nenhum chrome, nenhuma UI, nenhuma formatação do sistema.

A postura de confiança: o servidor MCP é o contrato do desenvolvedor sobre quem pode chamá-lo. Duas implantações do mesmo servidor (stdio local para desenvolvimento, HTTP via internet para usuários finais) têm posturas de confiança muito diferentes e precisam de guardrails muito diferentes. O protocolo é o mesmo; a implantação é a arquitetura. Coberto em detalhes em App Intents vs MCP: a questão do roteamento e Quando o LLM vive no seu app vs no seu tooling.⁵

Os seis eixos em que as superfícies discordam

Trazer as três superfícies para uma tabela de comparação torna as decisões de arquitetura concretas:

As discordâncias se compõem. Uma funcionalidade projetada para a superfície humana presume latência apertada, renderização rica, erros gerenciados pelo app. Encaixá-la à força através do Apple Intelligence perde o controle de renderização e adiciona identidade mediada pelo SO. Encaixá-la à força através da superfície de agente perde a renderização inteiramente e desloca o limite de confiança para quem implantou o servidor. A funcionalidade tem que ser remodelada, não apenas reembrulhada.

A regra arquitetural: camada de domínio abaixo das superfícies

O padrão que sobrevive nas três superfícies é uma camada de domínio abaixo delas. A camada de domínio é composta por funções Swift comuns: entradas tipadas, saídas tipadas, nenhuma suposição de protocolo. Cada superfície é um adaptador fino sobre o domínio. A mesma função logWater(amount:caller:) sustenta o botão SwiftUI, o perform() do App Intent e o handler da ferramenta MCP.

O esboço (uma versão de produção real faria WaterEntry conformar a AppEntity para o retorno do App Intent, injetaria domain como dependência em vez de uma referência de nível superior, e adicionaria a static var title obrigatória no intent):

// Domain layer (the actual capability)
func logWater(amount: Measurement<UnitVolume>, at: Date, caller: Caller) throws -> WaterEntry {
    try guards.requireWritePermission(caller)
    let entry = WaterEntry(amount: amount, timestamp: at)
    try store.insert(entry)
    return entry
}

// Adapter A: human surface (SwiftUI button)
Button("Log 250ml") {
    Task {
        let entry = try await domain.logWater(
            amount: .init(value: 250, unit: .milliliters),
            at: .now,
            caller: .human
        )
        // Update view state, show confirmation animation, etc.
    }
}

// Adapter B: Apple Intelligence surface (AppIntent)
struct LogWaterIntent: AppIntent {
    static var title: LocalizedStringResource = "Log Water"
    @Parameter(title: "Amount") var amount: Measurement<UnitVolume>
    func perform() async throws -> some IntentResult & ReturnsValue<WaterEntry> {
        let entry = try domain.logWater(amount: amount, at: .now, caller: .siri)
        return .result(value: entry)  // WaterEntry conforms to AppEntity
    }
}

// Adapter C: agent surface (MCP tool handler)
let entry = try domain.logWater(
    amount: .init(value: ml, unit: .milliliters),
    at: .now,
    caller: .mcp(host: hostName)
)
return .text("Logged \(entry.amount) at \(entry.timestamp)")

Três chamadores. Uma função de domínio. A função de domínio recebe um parâmetro Caller para poder impor regras diferentes por superfície (rate limits, log de auditoria, requisitos de confirmação) sem que cada superfície tenha que reimplementá-las. Os adaptadores são burros; o domínio é inteligente.

A forma generaliza o padrão de adaptador duplo de App Intents vs MCP; adicionar a superfície humana como uma terceira classe de chamador é a extensão natural. O LLM Foundation Models no dispositivo, quando usado dentro do app, fica na superfície humana (o usuário invocou um recurso no app que por acaso chama o modelo); o LLM em runtime não é uma quarta superfície, é uma forma de executar funcionalidades que já pertencem à superfície humana.⁶

Nem toda funcionalidade serve às três superfícies

Exposição igualitária não é o objetivo. Funcionalidades diferentes pertencem a superfícies diferentes.

Funcionalidades que geralmente deveriam exigir presença humana em foreground. Captura de fotos, autenticação biométrica, entrada de PII sensível, confirmação de pagamento, exclusão de conta. O humano tem que estar olhando para a tela, tem que consentir, tem que se autenticar. O Apple Intelligence pode tecnicamente trazer o app para foreground e solicitar confirmação; a superfície de agente não tem garantia de presença equivalente. O julgamento de produto é que essas funcionalidades devem rodar como UI em foreground com ação deliberada explícita, não como uma chamada silenciosa do Siri ou de ferramenta em background.

Funcionalidades que deveriam viver nas superfícies humana + Apple Intelligence. A maioria das ações voltadas ao usuário. Registrar água, iniciar uma meditação, adicionar um item à lista, me mostre meus registros de terça. O usuário pode tocar em um botão ou pode dizer “E aí, Siri.” Ambas as superfícies são válidas; ambas devem alcançar a mesma função de domínio.

Funcionalidades que deveriam viver em todas as três superfícies. Integrações entre processos. Uma lista de compras compartilhada entre o iPhone do usuário e uma sessão do Claude Code que importa receitas. A superfície humana detém o uso do dia a dia; a superfície Apple Intelligence detém o alcance via Siri/Spotlight; a superfície de agente detém o fluxo externo dirigido por desenvolvedor ou usuário.

Funcionalidades que deveriam viver apenas na superfície de agente. Importações em massa de desenvolvedor ou admin sem um fluxo de revisão para usuário final, integrações com sistemas externos, fluxos orquestrados por agentes que não têm expressão no Siri ou no app. Importar em massa 500 registros históricos do CSV de um desenvolvedor durante um backfill único. Importações de arquivo por usuário final geralmente têm um fluxo na superfície humana (Shortcuts pode passar arquivos; um importador no app pode dividir o progresso); o caso somente-agente é o fluxo de trabalho que genuinamente não tem lugar em nenhuma das outras duas superfícies.

A decisão é o design. Listar as superfícies que uma funcionalidade não serve é tão importante quanto listar aquelas que serve.

O que eu construiria diferente

Dois padrões que os apps do cluster ou entregam ou gostariam de ter entregado.

Faça Caller um tipo de primeira classe na camada de domínio. Toda função pública de domínio recebe um argumento Caller. O tipo codifica qual superfície invocou a chamada (.human, .siri, .mcp(host:)). A lógica de domínio se ramifica nele para prompts de confirmação, rate limits, log de auditoria e gates de ações sensíveis. A alternativa (cada superfície reimplementando as regras) deriva; a versão centralizada permanece consistente.

Trate cobertura de superfície como um checklist explícito. Ao adicionar uma funcionalidade, o documento de design lista quais das três superfícies devem expô-la e quais devem recusar. A lista de recusa não é um padrão; é uma escolha deliberada. Recusada: superfície Apple Intelligence, porque a funcionalidade requer prova de atenção do usuário que o Siri não pode fornecer. O raciocínio fica registrado; a auditoria detecta deriva mais tarde.

O que o padrão significa para apps que entregam no iOS 26+

Três pontos principais.

1. Três superfícies, três posturas de confiança. Humana, Apple Intelligence, agente. Cada uma tem obrigações que as outras não têm. Projetar para uma e encaixar à força nas outras produz arquitetura ruim em todas as superfícies.

2. Domínio embaixo; adaptadores em cima. Uma função Swift por funcionalidade; adaptadores finos por superfície; a função recebe um parâmetro Caller para que possa impor regras específicas de superfície em um único lugar.

3. Nem toda funcionalidade serve às três. Esconder uma funcionalidade das superfícies que não deveriam tê-la é uma decisão de design tanto quanto expô-la. A lista de recusa merece seu lugar.

O cluster completo do Ecossistema Apple: App Intents tipados para a superfície Apple Intelligence; servidores MCP para a superfície de agente; a questão do roteamento entre eles; Foundation Models para recursos de LLM no dispositivo dentro da superfície humana; a distinção entre LLM em runtime vs em tooling; Live Activities para a máquina de estados da Tela Bloqueada do iOS; o contrato do runtime watchOS no Apple Watch; internos do SwiftUI para o substrato da superfície humana; o modelo mental espacial do RealityKit para cenas visionOS; disciplina de schema do SwiftData para persistência entre superfícies; padrões Liquid Glass para a camada visual humana; entrega multiplataforma para alcance entre dispositivos. O hub está na Série Ecossistema Apple. Para contexto mais amplo de iOS-com-agentes-LLM, veja o guia de Desenvolvimento de Agentes iOS.

FAQ

Quais são as três superfícies de um app iOS?

A superfície humana (views SwiftUI, toques, gestos, tela), a superfície Apple Intelligence (App Intents, Siri, Shortcuts, Spotlight), e a superfície de agente (servidores MCP expostos a hosts LLM externos como Claude Code, Cursor, ChatGPT). Cada uma tem sua própria identidade de chamador, orçamento de latência, local de renderização, semântica de persistência e postura de confiança. Uma funcionalidade que quer servir a mais de uma superfície deve ficar em uma camada de domínio abaixo de adaptadores finos por superfície.

Toda funcionalidade deveria ser exposta às três superfícies?

Não. Algumas funcionalidades estão corretamente limitadas a uma ou duas superfícies. Captura de fotos, autenticação biométrica e confirmações de ações sensíveis geralmente são melhores como fluxos de superfície humana em foreground porque os sinais de confiança (atenção do usuário, ação deliberada) estão presentes lá de forma mais confiável. Operações em massa dirigidas pelo desenvolvedor pertencem apenas à superfície de agente quando não existe fluxo de revisão para usuário final. A escolha de design é quais superfícies uma funcionalidade serve e quais ela recusa.

Qual é a diferença entre as superfícies Apple Intelligence e agente?

Apple Intelligence é o agente de primeira parte da Apple: o usuário invoca o Siri, Shortcuts, ou Spotlight; o sistema roteia através de App Intents. A confiança vem do SO. A superfície de agente é todo outro host LLM: desenvolvedores rodam Claude Code ou Cursor, usuários finais rodam Claude Desktop ou ChatGPT. A confiança vem de quem implantou o servidor MCP. App Intents são a superfície de protocolo para o primeiro; MCP é a superfície de protocolo para o segundo.

Onde se encaixa o LLM Foundation Models no dispositivo?

Dentro da superfície humana. Quando o usuário invoca um recurso no app que chama Foundation Models, o LLM em runtime é a implementação de uma funcionalidade da superfície humana, não uma quarta superfície. O LLM em runtime não tem chamador próprio do Siri ou de host externo. As ferramentas do Foundation Models são como o modelo no dispositivo lê/escreve o estado do domínio do app; o usuário é quem está dirigindo a chamada.

Como o padrão de camada de domínio simplifica código multissuperfície?

Centralizando as regras. Uma função Swift recebe um argumento Caller e impõe comportamento específico por superfície (prompts de confirmação, rate limits, log de auditoria) em um único lugar. Cada superfície é um adaptador fino (binding SwiftUI, AppIntent.perform, handler MCP) que traduz o protocolo da superfície para a função de domínio. Deriva entre superfícies se torna impossível porque há uma única fonte de verdade.

Referências