Fluxo de trabalho agêntico do Foundation Models: dentro do app vs LLM de tooling

Um app Swift no iOS 26 tem dois LLMs tocando nele, em camadas muito diferentes. Um é o modelo on-device que o usuário executa pelo LanguageModelSession do app. O outro é o agente que o desenvolvedor executou pelo Claude Code, Cursor ou Codex CLI para escrever o app em primeiro lugar. Confundir esses dois LLMs é um erro recorrente de arquitetura no desenvolvimento agêntico Apple. Eles não são o mesmo problema; não compartilham modelo de segurança; não compartilham história de deploy; e os padrões que funcionam para um falham ativamente para o outro.

O LLM de runtime é uma funcionalidade entregue ao usuário. O LLM de tooling é uma caneta que o desenvolvedor segura. O modelo de runtime vive por trás das expectativas de privacidade do usuário, das verificações de disponibilidade do sistema e da revisão da App Store. O modelo de tooling vive por trás da chave da API do desenvolvedor, das permissões de filesystem da IDE e de uma revisão de código pela qual o desenvolvedor é responsável. As duas stacks raramente se cruzam, e quando se cruzam (um servidor MCP que o desenvolvedor usa para operar o domínio do app durante o desenvolvimento e que o app de runtime também poderia expor para automação do usuário final), a fronteira de confiança se desloca e a arquitetura precisa reconhecer isso.

Este post nomeia essa distinção e a questão de roteamento que vem em seguida: qual LLM deve servir qual capacidade, e o que cada um deve ao usuário.

TL;DR

• O LLM de runtime é o Foundation Models (SystemLanguageModel.default mais o protocolo Tool). A inferência é local, o modelo vem com o sistema operacional e o app executa a chamada em nome do usuário.¹
• O LLM de tooling é o que o desenvolvedor escolheu: Claude no Claude Code, GPT no Cursor, Codex CLI para Swift. A inferência é remota (infraestrutura da Anthropic ou o provedor Claude configurado, OpenAI, etc.), o modelo está onde o host o colocou, o desenvolvedor dirige o agente.
• Os dois LLMs não compartilham segurança, deploy, orçamentos de latência ou responsabilidade. Uma capacidade que faz sentido em uma camada geralmente tem o formato errado na outra.
• O mesmo servidor MCP que o desenvolvedor usa durante uma sessão do Claude Code não é automaticamente a superfície correta para automação de agente do usuário final. A fronteira de confiança muda; o que era uma ferramenta controlada pelo desenvolvedor se torna uma ferramenta controlada pelo usuário (ou pelo sistema).

Duas stacks, mesma palavra “LLM”

A colisão acontece em conversas como esta. Alguém diz “deveríamos adicionar um LLM ao app”. Se isso significa um recurso que o usuário invoca (escreva um resumo de meditação para mim, polir este rascunho, classificar esta foto) ou uma ferramenta que o desenvolvedor conecta ao próprio loop de iteração (deixar o Claude Code escrever a migration, deixar o Cursor refatorar a view) não está claro pela frase. Ambos são adições de LLM. Nenhuma é a mesma decisão de engenharia.

Foundation Models é uma stack. O modelo vive em SystemLanguageModel.default, tem uma janela de contexto fixa, roda em Apple silicon, nunca sai do dispositivo e é restrito pela elegibilidade do usuário ao Apple Intelligence.¹ O desenvolvedor do app restringe entradas via tipos @Generable, expõe capacidades do app através do protocolo Tool e entrega um binário que chama o modelo quando o recurso é acionado. O usuário invoca o recurso; o sistema operacional fornece o modelo; o app costura tudo isso junto.

Claude Code, Cursor, Codex CLI e qualquer outra IDE agêntica formam uma stack diferente. O modelo vive onde o provedor de LLM host o executa (servidores da Anthropic para Claude, da OpenAI para GPT, etc.). A IDE é o host. Os servidores MCP são ferramentas que o modelo do host pode chamar. A máquina do desenvolvedor tem acesso ao filesystem, acesso ao shell e o que mais a IDE tenha decidido expor. O desenvolvedor invoca o agente; o agente alcança o filesystem do desenvolvedor; a saída cai no projeto do desenvolvedor.²

Mesma palavra “LLM”, raios de explosão muito diferentes.

Seis eixos onde as duas stacks divergem

Seis propriedades tornam a divergência concreta:

A fronteira de confiança é a linha que sustenta a estrutura. O LLM de runtime opera dentro do sandbox do app sob as expectativas de privacidade do usuário; o LLM de tooling opera dentro da máquina do desenvolvedor sob a autoridade do desenvolvedor. Um padrão como deixar o LLM executar um comando de shell é normal em tooling (o Claude Code faz isso constantemente através da ferramenta Bash)³ e inviável em runtime: o Foundation Models não tem ferramenta Bash, e o protocolo Tool é uma função Swift tipada que o desenvolvedor do app escreveu e revisa.¹

A linha de custo do mau uso é a consequência de errar a fronteira de confiança. Um LLM de runtime que exfiltra dados do usuário para um servidor é uma violação de privacidade e uma rejeição por diretrizes. Um LLM de tooling que exfiltra o código-fonte do desenvolvedor para um provedor de LLM é, dependendo do contrato do desenvolvedor, ou comportamento esperado ou um vazamento. Ambos importam; importam por razões diferentes.

O servidor MCP que fica no meio

O lugar mais limpo para ver a fronteira se mover é quando um único servidor MCP é usado por ambas as stacks. O Get Bananas entrega um servidor MCP que expõe operações de lista de compras: ler itens, adicionar itens, marcar como concluído. O mesmo servidor roda em dois lugares.⁴

Na sessão do Claude Code do desenvolvedor durante a iteração, o servidor MCP é uma ferramenta que o agente do desenvolvedor chama para manipular a própria lista do desenvolvedor. O servidor roda contra um arquivo JSON no iCloud Drive. O desenvolvedor conectou o servidor à configuração do host MCP; o host sabe chamá-lo; o agente lê/escreve itens de compras como parte de tarefas de desenvolvimento maiores.

Em uma superfície de agente para usuário final (um usuário externo do Claude Desktop apontando para uma lista compartilhada, por exemplo), o mesmo servidor MCP tem obrigações diferentes. O chamador não é mais o Blake-desenvolvedor com confiança total no filesystem; o chamador é um usuário final cuja autenticação, autorização e verificação de intenção não são responsabilidade do desenvolvedor. O servidor MCP precisa impor essas proteções (ou se recusar a se expor) antes que essa superfície se torne segura.

O mesmo método JSON-RPC, add_item, servido a um desenvolvedor por um transport stdio local sem autenticação, tem o formato correto. Servido a um host acessível pela internet em nome de um usuário final arbitrário sem autenticação, é um risco de integridade de dados. O servidor MCP é o mesmo código; o deploy ao redor muda tudo.

Essa é a regra de roteamento para servidores MCP no desenvolvimento agêntico Apple. O servidor é um contrato tipado sobre um domínio. Onde ele se posiciona na stack (ferramenta de desenvolvedor vs superfície para usuário final) é uma decisão de deploy, não uma decisão de protocolo. Faça revisão de código do deploy; não assuma que os defaults permissivos do protocolo são os defaults corretos do deploy.

O protocolo Tool on-device não é um servidor MCP

Uma confusão comum: o Foundation Models tem um protocolo Tool, e o MCP tem chamadas de ferramentas. São a mesma coisa? Não, e a diferença importa para roteamento.

O protocolo Tool do Foundation Models é uma API Swift que o desenvolvedor do app implementa:¹

struct WaterEntryLookup: Tool {
    let name = "lookup_water_entries"
    let description = "Look up water intake entries for a given date range."
    @Generable struct Arguments { ... }
    func call(arguments: Arguments) async throws -> String { ... }
}

A ferramenta roda dentro do processo do app. O modelo que a ferramenta serve é o SystemLanguageModel do dispositivo. Os argumentos e saídas são tipos Swift. O desenvolvedor revisa a implementação, a App Store revisa o app. O usuário invoca um recurso; a sessão do app chama a ferramenta; o modelo local usa o resultado.

Uma ferramenta MCP é um método JSON-RPC exposto por um servidor MCP, que é um processo separado ao qual o LLM host (Claude, GPT, etc.) se conecta:²

{
  "name": "add_item",
  "description": "Add an item to the shopping list.",
  "inputSchema": {"type": "object", "properties": {"name": {"type": "string"}}}
}

A ferramenta roda fora do processo do agente, na linguagem que o desenvolvedor escolheu, falando JSON por stdio ou Streamable HTTP. O modelo está onde o host o colocou. Os argumentos são JSON validados contra o schema. A responsabilidade é de quem fez o deploy do servidor MCP.

Os dois protocolos resolvem problemas sobrepostos com escopos diferentes:

A regra de roteamento é direta: se a capacidade serve aos próprios recursos de LLM do app para usuários finais, vai num Tool do Foundation Models. Se a capacidade serve a um agente externo (desenvolvedor ou usuário final) operando entre processos, vai numa ferramenta MCP. Alguns apps precisam de ambos; a mesma função Swift pode servir de base para ambos os adaptadores, mas os adaptadores vivem em camadas diferentes da stack e são entregues por ciclos de release diferentes.⁵

Hooks são onde o LLM de tooling ganha seu lugar

O raio de explosão do LLM de tooling faz dos hooks a primitiva de segurança que sustenta tudo. O sistema de hooks do Claude Code executa scripts em eventos de ciclo de vida (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop).⁶ Um desenvolvedor iOS usando Claude Code configura hooks não porque o agente seja malicioso, mas porque a autoridade do agente é ampla: escrita no filesystem, execução de shell, commits no git, push.

Os padrões que ganham seu lugar de hook em trabalho agêntico Apple:

Um bloqueio PreToolUse em comandos Bash que correspondam a xcodebuild ou xcrun sem aprovação explícita. O Claude Code pode rodar builds, apagar simuladores, invocar passos de assinatura ou exportação, ou mutar estado gerado do projeto se você deixar. O hook transforma “o agente rodou um build” em “o agente pediu para rodar um build e recebeu um sim”. Desacelerar o agente em ações irreversíveis é o tradeoff certo para a confiança do desenvolvedor.

Um validador PostToolUse em toda chamada de Edit ou Write contra arquivos .pbxproj. O arquivo de projeto do Xcode é editado por humanos mas tóxico para agentes; uma linha errada quebra silenciosamente o build para todo desenvolvedor da equipe. Um hook que executa plutil -lint (ou uma verificação estrutural similar) em toda escrita em .pbxproj antes de commitar é a diferença entre “o agente escreveu a migration em cinco minutos” e “o agente escreveu a migration e quarenta e cinco minutos de git bisect”.

Um hook Stop que executa swift build (ou o comando de build apropriado) antes de deixar o agente declarar uma tarefa como concluída. Os agentes são treinados em como “concluído” parece numa conversa. O hook faz “concluído” significar “o build ainda compila”, que é a única definição que importa para entrega.

O LLM de runtime não precisa de nada disso. O Foundation Models não tem shell, não tem git, não tem arquivo de projeto, não tem configuração de servidor MCP. O Tool on-device é a função Swift que o desenvolvedor do app escreveu; o usuário invoca um recurso; nada escapa do sandbox ou dos entitlements do app a menos que a própria implementação do Tool do app o faça.

A assimetria é o ponto. O LLM de tooling tem mais autoridade e precisa de mais proteções. O LLM de runtime tem menos autoridade por construção. A Apple fez o trabalho de tornar o LLM de runtime seguro; o desenvolvedor faz o trabalho de tornar o LLM de tooling seguro.

Regras de arquitetura

Três regras arquiteturais decorrem da distinção entre runtime e tooling.

Escolha a camada por capacidade, não por app. Um app de meditação pode usar Foundation Models para resumo dentro do app (LLM de runtime, on-device, vem com o app) e expor um servidor MCP que o desenvolvedor usa com Claude Code para importação em massa do histórico de sessões durante a iteração. Os dois LLMs servem trabalhos diferentes em camadas diferentes. Tratá-los como uma única decisão produz um resultado pior em ambas as camadas do que tratá-los como duas.

Faça revisão de código do alcance do LLM de tooling. Uma sessão do Claude Code com acesso total ao filesystem e servidores MCP remotos é um ambiente de desenvolvimento poderoso e uma superfície de ataque generosa. A mitigação não é “confiar no agente”; a mitigação são hooks, permissões com escopo e um desenvolvedor que lê o diff. O agente trabalha para você; o agente não é você.

Entregue o conjunto de Tool do LLM de runtime como uma API estável. As ferramentas do Foundation Models fazem parte do contrato binário do seu app. Remover ou renomear uma ferramenta entre releases é uma mudança de comportamento para usuários que dependiam do recurso. Trate definições de ferramentas como affordances de UI, não como helpers internos.

O que eu construiria diferente na minha stack

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

Construa primeiro a camada de domínio; deixe que ferramentas de runtime e servidores MCP de tooling envolvam as mesmas funções Swift. O padrão de adaptador duplo de App Intents vs MCP se estende naturalmente para ferramentas de LLM de runtime. Um método de domínio logWater(amount:caller:) é envolvido por um AppIntent (superfície do Apple Intelligence), uma ferramenta MCP (superfície de agente externo) e um Tool do Foundation Models (superfície de LLM de runtime dentro do app). Três adaptadores de protocolo, uma função de domínio, três classes de chamadores (agente do sistema, agente externo, modelo on-device) com três obrigações diferentes. A função não sabe qual chamador a invocou; os adaptadores carregam os sinais de confiança.

Trate os servidores MCP do agente como código, não como configuração. Um .mcp.json referenciado em um projeto iOS é uma superfície de confiança de escopo e precedência (coberta em O Repo Não Deveria Votar na Própria Confiança). O Claude Code resolve o escopo de servidor MCP como local > projeto > usuário, e servidores com escopo de projeto pedem aprovação ao desenvolvedor antes de serem usados. O agente lê a configuração e se conecta aos servidores que o desenvolvedor aprova; o desenvolvedor revisa a configuração e os servidores. Adicionar um servidor MCP a um projeto é uma revisão de código, não um ajuste de configuração.

Quando o Foundation Models é certo e quando o LLM de tooling é certo

A árvore de decisão para a qual os posts do cluster convergem:

Is the capability a feature an end user invokes inside your app?
├── Yes → Runtime LLM (Foundation Models or cloud LLM behind an Apple Intelligence-aware surface)
│         Use the Tool protocol for app-internal tool calls.
│         Use App Intents for capabilities the system agent should reach.
└── No → It is part of the developer's iteration loop.
          ├── Is the capability local to one developer's machine? → Tooling LLM
          │     Use Claude Code, Cursor, or Codex CLI directly.
          │     Wrap shared utilities as MCP servers behind hooks.
          └── Is the capability shared across the team? → Tooling LLM with shared MCP servers
                Deploy the MCP server somewhere the team can reach.
                Code review the server like production code; gate dangerous tools behind explicit approval.

A decisão raramente produz empate. Quando produz (a mesma capacidade poderia legitimamente servir tanto usuários finais quanto desenvolvedores), a resposta são dois adaptadores, não uma superfície compartilhada, porque as posturas de confiança e cadências de atualização são suficientemente diferentes para que uma única superfície tentando servir a ambos comprometa a ambos.

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

Três conclusões.

1. Dois LLMs, duas stacks. O LLM de runtime (Foundation Models, on-device) é o agente do usuário operando sobre os dados dele dentro do seu app. O LLM de tooling (Claude Code, Cursor, Codex CLI) é o agente do desenvolvedor operando na máquina do desenvolvedor para construir o app. Eles compartilham a palavra “LLM” e quase nada mais.

2. A fronteira de confiança é a arquitetura. Onde o modelo roda, quem o executa e no que ele toca definem as obrigações. Padrões que se encaixam em uma fronteira falham ativamente na outra.

3. Servidores MCP carregam a fronteira. O mesmo servidor é uma ferramenta de desenvolvedor em um deploy e uma superfície para usuário final em outro. O protocolo não muda; o deploy muda, e o deploy é a parte que precisa de atenção de engenharia.

O cluster completo do Apple Ecosystem: App Intents tipados para Apple Intelligence; servidores MCP para agentes entre LLMs; a questão de roteamento entre os dois; Foundation Models para o LLM on-device e o protocolo Tool, com casos de uso e adaptadores customizados como os irmãos de adequação de carga e especialização; Live Activities para a máquina de estado da Lock Screen do iOS; o contrato de runtime do watchOS no Apple Watch; internals do SwiftUI para o substrato do framework; modelo mental espacial do RealityKit para cenas do visionOS; disciplina de schema do SwiftData para persistência; padrões de Liquid Glass para a camada visual; entrega multiplataforma para alcance entre dispositivos. O hub está em Apple Ecosystem Series. Para contexto mais amplo de iOS com agentes de IA, veja o iOS Agent Development guide.

FAQ

Qual é a diferença entre Foundation Models e Claude Code do ponto de vista de arquitetura?

Foundation Models é um recurso de runtime: o LLM vem com o iOS 26, roda no dispositivo do usuário através de SystemLanguageModel.default e é invocado quando o LanguageModelSession do app é acionado. O app executa a chamada em nome do usuário. O Claude Code é uma ferramenta de desenvolvimento: o LLM roda na infraestrutura da Anthropic (ou no provedor Claude configurado), a máquina do desenvolvedor hospeda a IDE, e o agente tem acesso ao filesystem do desenvolvedor, shell e servidores MCP. O desenvolvedor dirige o agente; o agente ajuda a construir o app.

O mesmo servidor MCP deve servir tanto meu agente quanto meus usuários finais?

Provavelmente não. O mesmo contrato JSON-RPC pode ser o formato certo para ambos, mas os deploys são diferentes: stdio do lado do desenvolvedor sem autenticação é normal para uma ferramenta de desenvolvedor, e um risco para uma superfície de usuário final. O protocolo é reutilizável; o deploy não é. Se você expor o mesmo servidor para ambos, trate como dois deploys atrás de uma base de código, não como uma superfície para os dois públicos.

Por que o LLM de tooling precisa de hooks mas o LLM de runtime não?

O LLM de tooling tem acesso ao filesystem, acesso ao shell, servidores MCP e autoridade de execução de código arbitrário na máquina do desenvolvedor. O LLM de runtime (Foundation Models) tem o que as implementações de Tool do app expõem, dentro do sandbox do app, sem shell. O raio de explosão é assimétrico. Hooks dão ao desenvolvedor revisão pré-execução e validação pós-execução sobre essa autoridade ampla. O LLM de runtime não precisa deles porque sua autoridade é restrita por construção.

Uma única função de domínio Swift pode servir tanto a casos de uso de runtime quanto de tooling LLM?

Sim, e esse é o padrão certo. A abordagem de adaptador duplo (uma função Swift, múltiplos wrappers de protocolo) se estende de App Intents vs MCP para incluir ferramentas do Foundation Models. A função não sabe qual chamador a invocou; os adaptadores carregam o schema, os sinais de confiança e as obrigações específicas do protocolo. Três adaptadores, um método de domínio.

Onde os LLMs hosted na cloud (OpenAI, API direta da Anthropic) se encaixam neste cenário?

LLMs da cloud chamados de dentro de um app em runtime são uma terceira categoria: LLM de runtime com inferência fora do dispositivo. Eles compartilham a postura de confiança do Foundation Models de “o app executa a chamada em nome do usuário” mas perdem a história de privacidade on-device e a história de disponibilidade fornecida pelo sistema operacional. A árvore de decisão se estende: LLMs de runtime na cloud são apropriados para capacidades que genuinamente excedem o envelope do modelo on-device (contexto grande, raciocínio de fronteira, multimodal em escala) e aceitáveis para as expectativas de privacidade do usuário (com divulgação transparente). Foundation Models é o default quando a carga de trabalho cabe; cloud é a escalada quando não cabe.

Referências