Foundation Models On-Device LLM: O Protocolo Tool

O contrato do LLM on-device que a Apple lançou na WWDC 2025 levanta uma questão imediata de roteamento: quando LanguageModelSession é a resposta certa, quando é AppIntent, quando é MCP, quando não é nenhuma das opções acima.

O iOS 26 traz 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 on-device; a rede não está no caminho da chamada. O modelo vive em SystemLanguageModel.default, seu app recebe um 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 on-device é 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. Geração on-device aumentada por tools é a capacidade real do framework. A superfície de chat é o demo.

TL;DR

• Foundation Models dá 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 on-device; 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 um 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 faz 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 on-device. App Intents = Apple Intelligence roda o modelo on-device e roteia para seu app. MCP = um host externo roda o modelo onde quiser e alcança seu app através 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 foundation model on-device. A instância padrão 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 runtime 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 em nuvem como faria com OpenAI ou Anthropic; a Apple distribui e atualiza o modelo on-device a cada versão do OS, e o framework te entrega a versão que está instalada no momento.

LanguageModelSession. Um objeto stateful 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 app de cronômetro 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 isso para duas pessoas em vez de quatro”.

Tool (o protocolo). Um protocolo Swift que declara um name, uma description, 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 para a sessão para o próximo turno. O modelo não vê Swift; o framework faz o marshalling.

Os requisitos completos do protocolo: name: String, description: String, um tipo associado Arguments que conforma com ConvertibleFromGeneratedContent, um tipo associado Output que conforma com PromptRepresentable e um método async call(arguments:). A macro @Generable no struct Arguments gera a conformidade de ConvertibleFromGeneratedContent automaticamente; para Output, String e GeneratedContent já conformam. Os exemplos documentados pela Apple retornam String ou [String].

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 -> String {
        let entries = try store.entries(
            from: ISO8601DateFormatter().date(from: arguments.startDate) ?? .now,
            to: ISO8601DateFormatter().date(from: arguments.endDate) ?? .now
        )
        let totalMl = entries.reduce(0) { $0 + $1.amountMl }
        return "Found \(entries.count) entries totalling \(totalMl)ml."
    }
}

O modelo vê uma descrição de tool e uma forma de argumento de generation-schema. O código Swift vê entrada tipada e saída tipada. A fronteira de decode/encode é a parte que a Apple controla. A saída da tool pode ser uma String ou um objeto GeneratedContent; o exemplo acima retorna String já que o consumidor é o raciocínio do próximo turno do modelo.

Generable E Guide: Saída Tipada Sem Um 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.³ Um struct @Generable declara sua forma; o framework restringe a saída do modelo para corresponder a ela.

@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
)

A chamada retorna um Response<PracticeSummary> cujo content é um PracticeSummary tipado. Sem parsing de JSON no seu código, sem string-matching para “headline:”, sem fallback para quando o modelo retornou um objeto malformado. O framework usa constrained sampling para manter a saída token-a-token do modelo estruturalmente alinhada com o schema, então saída estruturalmente inválida não escapa pela fronteira. A sessão acima não recebe tools porque saída tipada e tool calling são capacidades independentes; uma sessão pode usar @Generable para a forma da resposta, tools para grounding, ambas ou nenhuma.

A superfície tipada em Swift é o que distingue o framework das SDKs de LLM em nuvem. As SDKs em nuvem (OpenAI Structured Outputs, uso de tools de Anthropic, outras) também suportam constrained sampling, 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: a 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 aos dados.

A Questão Do Roteamento, De Três Formas

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. Elas roteiam para runners diferentes.

Foundation Models (LanguageModelSession). Seu app carrega o modelo on-device e executa 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 do 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 stack de sistema da Apple decide quando invocá-las baseado em pedido do usuário, query do Spotlight, entrada do Siri ou orquestração de Shortcuts. Coberto em detalhe em App Intents São A Nova API Da Apple Para O 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 o host o roda; chamadas de tool atravessam um transporte JSON-RPC. Coberto em Dois Ecossistemas De Agentes, Uma Lista De Compras e na 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 o Siri possa invocá-la. A capacidade “mostrar 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 on-device não é grátis. O Apple silicon cuida da inferência, mas o modelo ainda tem uma janela de contexto, um orçamento de tokens e uma latência de wall-clock que depende do dispositivo. Três restrições moldam como você projeta com o framework:⁶

Disponibilidade é por dispositivo. Nem todo dispositivo iOS 26 tem Apple Intelligence. iPhones mais antigos, dispositivos com restrições 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 runtime; o padrão correto é ramificar a UI no estado de disponibilidade antecipadamente 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.

Latência não é trivial. A latência do primeiro token em hardware iPhone 16 Pro é utilizável para interações in-app em nossos testes no Return; 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 em nuvem funcionam aqui também; não bloqueie a thread principal, mostre saída progressiva e projete para o caso em que o usuário navega para fora durante a geração.

Janelas de contexto são menores que em nuvem. O modelo on-device tem uma janela de contexto menor do que modelos em nuvem da classe GPT-4. Documentos longos precisam de sumarização ou chunking. Histórico de conversa longo precisa de trimming. Saídas de tools que retornam grandes payloads estruturados devem retornar uma referência (um ID, uma chave) que o próximo turno pode rebuscar sob demanda, não o payload inteiro inline.

O conjunto de restrições é similar a projetar para um runtime de edge de baixo desempenho, não para um modelo em nuvem de fronteira. Os affordances do framework tornam isso mais agradável; os limites físicos subjacentes não se movem.

Quando Usar Foundation Models

Os encaixes mais fortes do framework são onde geração on-device e de baixo atrito é o produto:

Reformatação e reescrita. Transforme uma nota livre do usuário em uma entrada estruturada, refine uma mensagem em rascunho, resuma uma transcrição capturada. Tolerância à latência é moderada; sensibilidade dos dados é alta; inferência em 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 de finanças explicando o padrão de gastos do usuário. Um app de diário trazendo à tona temas ao longo de um trimestre de entradas. Os dados não devem sair do dispositivo; a resposta deve aparecer in-app; o prompt é limitado.

Tool-calling leve para automação interna do app. Um app que permite ao usuário dizer “mostre meu log de meditação de terça” e usa uma tool para buscar os registros subjacentes, depois 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 teria que escrever à mão um parser de JSON ou um template de string, @Generable mais @Guide é uma superfície mais durável.

Quando Não Usar Foundation Models

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

Qualquer coisa que o usuário pode pedir ao 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 pelo Siri. Se você construir a mesma capacidade duas vezes (App Intent + LanguageModelSession com uma tool), o App Intent vence porque o usuário invoca o Siri, não a tela in-app.

Qualquer coisa que um agente LLM externo deveria conduzir. Uma sessão do Claude Code alcançando o domínio do seu app pertence ao 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 on-device é pequeno. Um contrato de 200 páginas, um contexto longo de codebase ou raciocínio multi-imagem sobre muitas fotos pertencem à inferência em nuvem (sua ou de um vendor), 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 guardrails, locales não suportados. Exponha esses erros deliberadamente em vez de projetar fluxos que dependem do modelo lidando com trabalho fora do envelope.

Workflows entre dispositivos e entre usuários. O modelo on-device tem acesso apenas ao que o app passa para a sessão. Sincronização entre dispositivos (estado de cronômetro do Watch para o iPhone), colaboração entre usuários (listas compartilhadas, documentos compartilhados) e qualquer fluxo que se beneficie de coordenação server-side precisam de um servidor. O modelo não é uma primitiva de rede.

O Que Eu Construiria De Forma Diferente Na Minha Stack

O framework recompensa uma escolha específica de arquitetura que é fácil errar na primeira tentativa. Capacidades que o usuário invoca através da UI do app e que o LLM deveria consumir como tools, não como caminhos de prosa duplicados.

Um app de meditação pode adicionar um painel de “revisão semanal” resumida 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 houve na semana, mais saída estruturada WeeklySummary via @Generable. A primeira construção é frágil (o modelo precisa ingerir uma longa lista de entradas a cada chamada), cara em tokens e produz prosa não estruturada. A segunda é durável (a tool-call 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 com App Intents e MCP de forma limpa. A mesma query WeeklyEntries também é o corpo de um resolver de parâmetro de AppIntent e de um handler de tool de 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ê 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 on-device é um recurso de runtime, não um backend. Trate-o como um framework de sistema com uma janela de contexto e um orçamento de inferência on-device, 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 agentes externos vão para MCP. A mesma função de domínio Swift pode ser chamada por todas as três superfícies.

Três posts irmãos vão mais fundo no framework Foundation Models: Casos de uso de Foundation Models para as decisões de adequação de carga de trabalho, adapters customizados para fine-tuning do modelo on-device em dados do app, e o workflow agêntico para a divisão entre LLM in-app vs ferramentas.

O cluster completo do Apple Ecosystem: App Intents tipados para Apple Intelligence; servidores MCP para agentes cross-LLM; a questão de roteamento entre os dois; Live Activities para a state machine do Lock Screen; padrões de Liquid Glass para a camada visual; shipping multiplataforma para alcance entre dispositivos. O hub está em Apple Ecosystem Series. Para contexto mais amplo de iOS-com-agentes-AI, 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 on-device 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 on-device sem acesso à rede.

Como funciona o protocolo Tool?

Uma Tool é um tipo Swift que declara um struct Arguments (anotado 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 um 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 seu app rodar o LLM on-device para geração in-app. App Intents é para Apple Intelligence (o agente do sistema) chamar as capacidades tipadas do seu app. MCP é para hosts de LLM externos (Claude, ChatGPT, etc.) chamarem 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 a todos os três.

Foundation Models pode chamar tools do MCP?

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

O modelo on-device é 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, entendimento multimodal em escala ou raciocínio entre documentos, não. O modelo on-device é um modelo de 3 bilhões de parâmetros com uma janela de contexto menor do que LLMs em nuvem; escolha cargas de trabalho que caibam no envelope.

Referências