Foundation Models no iOS 27: controle de chamada de ferramentas

O iOS 26 deu ao app um grande modelo de linguagem rodando no dispositivo, uma forma de obter saída com tipos seguros por meio de @Generable e um protocolo Tool que permitia ao modelo chamar o seu código no meio da geração¹. O modelo decidia quando recorrer a uma ferramenta, e você escrevia a ferramenta. A única coisa que você não conseguia fazer era orientar o próprio comportamento de chamada, e a única coisa que você sempre tinha de fazer era escrever cada ferramenta à mão, inclusive aquelas de que todo app precisa. O iOS 27 fecha as duas lacunas. O GenerationOptions.ToolCallingMode permite controlar como o modelo interage com as ferramentas a cada requisição², e o framework Vision agora traz duas ferramentas prontas, OCRTool e BarcodeReaderTool, que você acopla a uma sessão sem escrever você mesmo o código de reconhecimento³⁴. Juntas, elas completam o laço agêntico que o framework começou: o modelo decide o que fazer, você decide com que agressividade ele pode fazê-lo, e a Apple fornece as ferramentas de percepção que leem o mundo físico.

O que vem a seguir é a camada do iOS 27 sobre a referência do framework. Se você ainda não conhece LanguageModelSession, o protocolo Tool ou a geração guiada, comece pelo explicativo do framework Foundation Models e depois volte.

TL;DR

• O GenerationOptions.ToolCallingMode é uma nova estrutura do iOS 27 que descreve o comportamento do modelo em torno do uso de ferramentas, definida a cada requisição por meio de GenerationOptions². A Apple documenta três modos.
• O framework pode mudar de modo após a primeira chamada de ferramenta, de modo que o modelo pare de chamar ferramentas e produza uma resposta final, o que limita a atividade de ferramentas de uma única requisição².
• O OCRTool reconhece texto em uma imagem e retorna uma string com tudo o que leu. Você o habilita configurando sua LanguageModelSession com uma instância de OCRTool³.
• O BarcodeReaderTool lê códigos legíveis por máquina e retorna um array de resultados Barcode, cada um carregando o conteúdo decodificado e o tipo de simbologia. Você o habilita da mesma forma, configurando a sessão com uma instância⁴.
• Ambas as ferramentas Vision permitem sobrescrever o nome e a descrição padrão, para que você controle como o modelo identifica cada uma e decide usá-la³⁴.
• Tudo aqui é beta do iOS 27 (e os betas correspondentes de iPadOS, macOS, visionOS e, para dois dos três símbolos, watchOS)²³⁴.

O que mudou entre o iOS 26 e o iOS 27

O framework do iOS 26 tratava a chamada de ferramentas como binária na superfície da API. Você entregava a uma sessão um conjunto de ferramentas e, dali em diante, só o modelo decidia se e com que frequência chamá-las. Isso funciona para uma consulta única. Fica incômodo no momento em que você quer comportamentos diferentes entre requisições dentro de uma mesma sessão: um prompt em que o modelo precisa consultar uma ferramenta e outro em que você prefere que ele responda a partir do contexto e pule a ida e volta.

O iOS 27 coloca essa decisão nas suas mãos. O ToolCallingMode é um valor que você passa por GenerationOptions, o mesmo objeto de opções que já controla a decodificação²⁵, e o modo é uma propriedade da requisição, não da sessão. As ferramentas Vision integradas mudam o outro lado da equação: em vez de escrever uma pipeline de OCR ou um leitor de código de barras e envolvê-lo na sua própria conformidade com Tool, você acopla a implementação da Apple e investe seu esforço no prompt.

GenerationOptions.ToolCallingMode: orientando as chamadas

O ToolCallingMode é uma estrutura dentro de GenerationOptions, disponível nos betas de iOS 27, iPadOS 27, Mac Catalyst 27, macOS 27, visionOS 27 e watchOS 27². O resumo da Apple cabe em uma frase: um valor que você usa para descrever o comportamento do modelo no que diz respeito ao uso de ferramentas². A declaração é o mais simples possível:

// iOS 27 beta
struct ToolCallingMode

A documentação da Apple afirma que o modo de chamada de ferramentas oferece três modos². O texto de discussão que nomearia cada um deles está parcialmente omitido na referência no momento da escrita, então, em vez de adivinhar os identificadores, descrevo o que o framework documenta sobre o comportamento, que é a parte que de fato guia o seu design.

O comportamento que a Apple deixa explícito: o framework pode mudar de modo após a primeira chamada de ferramenta, o que permite ao modelo produzir uma resposta final². Essa única frase é a peça que sustenta tudo. Ela significa que uma requisição pode começar em uma postura na qual o modelo é livre para (ou obrigado a) chamar uma ferramenta e, assim que essa primeira chamada retorna, o framework muda de modo para que o modelo pare de recorrer a ferramentas e se comprometa com uma resposta. O efeito prático é um limite para a atividade de ferramentas de uma única requisição: você não fica à mercê de um modelo que continua chamando ferramentas em laço até esgotar a janela de contexto.

Você define o modo pelo objeto de opções que já passa para respond(to:):

import FoundationModels

let session = LanguageModelSession(tools: [FindContacts()])

// A request where you want to govern tool-calling behavior explicitly.
var options = GenerationOptions()
options.toolCallingMode = .someMode   // one of the three documented modes
let response = try await session.respond(
    to: "Draft a dinner invite to three of my contacts.",
    options: options
)

A grafia exata de .someMode vem dos três casos documentados; o que importa é o mecanismo, e o mecanismo é que o comportamento vale por requisição e é carregado por GenerationOptions. Esse objeto é a mesma estrutura do iOS 26 que governa a estratégia de decodificação, o modo como o modelo escolhe os tokens de saída e o limite opcional de tokens de resposta, ao qual você recorre apenas para se proteger contra prolixidade descontrolada⁵. O modo de chamada de ferramentas é uma nova dimensão de uma superfície de controle que você já usa, não um novo objeto para conduzir pelo seu código.

O controle fica no nível da requisição em vez do nível da sessão porque a necessidade de ferramenta é uma propriedade da pergunta, não da conversa. Uma sessão de chat pode ter um turno que realmente exige uma busca de contatos e um turno seguinte que é pura reformulação, algo que o modelo consegue fazer com o que já tem em mãos. Forçar uma chamada de ferramenta no segundo turno desperdiça uma ida e volta e queima tokens que a janela de contexto compartilhada não pode dispensar⁵. O modo por requisição deixa cada turno declarar a própria postura.

Ferramentas Vision integradas: OCRTool e BarcodeReaderTool

A segunda metade da história do iOS 27 vem do framework Vision, exposto como ferramentas do Foundation Models. A Apple agora traz duas ferramentas que você acopla a uma LanguageModelSession do mesmo jeito que acopla uma das suas, exceto que você não escreve nada do código de reconhecimento.

Na sessão 241, a Apple apresenta BarcodeReaderTool e OCRTool como ferramentas de sistema integradas que ampliam a capacidade do modelo de raciocinar sobre informações visuais de formas que ele não consegue nativamente.⁷

OCRTool

O OCRTool reconhece texto em uma imagem. O resumo da Apple é exatamente esse, e a discussão é precisa quanto ao contrato: a ferramenta retorna uma string contendo todo o texto reconhecido na imagem³. Para ligá-la, você configura sua LanguageModelSession com uma instância de OCRTool³. A declaração:

// iOS 27 beta, Vision framework
struct OCRTool

Acoplá-la segue o mesmo formato de qualquer ferramenta, porque, para a sessão, ela é apenas mais um Tool:

import FoundationModels
import Vision

// Configure the session with an OCRTool instance to enable it.
let session = LanguageModelSession(tools: [OCRTool()])

let response = try await session.respond(
    to: "Pull the total and the date off this receipt image and summarize them."
)

O modelo decide quando o prompt precisa de texto extraído de uma imagem, chama o OCRTool, recebe de volta uma string com tudo o que a ferramenta leu e incorpora essa string à resposta da mesma forma que incorporaria o resultado de uma ferramenta escrita por você³. Você não escreveu nenhuma requisição do Vision nem código de tratamento. Você acoplou uma ferramenta e descreveu a tarefa.

A Apple permite sobrescrever o nome e a descrição padrão para personalizar como o modelo identifica e usa a ferramenta³. Esse gancho é a única alavanca que você tem sobre quando o modelo recorre ao OCR. Se o seu app lê recibos, escrever a descrição da ferramenta em termos de recibos inclina o modelo a chamá-la em prompts com cara de recibo e a evitá-la em prompts em que a imagem é meramente decorativa. A descrição é uma documentação de função que o modelo lê, então escreva-a como tal.

BarcodeReaderTool

O BarcodeReaderTool lê códigos legíveis por máquina em uma imagem⁴. Enquanto o OCRTool retorna uma string plana, a ferramenta de código de barras retorna estrutura: quando o modelo encontra uma imagem com códigos legíveis por máquina, ele pode chamar essa ferramenta para decodificá-los, e a ferramenta retorna um array de resultados Barcode, cada um contendo o conteúdo decodificado e o tipo de simbologia⁴. A declaração e o acoplamento espelham o OCRTool:

// iOS 27 beta, Vision framework
struct BarcodeReaderTool

// Configure the session with a BarcodeReaderTool instance to enable it.
let session = LanguageModelSession(tools: [BarcodeReaderTool()])

let response = try await session.respond(
    to: "Scan this label and tell me what product it is and which standard the code uses."
)

O tipo de simbologia em cada resultado Barcode é o detalhe que justifica o retorno estruturado⁴. Um QR code, um código de barras EAN-13 de supermercado e um PDF417 numa carteira de motorista são todos códigos legíveis por máquina, e significam coisas diferentes para o seu app. Como a ferramenta devolve a simbologia ao lado do payload decodificado, o modelo (e o seu código a jusante) pode ramificar conforme o tipo de código, e não apenas conforme os bytes contidos nele. Como no OCRTool, você pode sobrescrever o nome e a descrição padrão para orientar como o modelo identifica e usa a ferramenta⁴.

Ambas as ferramentas carregam a mesma disponibilidade beta: iOS 27, iPadOS 27, Mac Catalyst 27, macOS 27 e visionOS 27 para as duas, com o BarcodeReaderTool listado também para watchOS 27³⁴.

Compondo o laço: percepção mais chamada controlada

Os dois recursos são interessantes por si sós e melhores juntos, porque se posicionam em extremidades opostas de uma mesma requisição agêntica. As ferramentas Vision são percepção, os olhos do modelo sobre uma imagem. O ToolCallingMode é governança, a sua mão sobre o quanto o modelo se apoia nesses olhos.

Imagine um recurso de reposição de despensa. O usuário fotografa uma prateleira. A sessão tem ambas as ferramentas Vision acopladas e uma ferramenta sua, um LookUpProduct que consulta o catálogo do app. Uma única requisição pede ao modelo que identifique os itens e monte uma lista de reposição. O modelo chama o BarcodeReaderTool para decodificar os rótulos que consegue ver, lê qualquer texto impresso com o OCRTool nos itens sem um código nítido e chama o seu LookUpProduct para resolver cada payload decodificado em uma entrada do catálogo. Três ferramentas, um prompt, uma resposta coerente.

import FoundationModels
import Vision

let session = LanguageModelSession(tools: [
    OCRTool(),
    BarcodeReaderTool(),
    LookUpProduct(),     // your own Tool conformance over the app catalog
])

var options = GenerationOptions()
options.toolCallingMode = .someMode   // govern how the model sequences the calls
let response = try await session.respond(
    to: "Identify everything on this shelf and build a reorder list.",
    options: options
)

Esse é o laço para o qual o framework vinha caminhando. O iOS 26 forneceu o modelo de runtime, a geração guiada e o protocolo Tool que permite ao modelo no dispositivo invocar o seu código sem que você precise analisar texto livre¹. O artigo de arquitetura deste cluster traçou a linha entre esse modelo de runtime e o LLM de ferramental que um desenvolvedor roda no Claude Code para escrever o app, e defendeu uma única função de domínio em Swift sustentando um Tool do Foundation Models, um App Intent e uma ferramenta MCP por meio de três adaptadores enxutos⁶. O iOS 27 se encaixa no lado de runtime dessa figura: as ferramentas Vision integradas são funções de domínio que a Apple escreveu e você monta, LookUpProduct é a função de domínio que você escreveu, o modelo orquestra todas elas, e o ToolCallingMode é o acelerador sobre a orquestração.

A fronteira de confiança não se move. OCRTool e BarcodeReaderTool rodam dentro do processo do app, no dispositivo, sobre a imagem do usuário, sob o mesmo sandbox e a mesma postura de privacidade de uma ferramenta escrita por você. A Apple fornecer a implementação muda quem mantém o código de reconhecimento, não quem responde pelo recurso. Você continua dono do prompt, da sessão, da verificação de disponibilidade e da decisão de pôr uma câmera diante do usuário.

Quando usar cada modo e cada ferramenta

Algumas regras que decorrem dos contratos acima.

Recorra ao ToolCallingMode quando a necessidade de ferramenta varia a cada requisição. Se todo turno de uma sessão precisa do mesmo comportamento de ferramenta, o padrão basta e o modo é só ruído. O modo ganha seu lugar quando uma requisição precisa consultar uma ferramenta e outra deve responder a partir do contexto, ou quando você quer que a mudança de modo do framework após a primeira chamada limite uma requisição que, de outra forma, poderia entrar em laço². Defina-o na requisição, e não uma vez para a sessão, porque é aí que o controle vive².

Recorra ao OCRTool quando a resposta é texto preso em uma imagem. Recibos, placas, anotações à mão, capturas de tela de texto. A ferramenta retorna uma string com tudo o que leu³, então combina com prompts em que você quer que o modelo raciocine sobre as palavras, não sobre o layout. Se você precisa de caixas delimitadoras ou de confiança por linha, isso é uma requisição do Vision de nível mais baixo, não esta ferramenta.

Recorra ao BarcodeReaderTool quando a imagem carrega códigos legíveis por máquina e o tipo de código importa. Rótulos de produtos, ingressos, documentos, etiquetas de inventário. O retorno estruturado — conteúdo decodificado mais simbologia⁴ — é o motivo para preferi-lo a tratar um código de barras como texto genérico. Ramifique conforme a simbologia na sua própria ferramenta ou no seu pós-processamento.

Sobrescreva o nome e a descrição sempre que o seu app tiver uma tarefa específica para uma ferramenta genérica. Ambas as ferramentas Vision vêm com identidades genéricas por padrão, e o modelo escolhe ferramentas em parte pelas descrições delas³⁴. Um app que só lê recibos deveria dizer isso na descrição da ferramenta de OCR, para que o modelo não a chame em toda foto que por acaso contenha uma palavra.

FAQ

O que é GenerationOptions.ToolCallingMode no iOS 27?

É uma estrutura, nova no beta do iOS 27, que descreve o comportamento do modelo em torno do uso de ferramentas para uma dada requisição. Você a define por meio do GenerationOptions que passa para respond(to:), de modo que o comportamento de chamada de ferramentas é uma propriedade de cada requisição, e não da sessão inteira. A Apple documenta três modos².

Quantos modos de chamada de ferramentas a Apple documenta, e como eles se chamam?

A documentação da Apple afirma que o modo de chamada de ferramentas oferece três modos². O texto de referência que nomeia cada modo individualmente está parcialmente omitido no momento da escrita, então descrevo o comportamento documentado em vez de adivinhar os identificadores. O comportamento que a Apple declara explicitamente: o framework pode mudar de modo após a primeira chamada de ferramenta, de modo que o modelo produza uma resposta final, o que limita a atividade de ferramentas de uma única requisição².

Como habilito a ferramenta de OCR integrada da Apple?

Configure sua LanguageModelSession com uma instância de OCRTool, do mesmo jeito que você acopla qualquer ferramenta³. O modelo então a chama quando um prompt precisa de texto extraído de uma imagem, e a ferramenta retorna uma string contendo todo o texto reconhecido. O OCRTool está no framework Vision e está disponível no beta do iOS 27³.

O que o BarcodeReaderTool retorna?

Ele retorna um array de resultados Barcode, cada um contendo o conteúdo decodificado e o tipo de simbologia⁴. A simbologia permite distinguir um QR code de um EAN-13 e de um PDF417 e ramificar conforme o tipo de código, não apenas conforme o payload. Você o habilita configurando uma LanguageModelSession com uma instância de BarcodeReaderTool⁴.

Posso mudar como o modelo decide usar as ferramentas Vision integradas?

Sim. Tanto o OCRTool quanto o BarcodeReaderTool permitem sobrescrever o nome e a descrição padrão para personalizar como o modelo identifica e usa a ferramenta³⁴. A descrição é a alavanca sobre quando o modelo recorre à ferramenta, então escrevê-la nos termos do seu próprio app inclina o modelo às chamadas certas.

As ferramentas Vision integradas enviam imagens para fora do dispositivo?

Não. OCRTool e BarcodeReaderTool são ferramentas do Foundation Models que rodam dentro do processo do app, no dispositivo, sob o mesmo sandbox e a mesma postura de privacidade de uma ferramenta escrita por você¹³⁴. A Apple fornecer o código de reconhecimento muda quem o mantém, não onde ele roda nem quem responde pelo recurso.

O cluster completo do Apple Ecosystem: o explicativo do framework Foundation Models; o LLM no dispositivo; a distinção entre LLM de runtime e de ferramental; os adaptadores personalizados; os App Intents tipados; a nova execução em segundo plano e sincronização dos App Intents no iOS 27; a questão de roteamento frente às ferramentas MCP; o framework Vision; a inferência com Core ML no dispositivo; as três superfícies. O hub fica na Série Apple Ecosystem. Para um contexto mais amplo de iOS com agentes de IA, veja o guia de desenvolvimento de agentes para iOS.