Foundation Models LLM no Dispositivo: O Protocolo Tool

Gênero: frontier-essay. O post nomeia o contrato do LLM no dispositivo que a Apple lançou na WWDC 2025 e percorre a questão de roteamento: quando LanguageModelSession é a resposta certa, quando é AppIntent, quando é MCP, quando não é nenhum dos anteriores.

O iOS 26 entrega um modelo de linguagem de 3 bilhões de parâmetros em todo dispositivo compatível com Apple Intelligence.¹ A Apple chama o framework de Foundation Models. O framework é local. A inferência é otimizada para Apple silicon e roda no dispositivo; a rede não está no caminho da chamada. O modelo vive em SystemLanguageModel.default, seu app obtém uma LanguageModelSession, e a superfície tipada para deixar essa sessão fazer trabalho útil é o protocolo Tool.

O protocolo Tool é a parte que importa para desenvolvedores de apps. Sem ele, o LLM no dispositivo é um endpoint de chat completion sem conexão com os dados do seu app, com os dados do seu usuário, ou com o resto do sistema. Com ele, o modelo pode chamar funções Swift tipadas, receber resultados tipados de volta, e raciocinar sobre a resposta no próximo turno. A geração no dispositivo aumentada por tools é a capacidade real do framework. A superfície de chat é o demo.

TL;DR

• Foundation Models entrega a todo dispositivo elegível para Apple Intelligence um LLM de 3B de parâmetros em SystemLanguageModel.default. O modelo é local; a inferência é otimizada para Apple silicon e roda no dispositivo; a rede está fora do caminho da chamada.
• O protocolo Tool é o contrato entre o modelo e seu app. Uma tool declara Arguments tipados, retorna um Output tipado, e é vinculada a uma LanguageModelSession no momento da construção.
• As anotações Generable e Guide permitem que o modelo produza valores Swift tipados diretamente, não apenas strings. O decoder é parte do framework, não do seu código.
• A regra de roteamento entre Foundation Models, App Intents e MCP é quem roda o modelo e onde. Foundation Models = seu app roda o modelo no dispositivo. App Intents = Apple Intelligence roda o modelo no dispositivo e roteia para seu app. MCP = um host externo roda o modelo onde quiser e alcança seu app por meio de um servidor de tools.

O que o framework realmente fornece

Três primitivas sustentam o framework: o modelo, a sessão e a tool.²

SystemLanguageModel. Uma referência ao modelo fundacional no dispositivo. A instância default está vinculada ao dispositivo do usuário, disponível em hardware elegível para Apple Intelligence, e expõe verificações de capacidade que o app lê em tempo de execução para decidir se o modelo está disponível. O framework suporta configuração através de SystemLanguageModel(useCase:guardrails:), adapters customizados, e GenerationOptions, mas você não escolhe IDs arbitrários de modelos na nuvem como faria com OpenAI ou Anthropic; a Apple entrega e atualiza o modelo no dispositivo a cada release do OS, e o framework te entrega a versão que estiver instalada no momento.

LanguageModelSession. Um objeto com estado que mantém o estado da conversa entre chamadas. A sessão recebe um system prompt na construção, acumula turnos de usuário/assistente ao longo do tempo, e expõe métodos async para gerar respostas. Sessões são leves para criar e descartáveis; você cria uma por tarefa, não uma por app. Um timer de meditação cria uma sessão para “resumir meus últimos 7 dias de prática”; um app de receitas cria uma sessão diferente para “converter isto para duas pessoas em vez de quatro”.

Tool (o protocolo). Um protocolo Swift que declara um tipo Arguments, um tipo Output, e uma função async call(arguments:). Tools são vinculadas a uma sessão na construção (LanguageModelSession(tools: [...], instructions: ...)). Quando o modelo decide que precisa de uma tool, ele emite uma chamada estruturada; o framework decodifica os argumentos, executa a tool, codifica o resultado, e o devolve à sessão para o próximo turno. O modelo não vê Swift; o framework faz o marshalling.

A forma do protocolo Tool, condensada:

import FoundationModels

struct WaterEntryLookup: Tool {
    let name = "lookup_water_entries"
    let description = "Look up water intake entries for a given date range."

    @Generable
    struct Arguments {
        @Guide(description: "Start date in ISO-8601 format")
        let startDate: String

        @Guide(description: "End date in ISO-8601 format")
        let endDate: String
    }

    func call(arguments: Arguments) async throws -> ToolOutput {
        let entries = try store.entries(
            from: ISO8601DateFormatter().date(from: arguments.startDate) ?? .now,
            to: ISO8601DateFormatter().date(from: arguments.endDate) ?? .now
        )
        return ToolOutput(GeneratedContent(properties: [
            "count": entries.count,
            "total_ml": entries.reduce(0) { $0 + $1.amountMl }
        ]))
    }
}

O modelo vê uma descrição da tool e um esquema de argumentos no formato JSON. O código Swift vê entrada tipada e saída tipada. A fronteira de decode/encode é a parte que a Apple controla.

Generable e Guide: saída tipada sem parser

O mesmo sistema de anotações que torna os argumentos das tools tipados também permite que o modelo produza valores Swift tipados diretamente.³ Uma struct @Generable declara seu formato; o framework restringe a saída do modelo para corresponder.

@Generable
struct PracticeSummary {
    @Guide(description: "Single-sentence headline summarizing the user's week")
    let headline: String

    @Guide(description: "Total practice duration this week in minutes")
    let totalMinutes: Int

    @Guide(description: "Three short observations as bullet points")
    let observations: [String]
}

let session = LanguageModelSession(instructions: "You are a meditation coach.")
let summary = try await session.respond(
    to: "Summarize this week of practice given the entries.",
    generating: PracticeSummary.self
)

O modelo retorna um valor PracticeSummary. Sem parsing JSON no seu código, sem string-matching para “headline:”, sem fallback quando o modelo retornou um objeto malformado. O framework usa decodificação restrita para manter a saída token-a-token do modelo estruturalmente alinhada ao schema, então saída estruturalmente inválida não passa pela fronteira.

A superfície tipada em Swift é o que distingue o framework das SDKs de LLM na nuvem. SDKs na nuvem (OpenAI Structured Outputs, tool use do Anthropic, outras) também suportam decodificação restrita, mas o valor tipado que o desenvolvedor recebe é um objeto JSON validado contra um schema, e depois decodificado em um tipo Swift Codable como uma etapa separada. Foundation Models colapsa essas etapas: o macro @Generable e o decoder do framework produzem um valor Swift tipado como retorno direto, com as anotações @Guide por campo carregando a intenção para a restrição de geração. A saída é tipada porque a geração foi tipada contra o schema Swift, não contra uma especificação JSON que o desenvolvedor reconstruiu em Swift.

As anotações @Guide são como você comunica a intenção por campo ao modelo sem escrevê-la no prompt. A descrição gerada se torna parte da restrição de geração. Guides em nível de campo mantêm o prompt limpo e o schema próximo dos dados.

A questão do roteamento, em três caminhos

A Apple agora oferece três superfícies de protocolo que um app pode usar para expor seu domínio a um modelo de linguagem. Eles roteiam para runners diferentes.

Foundation Models (LanguageModelSession). Seu app carrega o modelo no dispositivo e roda a inferência. As tools que a sessão pode chamar são tools que o código do seu app define. O modelo nunca sai do dispositivo. O usuário não invoca isso através da Siri; o código do seu app invoca. O caso de uso é dentro do seu app: um app de meditação que usa o LLM para resumir uma semana, um app de receitas que adapta uma receita para menos porções, um water tracker que transforma “tomei um copo no almoço” em uma entrada estruturada.

App Intents. Apple Intelligence roda um LLM em nome do usuário (o agente first-party da Apple) e roteia chamadas de capacidade para os tipos AppIntent do seu app. Seu app não roda o modelo. Você declara ações tipadas através do framework App Intents, e a system stack da Apple decide quando invocá-las com base em pedido do usuário, query do Spotlight, entrada da Siri ou orquestração de Shortcuts. Coberto em detalhes em App Intents são a nova API da Apple para seu app.⁴

MCP. Um host externo (Claude Desktop, Claude Code, Cursor, ChatGPT) roda qualquer modelo que o desenvolvedor escolheu. Seu app expõe um servidor que o modelo do host pode chamar. O modelo roda onde quer que o host rode; chamadas de tool atravessam um transporte JSON-RPC. Coberto em Dois ecossistemas de agentes, uma lista de compras e a síntese da questão de roteamento em App Intents vs MCP.⁵

A decisão de roteamento se resume a quem é o agente.

                  ┌──────────────────────────────────┐
                  │  Who is the language model?       │
                  └────┬─────────────┬─────────────┬──┘
                       │             │             │
              ┌────────┴────┐ ┌──────┴──────┐ ┌────┴──────┐
              │ Your app's  │ │   Apple     │ │  External │
              │ own use of  │ │ Intelligence│ │   host's  │
              │   LLM       │ │   agent     │ │   agent   │
              └──────┬──────┘ └──────┬──────┘ └────┬──────┘
                     │               │             │
                     ▼               ▼             ▼
              Foundation Models  App Intents     MCP
              + Tool protocol   + AppEntity    + tools/list
              (on-device, your  (system runs   (host runs
               app runs model)   the model)     the model)

Um app de meditação resumindo a semana do usuário usa Foundation Models porque o próprio app quer chamar o modelo e apresentar um resultado dentro do app. A capacidade “registrar uma sessão de 5 minutos” do mesmo app usa App Intents para que a Siri possa invocá-la. A capacidade “mostre minhas últimas entradas de log de meditação” do mesmo app usada por uma sessão do Claude Code usa MCP. Três runners diferentes, três obrigações diferentes, uma camada de domínio compartilhada por baixo.

Orçamentos de inferência: o que o framework pede de você

Rodar um LLM no dispositivo não é grátis. O Apple silicon trata da inferência, mas o modelo ainda tem uma janela de contexto, um orçamento de tokens, e uma latência wall-clock que depende do dispositivo. Três restrições moldam como você projeta com o framework:⁶

A disponibilidade é por dispositivo. Nem todo dispositivo iOS 26 tem Apple Intelligence. iPhones antigos, dispositivos bloqueados, e dispositivos onde o usuário desabilitou Apple Intelligence retornam um estado de não-disponível em SystemLanguageModel.default.availability. Código que chama LanguageModelSession sem verificar disponibilidade gera um erro de geração em tempo de execução; o padrão correto é ramificar a UI no estado de disponibilidade antes da chamada e apresentar um caminho sem LLM quando o estado não estiver disponível. Trate o modelo como uma feature flag, não como uma garantia.

A latência não é trivial. A latência do primeiro token no iPhone 16 Pro é utilizável para interações dentro do app; gerações mais longas e cadeias de tool-calling não são instantâneas. Padrões de UI que funcionam para streaming de LLM na nuvem funcionam aqui também; não bloqueie a main thread, mostre saída progressiva, e projete para o caso em que o usuário sai da tela no meio da geração.

As janelas de contexto são menores do que na nuvem. O modelo no dispositivo tem uma janela de contexto menor do que modelos de nuvem da classe GPT-4. Documentos longos precisam de sumarização ou chunking. Histórico longo de conversa precisa ser podado. Saídas de tool que retornam payloads estruturados grandes devem retornar uma referência (um ID, uma chave) que o próximo turno possa re-buscar sob demanda, não o payload inteiro inline.

O conjunto de restrições é semelhante ao de projetar para um runtime edge de baixa potência, não para um modelo de nuvem de fronteira. As facilidades do framework tornam isso mais agradável; os limites físicos subjacentes não se movem.

Quando recorrer a Foundation Models

Os encaixes mais fortes do framework são onde a geração no dispositivo, com baixa fricção, é o produto:

Reformatação e reescrita. Transformar uma nota livre do usuário em uma entrada estruturada, polir uma mensagem rascunho, resumir uma transcrição capturada. A tolerância a latência é moderada; a sensibilidade dos dados é alta; inferência na nuvem é exagero.

Síntese local sobre dados privados. Um app de treino transformando o histórico de treinos do usuário em um resumo “esta semana”. Um app financeiro explicando o padrão de gastos do usuário. Um app de diário fazendo emergir temas em um trimestre de entradas. Os dados não devem sair do dispositivo; a resposta deve aparecer no app; o prompt é limitado.

Tool-calling leve para automação interna do app. Um app que permite ao usuário dizer “mostre o log de meditação de terça” e usa uma tool para buscar os registros subjacentes, e então formata a resposta. O agente é o app, a tool é a camada de dados do próprio app, o modelo é local.

Geração com conformidade de tipo. Em qualquer lugar onde o app de outra forma escreveria à mão um parser JSON ou um template de string, @Generable mais @Guide é uma superfície mais durável.

Quando NÃO recorrer a Foundation Models

O framework é a resposta errada para vários casos comuns:

Qualquer coisa que o usuário possa pedir à Siri. “Registrar 250ml de água”, “Iniciar uma meditação de 5 minutos”, “Adicionar bananas à minha lista” são App Intents. Apple Intelligence é o runner; seu app é o destino. Foundation Models é para geração dentro do app, não para ações roteadas pela Siri. Se você construir a mesma capacidade duas vezes (App Intent + LanguageModelSession com uma tool), o App Intent vence porque o usuário invoca a Siri, não a tela dentro do seu app.

Qualquer coisa que um agente LLM externo deva conduzir. Uma sessão do Claude Code alcançando o domínio do seu app pertence a MCP. O app não roda o LLM; o host roda; o modelo vive onde quer que o host o coloque. Foundation Models não pode servir agentes externos.

Raciocínio pesado sobre documentos grandes. O modelo no dispositivo é pequeno. Um contrato de 200 páginas, um contexto longo de codebase, ou raciocínio multi-imagem sobre muitas fotos pertence a inferência na nuvem (sua ou de um fornecedor), onde a janela de contexto e a contagem de parâmetros correspondem à carga de trabalho. Tarefas que excedem o envelope do framework produzem erros concretos: janela de contexto excedida, violações de guardrail, locales não suportados. Apresente esses erros deliberadamente em vez de projetar fluxos que dependem do modelo lidar com trabalho fora do envelope.

Workflows entre dispositivos e entre usuários. O modelo no dispositivo tem acesso apenas ao que o app passar para a sessão. Sincronização entre dispositivos (estado de timer do Watch para o iPhone), colaboração entre usuários (listas compartilhadas, documentos compartilhados), e qualquer fluxo que se beneficie de coordenação no servidor precisam de um servidor. O modelo não é uma primitiva de rede.

O que eu construiria diferente na minha stack

O framework recompensa uma escolha arquitetural específica que é fácil de errar na primeira passada. Capacidades que o usuário invoca por meio da UI do app e o LLM devem consumir como tools, não como caminhos duplicados em prosa.

Um app de meditação pode adicionar um painel de “revisão semanal” resumido por LLM. A construção ingênua é um único prompt: “Aqui estão as entradas do usuário desta semana, escreva um parágrafo.” A construção melhor define uma tool WeeklyEntries que o modelo pode chamar quando precisar saber o que estava na semana, mais saída estruturada WeeklySummary via @Generable. A primeira construção é frágil (o modelo tem que ingerir uma lista longa de entradas a cada chamada), cara em tokens, e produz prosa não estruturada. A segunda é durável (a chamada de tool separa “o que aconteceu” de “como falar sobre isso”), barata (o modelo só busca o que precisa), e estruturada (o resultado é um valor Swift tipado).

O padrão se compõe limpamente com App Intents e MCP. A mesma query WeeklyEntries também é o corpo de um resolver de parâmetro AppIntent e de um handler de tool MCP. Uma função Swift; três superfícies. O modelo chama a mesma função que o usuário chama.

A outra decisão arquitetural: descrições de tools são parte do prompt. O modelo lê Tool.description para decidir se e quando chamar. Trate a descrição como uma docstring que você realmente espera que um futuro contribuidor leia; o modelo é o futuro contribuidor.

O que o padrão significa para a stack Apple no iOS 26+

Três conclusões.

1. O LLM no dispositivo é uma feature de runtime, não um backend. Trate-o como um system framework com uma janela de contexto e um orçamento de inferência no dispositivo, não como um serviço remoto. As decisões arquiteturais são disponibilidade, latência, disciplina de janela de contexto, e saída estruturada.

2. O protocolo Tool é a superfície. Sem tools, o modelo é um endpoint de chat completion sem conexão com seu domínio. Com tools, o modelo se torna uma camada de query estruturada sobre os dados do seu app.

3. A regra de roteamento entre Foundation Models, App Intents e MCP é “quem roda o modelo”. Geração dentro do app vai para Foundation Models. Capacidades roteadas pela Apple Intelligence vão para App Intents. Capacidades de agente externo vão para MCP. A mesma função de domínio Swift pode ser chamada pelas três superfícies.

O cluster completo do Ecossistema Apple: App Intents tipados para Apple Intelligence; servidores MCP para agentes cross-LLM; a questão de roteamento entre os dois; Live Activities para a máquina de estados da Lock Screen; padrões Liquid Glass para a camada visual; shipping multi-plataforma para alcance entre dispositivos. 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

O que é o framework Foundation Models no iOS 26?

Foundation Models é o framework da Apple para acessar o modelo de linguagem no dispositivo que vem com dispositivos elegíveis para Apple Intelligence no iOS 26 (e iPadOS 26, macOS 26, visionOS 26). O framework expõe SystemLanguageModel, LanguageModelSession e o protocolo Tool para que apps possam executar chamadas tipadas de LLM no dispositivo sem acesso à rede.

Como o protocolo Tool funciona?

Uma Tool é um tipo Swift que declara uma struct Arguments (anotada com @Generable e @Guide), um método async call(arguments:), e um nome + descrição que o modelo usa para decidir quando chamar. Tools são vinculadas a uma LanguageModelSession na construção. Quando o modelo decide que precisa de uma tool, o framework decodifica os argumentos, executa a chamada, e devolve a saída tipada para a sessão.

Qual a diferença entre Foundation Models, App Intents e MCP?

Foundation Models é para que seu app rode o LLM no dispositivo para geração dentro do app. App Intents é para que Apple Intelligence (o agente do sistema) chame as capacidades tipadas do seu app. MCP é para que hosts LLM externos (Claude, ChatGPT, etc.) chamem as tools tipadas do seu app através de um transporte JSON-RPC. Os três protocolos diferem em quem roda o modelo. A mesma função de domínio Swift pode servir aos três.

Foundation Models pode chamar tools MCP?

Não. LanguageModelSession.tools aceita conformes ao protocolo Tool da Apple, não servidores de tools MCP. Para fazer a ponte entre os dois, você escreveria uma Tool Foundation Models cujo método call invoca um cliente MCP. A Apple não entregou um adapter embutido; a ponte seria código no app.

O modelo no dispositivo é bom o suficiente para produção?

Para os casos de uso para os quais o framework foi projetado (reformatação, sumarização, geração estruturada sobre dados locais, tool-calling leve), sim. Para raciocínio de fronteira sobre contextos grandes, compreensão multimodal em escala, ou raciocínio entre documentos, não. O modelo no dispositivo é um modelo de 3 bilhões de parâmetros com uma janela de contexto menor do que LLMs na nuvem; escolha workloads que caibam no envelope.

Referências