Writing Tools API: como aplicativos se conectam à camada de escrita do Apple Intelligence

A camada de escrita do Apple Intelligence, batizada de Writing Tools, está em todo dispositivo iOS 18+ com Apple Intelligence ativado. O usuário seleciona o texto, toca no menu Writing Tools e obtém revisão, reescrita (amigável, profissional, conciso), resumo, geração de listas e tabelas e (desde o iOS 18.2) composição generativa¹. O recurso vive na camada do sistema, não em um único aplicativo, e o usuário espera que funcione em todo campo de entrada de texto.

Aplicativos que usam UITextView, NSTextView ou WKWebView recebem a integração sem escrever código, desde que a text view rode em TextKit 2². Aplicativos com mecanismos de texto personalizados precisam do API UIWritingToolsCoordinator para conectar seu armazenamento e renderização de texto à experiência do Writing Tools. Este post percorre a superfície do API contra a documentação da Apple, nomeia os três níveis de adoção e cobre quando optar por sair (porque nem toda entrada de texto deve aceitar reescritas generativas).

TL;DR

• Text views padrão (UITextView, NSTextView, WKWebView) em TextKit 2 recebem o Writing Tools de graça, com a experiência completa de reescrita inline com animação².
• Text views personalizadas adotam UITextInteraction para obter a integração com callout/menu de contexto sem código adicional; a integração inline completa exige o API UIWritingToolsCoordinator³.
• UIWritingToolsBehavior é uma única propriedade enum que controla o nível da experiência: .complete, .limited ou .none⁴. O valor .default é uma solicitação que o sistema resolve em tempo de execução para um desses três; não é um quarto nível. Para texto sensível (senhas, editores de código-fonte, campos de chat que os usuários não querem reescritos), defina .none.
• allowedWritingToolsResultOptions permite que aplicativos declarem quais formatos de saída aceitam (texto simples, texto rico, listas, tabelas ou .presentationIntent no iOS 26) para que o Writing Tools não retorne conteúdo que o aplicativo não consegue renderizar⁵.
• A conexão com fluxos de agentes: o Writing Tools é uma superfície do Apple Intelligence como App Intents e Foundation Models, mas opera na camada de entrada de texto em vez da camada de ação.

O que o Writing Tools realmente faz

O menu Writing Tools no iOS 18+ expõe um conjunto de operações sobre texto selecionado. O conjunto público atual, segundo a documentação para desenvolvedores da Apple e a apresentação na WWDC 2024⁶:

Revisar. Corrige gramática, ortografia, pontuação e escolha de palavras. Retorna um diff que o usuário pode aceitar, rejeitar ou percorrer passo a passo.

Reescrever. Três tons predefinidos (amigável, profissional, conciso) mais um prompt personalizado de “descreva sua mudança”. O modelo reescreve o texto selecionado no tom escolhido.

Resumir. Texto longo vira curto. As variantes incluem “resumo”, “pontos-chave”, “lista”, “tabela”. O usuário escolhe o formato.

Compor. Escrita generativa a partir de um prompt (iOS 18.2+). O usuário descreve o que quer; o modelo gera texto novo em vez de reescrever texto existente.

O modelo que executa o Writing Tools é o foundation model on-device da Apple em hardware compatível, com fallback para a nuvem privada para solicitações maiores¹. O texto do usuário nunca vai para terceiros. A história de privacidade faz parte da proposta de valor.

Os três níveis de adoção

Os aplicativos se enquadram em um de três grupos com base em quanta integração com o Writing Tools precisam.

Nível 1: text view padrão (zero código)

Aplicativos que usam UITextView, NSTextView ou WKWebView para entrada de texto recebem o Writing Tools sem escrever nenhum código, desde que a text view use TextKit 2². O sistema cuida do menu, da UI de reescrita inline, da animação e dos destaques inline de revisão. O trabalho do aplicativo é usar a text view padrão.

let textView = UITextView()
textView.text = "Original content."
textView.isEditable = true
// Writing Tools just works.

A exigência do TextKit 2 importa porque o TextKit 1 vem com uma arquitetura de layout diferente que não suporta a animação de reescrita inline. Novos aplicativos com alvo iOS 18+ devem usar TextKit 2 por padrão; aplicativos legados podem precisar de uma etapa de migração. UITextView usa TextKit 2 por padrão no iOS 16+ quando inicializada via Interface Builder ou pelo inicializador moderno.

Nível 2: text view personalizada com UITextInteraction (apenas callout)

Aplicativos com text views personalizadas podem adotar UITextInteraction para obter o Writing Tools na barra de callout e no menu de contexto sem código adicional⁷. O usuário pode invocar o Writing Tools, ver a interface estilo painel para revisar/reescrever/resumir e aceitar ou rejeitar o resultado. O resultado é entregue ao aplicativo pelo fluxo padrão de colar/substituir.

A integração é parcial: o aplicativo não recebe a animação inline nem os destaques inline de revisão. Esses exigem o coordenador completo. Para a maioria dos aplicativos com text views personalizadas, a adoção de UITextInteraction é suficiente.

Nível 3: UIWritingToolsCoordinator (experiência inline completa)

Aplicativos que querem a experiência completa do Writing Tools com armazenamento de texto personalizado adotam UIWritingToolsCoordinator (ou NSWritingToolsCoordinator no macOS)³. O coordenador gerencia a conversa bidirecional entre o Writing Tools e o aplicativo:

• O aplicativo fornece contexto de texto (um NSAttributedString representando a seleção atual mais parágrafos circundantes opcionais) ao coordenador.
• O coordenador gerencia a UI do painel e a animação inline.
• O coordenador chama de volta por meio de um delegate para inserir, substituir ou animar mudanças de texto no armazenamento de texto do aplicativo.

Métodos-chave do delegate em UIWritingToolsCoordinator.Delegate, verificados contra os headers do SDK do iOS 26³:

• writingToolsCoordinator(_:requestsContextsForScope:completion:). O método de entrada. O Writing Tools pede ao aplicativo os contextos de texto relevantes (cada um um NSAttributedString mais um intervalo de seleção) dentro de um escopo determinado. O aplicativo monta os contextos a partir de seu armazenamento de texto e os retorna.
• writingToolsCoordinator(_:replaceRange:inContext:proposedText:reason:animationParameters:completion:). O cavalo de batalha para mudanças de texto. O Writing Tools propõe novo texto para um intervalo dentro de um contexto; o aplicativo aplica a mudança em seu armazenamento e confirma.
• writingToolsCoordinator(_:finishTextAnimation:forRange:inContext:completion:). Chamado quando uma animação de texto (a transformação entre o texto original e o reescrito) termina para um intervalo. Não é o sinal de fim de sessão.
• writingToolsCoordinator(_:willChangeToState:completion:). O sinal de ciclo de vida da sessão. O coordenador transita por estados (idle, interactive, noninteractive, etc.) e notifica o delegate antes de cada transição. É aqui que o aplicativo responde a “sessão começando” e “sessão terminando”.

O API do coordenador é projetado para mecanismos de texto serializados (estilo TextKit), editores em formato de documento e editores de código que querem integração parcial. A sessão da Apple “Dive deeper into Writing Tools” na WWDC 2025⁸ percorre os casos de múltiplos parágrafos e múltiplos estilos. Note que UIWritingToolsCoordinator foi lançado pela primeira vez como API público no iOS 18.2; o iOS 26 o aprofunda em vez de introduzi-lo.

A propriedade de comportamento: UIWritingToolsBehavior

O controle de opt-in/opt-out mais importante é a propriedade writingToolsBehavior em UITextView, UITextField e qualquer view que esteja em conformidade com UITextInputTraits⁴:

textView.writingToolsBehavior = .complete   // full inline experience
textView.writingToolsBehavior = .limited    // panel-only (no inline rewrite)
textView.writingToolsBehavior = .none       // disabled entirely
textView.writingToolsBehavior = .default    // request system default

Três valores são níveis reais de experiência; .default é uma solicitação que o sistema resolve para um dos outros três com base nos traits da entrada de texto:

• .complete. A experiência completa do Writing Tools, incluindo animação de reescrita inline, destaques inline de revisão e o painel. Melhor para editores de texto longo (compositor do Mail, Notas, editores de documentos).
• .limited. A experiência apenas com painel. O usuário recebe o Writing Tools no menu, mas as reescritas acontecem em um painel em vez de inline. Melhor para campos de texto mais curtos onde a animação inline pareceria desproporcional.
• .none. O Writing Tools fica desativado para essa entrada de texto. Use para conteúdo sensível.
• .default. Uma solicitação, não um nível. O header documenta o valor resolvido como sempre sendo um de .none, .limited ou .complete; a propriedade somente leitura behavior nunca retorna .default. A maioria dos aplicativos deve deixar a propriedade em .default a menos que haja um motivo específico para sobrescrever.

Quando optar por sair

Três categorias de entrada de texto onde .none é a escolha certa:

Senhas e credenciais sensíveis. Um campo de senha nunca deve oferecer “reescrever isto em tom amigável” como opção. O usuário está digitando texto literal que não pode ser transformado. O UITextField da Apple com isSecureTextEntry = true já desativa o Writing Tools por padrão; um .none explícito é cinto e suspensório.

Editores de código-fonte. Um editor de código SwiftUI ou um editor de Markdown para conteúdo técnico não melhora ao ser solicitado a reescrever o código selecionado em tom “profissional”. Os caminhos de reescrita do Writing Tools são ajustados para linguagem natural, não para estruturas sintáticas. Defina .none em text views cujo conteúdo não seja linguagem natural.

Campos de chat onde reescrever altera a intenção. Um aplicativo de mensagens ou um campo de comentários onde as palavras exatas do usuário importam (por tom, voz, responsabilidade) pode querer omitir reescrever mantendo revisar. O API atual do Writing Tools não permite controle por ação; o valor .none desativa toda a experiência. A jogada pragmática é .limited (apenas painel, que o usuário precisa invocar deliberadamente) para campos onde reescrever é ocasionalmente apropriado mas não deve ser o padrão inline.

allowedWritingToolsResultOptions declara o que seu aplicativo consegue renderizar

Um controle mais sutil fica em UITextInputTraits.allowedWritingToolsResultOptions (também exposto como UITextView.allowedWritingToolsResultOptions)⁵. A propriedade é um option set UIWritingToolsResultOptions que declara quais formatos de conteúdo a text view do aplicativo consegue renderizar:

• .plainText. A text view suporta texto simples (sem atributos de formatação).
• .richText. Suporta texto formatado (negrito, itálico, etc.).
• .list. Suporta renderização de listas (com marcadores, numeradas).
• .table. Suporta renderização de tabelas.
• .presentationIntent (iOS 26+). Suporta marcação rica de intenção semântica (cabeçalhos, citações em bloco, blocos de código) usando os tipos PresentationIntent do framework Foundation, que é uma superfície mais rica do que texto rico simples.

Quando definido, o Writing Tools restringe sua saída a formatos que o aplicativo aceita. Um editor de texto simples declarando apenas .plainText não receberá uma sugestão “transforme isso em tabela”. Um editor de texto rico declarando .richText e .list mas não .table receberá saída de lista mas não de tabela.

O valor padrão é .default, que deixa o sistema escolher com base nos traits da text view. Defina a propriedade explicitamente quando a autodetecção produzir formatos errados (uma text view que poderia renderizar texto rico mas o modelo de dados do aplicativo armazena apenas simples).

Onde a saída chega

Para aplicativos de Nível 1 (text views padrão), a saída substitui a seleção inline pela maquinaria padrão da text view. Nenhum código do aplicativo é envolvido.

Para aplicativos de Nível 2 (views personalizadas com UITextInteraction), a saída chega pelo fluxo padrão de colar. A implementação do protocolo UITextInput da text view é o que processa a mudança. Aplicativos que implementaram UITextInput corretamente recebem a integração “de graça” assim que UITextInteraction é adicionado.

Para aplicativos de Nível 3 (coordenador completo), a saída vem pelo método replaceRange: do delegate. O aplicativo aplica a mudança em seu armazenamento de texto, retorna os novos limites do texto no completion handler, e o coordenador cuida da transição visual. O aplicativo continua sendo a fonte da verdade para o armazenamento de texto.

O que o aprofundamento da WWDC 2025 acrescentou

A sessão “Dive deeper into Writing Tools” na WWDC 2025⁸ expandiu o API do iOS 18 em três eixos que vale nomear:

Contexto de múltiplos parágrafos. Os aplicativos agora podem fornecer mais contexto circundante ao coordenador, permitindo que o Writing Tools opere em seleções que dependem dos parágrafos adjacentes (uma frase cujo significado depende do parágrafo anterior, por exemplo).

Prompts de reescrita personalizados. O caminho “descreva sua mudança” que estava em beta no iOS 18.2 tornou-se totalmente público, com hooks de delegate para aplicativos que querem inspecionar ou transformar o prompt do usuário antes de passá-lo ao modelo.

Melhor tratamento de conteúdo misto. Seleções de texto que abrangem múltiplos estilos ou incluem imagens embutidas agora fluem pelo coordenador com o conteúdo embutido preservado como intervalos opacos. O coordenador não tenta reescrever uma imagem inline; ele a preserva e reescreve o texto ao redor.

Os deltas são extensões do modelo do iOS 18 em vez de uma substituição. Aplicativos que adotaram os APIs do Writing Tools no iOS 18 continuam funcionando; o iOS 26 desbloqueia integração mais profunda para aplicativos que precisam dela.

A conexão com fluxos de agentes

Writing Tools é uma das três superfícies do Apple Intelligence com as quais um aplicativo de terceiros pode integrar:

Writing Tools. A camada de entrada de texto. O usuário seleciona texto, pede ao sistema para transformá-lo, recebe o resultado inline. Aplicativos participam expondo text views bem formadas e (opcionalmente) implementando o coordenador. O usuário invoca; o aplicativo recebe o resultado.

App Intents. A camada de ação. O usuário (ou um agente) pede ao Apple Intelligence para realizar uma ação; o sistema roteia a solicitação para um intent registrado no aplicativo. Aplicativos participam declarando tipos AppIntent, esquemas de parâmetros e tipos de resultado. Coberto em App Intents Are Apple’s New API to Your App.

Foundation Models. A camada de runtime do LLM. Aplicativos invocam o LLM on-device diretamente pelo framework Foundation Models para geração in-app. Coberto em Foundation Models on-device LLM.

As três superfícies se compõem. Um aplicativo de anotações pode usar Writing Tools (para reescritas baseadas em seleção do usuário), App Intents (para “resuma minhas notas de ontem”) e Foundation Models (para um recurso generativo in-app como autoetiquetagem). Cada camada é uma integração distinta com um modelo mental de usuário distinto.

O post App Intents vs MCP Tools cobre quando expor uma ação por App Intents (Apple Intelligence) versus um servidor MCP (agentes gerais). O Writing Tools fica fora dessa questão; é uma superfície de nível de sistema que não tem equivalente de agente de terceiros na cobertura do cluster.

O que esse padrão significa para aplicativos iOS 26+

Três conclusões.

1. Use text views padrão e TextKit 2 por padrão. A maioria dos aplicativos não precisa do API do coordenador. Se a entrada de texto do aplicativo é um UITextView ou um WKWebView, o Writing Tools funciona sem código; o trabalho está na migração para TextKit 2 se o aplicativo ainda roda TextKit 1.

2. Defina writingToolsBehavior = .none deliberadamente para entradas sensíveis. Senhas, editores de código, campos de texto exato. O padrão tenta fazer a coisa certa, mas a configuração explícita é uma decisão de produto defensável que a equipe consegue articular.

3. Recorra a UIWritingToolsCoordinator apenas quando o mecanismo de texto do aplicativo for genuinamente personalizado. Editores de Markdown, editores de código, aplicativos de documentos com renderização personalizada, text views estilo terminal. O coordenador é um investimento real de engenharia; o Nível 2 (UITextInteraction) é suficiente para a maioria das views personalizadas.

O cluster completo do Apple Ecosystem: App Intents tipados; servidores MCP; a questão de roteamento; Foundation Models; a distinção entre runtime e tooling LLM; três superfícies; o padrão de fonte única da verdade; Two MCP Servers; hooks para desenvolvimento Apple; Live Activities; o contrato de runtime do watchOS; internals do SwiftUI; o modelo mental espacial do RealityKit; disciplina de schema do SwiftData; padrões Liquid Glass; shipping multiplataforma; a matriz da plataforma; framework Vision; Symbol Effects; inferência Core ML; sobre o que me recuso a escrever. O hub está na Apple Ecosystem Series. Para contexto mais amplo de iOS com agentes de IA, veja o iOS Agent Development guide.

FAQ

Preciso do Apple Intelligence para testar o Writing Tools no meu aplicativo?

Para testar a experiência completa do usuário, sim. O menu Writing Tools voltado ao usuário só aparece em dispositivos com Apple Intelligence ativado (iPhone 15 Pro ou mais novo, Mac M1 ou mais novo, com iOS 18+ / macOS 15+). Para fins de desenvolvimento, você pode testar a integração do API em qualquer simulador ou dispositivo iOS 18+ verificando que sua text view expõe isWritingToolsActive e que os métodos do delegate estão conectados corretamente; o menu do sistema simplesmente não vai aparecer sem o Apple Intelligence disponível.

O que acontece se eu não fizer nada sobre o Writing Tools no meu aplicativo iOS 18+?

Para text views padrão (UITextView, WKWebView), o Writing Tools aparece automaticamente. Para text views personalizadas sem UITextInteraction, o Writing Tools não aparece no menu e os usuários não podem invocá-lo no texto do seu aplicativo. Não fazer nada é um padrão defensável para views onde o Writing Tools seria inadequado (campos de senha, editores de código); para entrada de texto geral, não fazer nada significa perder um recurso do sistema que os usuários vão procurar.

Qual é a diferença entre .complete e .limited?

.complete executa as reescritas do Writing Tools inline com uma animação que transforma o texto original na reescrita, mais destaques inline de revisão. .limited executa o Writing Tools por uma UI de painel; o usuário vê a reescrita em uma superfície separada e decide se aplica. Use .complete para editores de texto longo onde a animação inline reforça o fluxo de edição; .limited para campos de texto mais curtos onde o painel parece mais adequado.

Posso personalizar os prompts do Writing Tools ou o comportamento do modelo?

O modelo e os prompts são controlados pelo sistema. Os aplicativos não podem injetar comportamentos de reescrita personalizados no menu do Writing Tools. Para recursos generativos de escrita específicos do aplicativo, use o framework Foundation Models diretamente (coberto em Foundation Models on-device LLM) e exponha o recurso por sua própria UI.

Como o Writing Tools lida com seleções mistas (texto + imagem)?

Conforme o “Dive deeper into Writing Tools” da WWDC 2025⁸, seleções mistas que incluem conteúdo embutido (imagens, anexos) fluem pelo coordenador com o conteúdo embutido preservado como intervalos opacos. O Writing Tools reescreve o texto ao redor mas não tenta transformar o conteúdo embutido. Para aplicativos que usam o coordenador, o delegate recebe payloads de texto proposto onde o intervalo do conteúdo embutido é marcado como inalterado.

Referências