--- title: Apple Foundation Models url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/libraries/apple-foundation-models description: Use o Claude em plataformas Apple por meio do framework Foundation Models com o pacote Swift Claude for Foundation Models. --- [Claude for Foundation Models](https://github.com/anthropics/ClaudeForFoundationModels) é um pacote Swift que disponibiliza o Claude como um modelo de linguagem do lado do servidor no framework [Foundation Models](https://developer.apple.com/documentation/foundationmodels) da Apple. O pacote faz o Claude conformar ao protocolo `LanguageModel` do framework, de modo que você o controla com a mesma API `LanguageModelSession` que usa para o modelo no dispositivo da Apple: `respond(to:)`, streaming, geração guiada e chamada de ferramentas funcionam todos da mesma forma. As requisições vão diretamente do seu app para a Claude API; a Apple não está no caminho da requisição e não vê prompts nem respostas. O uso é cobrado na sua conta Anthropic conforme os [preços padrão da API](https://platform.claude.com/docs/pt-BR/about-claude/pricing), portanto sua organização precisa de um saldo de créditos disponível ou de um método de cobrança ativo. Seu app decide quando usar o Claude e quando usar o modelo no dispositivo da Apple: passe o modelo que quiser para cada sessão. **Beta.** Este pacote tem como alvo a API de modelo de linguagem do lado do servidor do Foundation Models introduzida nas versões beta do OS 27. As APIs podem mudar durante o beta. Claude for Foundation Models **não** é um cliente de uso geral da Messages API. Sua superfície pública é a conformidade de provedor do Foundation Models mais os tipos de configuração que chegam a ela (`ClaudeLanguageModel`, `ClaudeModel`, `AuthMode`, `ClaudeServerTool`). Para acesso direto à Messages API em outra linguagem, consulte os [Client SDKs](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview#client-sdks). ## Requisitos * iOS 27, macOS 27, visionOS 27 ou watchOS 27 (todos em beta): as versões de sistema operacional cujo framework Foundation Models oferece suporte a modelos de linguagem do lado do servidor * Xcode 27 (beta) * Uma chave de API do Claude obtida no [Claude Console](https://platform.claude.com/) para desenvolvimento. Consulte [Autenticação](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/libraries/apple-foundation-models#authentication) para opções de produção. ## Instale o pacote Adicione o pacote ao seu `Package.swift`: ```swift dependencies: [ .package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0") ] ``` Ou no Xcode: **File** > **Add Package Dependencies…** e insira a URL do repositório. Em seguida, adicione `ClaudeForFoundationModels` às dependências do seu target e importe-o junto com `FoundationModels`: ```swift import FoundationModels import ClaudeForFoundationModels ``` ## Início rápido `ClaudeLanguageModel` é o ponto de entrada. Passe-o para `LanguageModelSession` e use a sessão exatamente como faria com qualquer provedor do Foundation Models: ```swift import FoundationModels import ClaudeForFoundationModels let model = ClaudeLanguageModel( name: .sonnet5, auth: .apiKey(ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] ?? "") ) let session = LanguageModelSession(model: model) let response = try await session.respond(to: "Plan a 4-day trip to Buenos Aires.") print(response.content) ``` O inicializador também aceita `baseURL` (padrão `https://api.anthropic.com`), `timeout` e `serverTools` (consulte [Ferramentas do lado do servidor](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/libraries/apple-foundation-models#server-side-tools)). Para um programa funcional completo, o repositório inclui [`Examples/ClaudeExample`](https://github.com/anthropics/ClaudeForFoundationModels/tree/main/Examples/ClaudeExample), um target de linha de comando executável que faz streaming de um turno de chat para o terminal, com uma flag `--search` que habilita a busca na web do lado do servidor para o turno. Executá-lo requer um host com macOS 27. ## Escolhendo um modelo Os identificadores de modelo são valores de `ClaudeModel`. Use uma constante compilada no pacote ou construa uma com capacidades explícitas para um ID que ainda não esteja compilado (consulte [Capacidades](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/libraries/apple-foundation-models#capabilities)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth) ``` As constantes espelham os IDs de modelo da API (`.opus5` é `claude-opus-5`) e carregam as capacidades de cada modelo. Novos modelos são lançados como novas constantes em versões do pacote; verifique `ClaudeModel` no Xcode para a lista atual e a [Visão geral dos modelos](https://platform.claude.com/docs/pt-BR/models/overview) para comparar modelos. ### Capacidades Cada `ClaudeModel` declara o que aceita: parâmetros de amostragem, níveis de esforço, pensamento adaptativo, saída estruturada e entrada de imagem. O pacote usa isso para determinar quais campos de requisição enviar, porque enviar um campo que um modelo rejeita é um erro fatal. As constantes carregam as capacidades corretas. Para um ID que não esteja compilado, declare o que o modelo aceita (deliberadamente não há um atalho que adivinhe): ```swift let model = ClaudeModel( id: "claude-experimental-x", capabilities: .init(samplingParams: false, effortLevels: [.low, .high]) ) ClaudeLanguageModel(name: model, auth: auth) ``` ### Esforço Fixe um [nível de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) do Claude para todas as requisições com `fixedEffort:`. Ele tem precedência sobre as dicas de raciocínio por requisição do framework. Os níveis de raciocínio nomeados do framework vão até high; para solicitar mais esforço em uma única requisição, passe um nível de raciocínio personalizado com o nome do esforço do Claude (`.custom("xhigh")` ou `.custom("max")`), que é mapeado diretamente. Quando nenhum esforço é enviado, a API usa o nível padrão do modelo, que varia de acordo com o modelo (consulte [Níveis de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#effort-levels)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth, fixedEffort: .xhigh) ``` O nível deve ser um que o modelo aceite. Cada `ClaudeModel` declara quais dos cinco níveis (`low`, `medium`, `high`, `xhigh`, `max`) seu modelo aceita, se houver: alguns modelos não aceitam esforço de forma alguma. ### Quando usar o Claude versus o modelo no dispositivo O modelo no dispositivo da Apple é rápido, privado e disponível offline, mas é dimensionado para tarefas leves. Escale para o Claude quando precisar de contexto maior, raciocínio de fronteira ou ferramentas do lado do servidor, como busca na web e execução de código. Como ambos usam a mesma API `LanguageModelSession`, você pode alternar trocando o argumento `model:`. ## Autenticação Defina a credencial com o parâmetro `auth:`. Use `.appAttest` para distribuir sem um back end, `.proxied` para rotear requisições pelo seu próprio back end ou `.apiKey` para iterar durante o desenvolvimento. ### App Attest Cada instalação do seu aplicativo usa o serviço [App Attest](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity) da Apple para provar que é uma compilação genuína e não modificada do aplicativo que você registrou. A Anthropic então emite para o dispositivo um token de acesso de curta duração que cobra o uso do seu workspace. O aplicativo não inclui nenhuma chave de API, e não há nenhum proxy para você operar. A autenticação com App Attest está disponível apenas quando seu aplicativo chama a Claude API diretamente. Ela não está disponível por meio do Amazon Bedrock, Google Cloud ou Microsoft Foundry. Para distribuir sem executar um back end, use `.appAttest`: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .appAttest(clientID: "clid_...") ) ``` O App Attest requer um dispositivo físico. O Simulator, e hardware sem um Secure Enclave, não conseguem executar o App Attest. Use `.apiKey` enquanto itera no Simulator e `.appAttest` ao executar em um dispositivo. Para configurar o App Attest, você precisa do seu Apple Developer Team ID e da função de admin, owner ou primary owner na sua organização. Configure seu projeto Xcode e registre seu aplicativo no [Claude Console](https://platform.claude.com/): 1. No Xcode, adicione a capability **App Attest** ao target do seu aplicativo em **Signing & Capabilities**. 2. No Claude Console, acesse a página [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Cada integração de aplicativo pertence a um workspace. Selecione o workspace desejado no seletor de workspace na barra lateral. 3. Clique em **Create app integration** e insira um nome, seu Apple Developer Team ID e um ou mais bundle IDs (até 32). 4. Copie o client ID (`clid_...`) da aba **Overview** da integração e passe-o para a configuração do Claude no seu aplicativo. Na primeira vez que seu aplicativo usa o Claude em um dispositivo, o aplicativo solicita um desafio à Anthropic, atesta o dispositivo com o `DCAppAttestService` da Apple e troca a atestação verificada por um token de acesso. O pacote Claude for Foundation Models executa esse fluxo automaticamente e solicita novos tokens à medida que expiram; não há código de atestação para você escrever. Os tokens têm escopo restrito ao seu workspace, expiram após uma hora e autorizam apenas chamadas à [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create). Eles não carregam nenhuma identidade de usuário final: o App Attest identifica seu aplicativo, não a pessoa que o utiliza, portanto trate qualquer lógica por usuário no seu aplicativo. Para interromper um aplicativo comprometido ou desativado, revogue sua integração. No Claude Console, acesse a página [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Cada integração de aplicativo pertence a um workspace. No seletor de workspace na barra lateral, selecione o workspace que contém a integração. Selecione a integração e clique em **Revoke**, depois confirme. Revogar uma integração revoga seus tokens pendentes, e seus dispositivos registrados não podem mais solicitar novos tokens. A revogação é permanente, portanto crie uma nova integração de aplicativo para restaurar o acesso. ### Proxy (produção) Para produção, roteie as requisições pelo seu próprio back end com `.proxied`. O relay em `baseURL` adiciona a credencial da Claude API no lado do servidor, de modo que o app não distribui nenhuma chave. Os `headers` que você fornece são enviados em cada requisição para que seu proxy possa autorizar o chamador. Passe `[:]` se ele não precisar de nenhum: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .proxied(headers: ["X-App-Token": "..."]), baseURL: URL(string: "https://api.yourapp.com/claude")! ) ``` Seu proxy recebe requisições padrão da [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create), anexa o cabeçalho `x-api-key` e as encaminha para `https://api.anthropic.com`. ### Chave de API (desenvolvimento) Passe uma chave de API diretamente durante o desenvolvimento: ```swift ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY")) ``` Uma chave embutida em um app pode ser extraída do binário distribuído, e qualquer pessoa que a extraia pode fazer requisições cobradas na sua conta. Use `.apiKey` apenas para desenvolvimento e mude para App Attest ou um proxy antes do lançamento. ## Streaming `streamResponse(to:)` retorna a resposta de forma incremental. Cada elemento é um snapshot cumulativo da resposta até o momento, não um delta: ```swift let stream = session.streamResponse(to: "Summarize today's top science stories.") for try await partial in stream { print(partial.content) } ``` ## Saída estruturada Anote um tipo com `@Generable` e solicite-o com `generating:`. O modelo retorna um valor desse tipo por meio de [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs): ```swift @Generable struct Trip { @Guide(description: "Destination city") var destination: String @Guide(description: "Length in days") var days: Int } let response = try await session.respond(to: "Plan a trip to Tokyo.", generating: Trip.self) print(response.content.destination) ``` A saída estruturada requer um modelo cujas capacidades a incluam (todas as constantes compiladas incluem). Se o modelo escolhido não incluir, o pacote lança `LanguageModelError.unsupportedGenerationGuide` em vez de degradar silenciosamente. ## Uso de ferramentas ### Ferramentas do lado do cliente O array `tools:` do framework funciona sem alterações. Faça seus tipos conformarem a `Tool`, passe-os para `LanguageModelSession`, e o framework os invoca no dispositivo quando o Claude os chama. Consulte [Uso de ferramentas com o Claude](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview). ```swift let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()]) ``` ### Ferramentas do lado do servidor As [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) (busca na web, web fetch e execução de código) são executadas na infraestrutura da Anthropic em uma única viagem de ida e volta, sem nada para o framework invocar no dispositivo. Configure-as para cada modelo com `serverTools:`: ```swift let model = ClaudeLanguageModel( name: .sonnet5, auth: auth, serverTools: [ .webSearch(maxUses: 5), .codeExecution, ] ) ``` `.webSearch` e `.webFetch` aceitam os opcionais `allowedDomains`, `blockedDomains` e `maxUses`. A atividade das ferramentas de servidor aparece na transcrição como segmentos personalizados `ClaudeServerToolSegment`. `serverTools` é configurado em `ClaudeLanguageModel` e não em `LanguageModelSession` porque o tipo de sessão é da Apple. Para usar conjuntos diferentes de ferramentas de servidor para cada conversa, construa múltiplas instâncias de `ClaudeLanguageModel`. ## Imagens Modelos cujas capacidades incluem entrada de imagem declaram a capacidade de visão do framework. Passe conteúdo de imagem pela API de sessão padrão do framework; o pacote o converte para o formato de imagem da Claude API. Consulte [Visão](https://platform.claude.com/docs/pt-BR/build-with-claude/vision) para os requisitos de imagem. ## Tratamento de erros O pacote mapeia os erros da Claude API para os casos de `LanguageModelError` da Apple quando há um adequado: estouro da janela de contexto aparece como `.contextSizeExceeded`, HTTP 429 como `.rateLimited`, uma requisição que ultrapassa o timeout configurado como `.timeout`. Erros do provedor sem equivalente no framework aparecem como `ClaudeError`. Use pattern matching para conduzir os fluxos do produto: ```swift do { let response = try await session.respond(to: prompt) print(response.content) } catch ClaudeError.missingCredential { // Solicita uma chave de API. } catch let error as LanguageModelError { // Erros no formato do framework (limites de taxa, guardrails, tamanho do contexto, decodificação). } catch { // Erros de transporte. } ``` Um padrão comum é capturar `.rateLimited` e recorrer ao `SystemLanguageModel` para aquele turno, enfileirar a requisição ou exibir uma opção de tentar novamente. ## Suporte a recursos O pacote expõe as capacidades da Messages API que o protocolo de provedor do Foundation Models consegue expressar. Recursos sem representação no protocolo da Apple não estão disponíveis por meio dele, incluindo: * Controles de cache de prompt (o pacote aplica cache de prompt automaticamente; o TTL do cache e o posicionamento de breakpoints não são configuráveis) * Sequências de parada * Processamento em lote * Files API * Contagem de tokens * Cabeçalhos beta ## Recursos adicionais | Referência | Abrange | | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | [Documentação do Apple Foundation Models](https://developer.apple.com/documentation/foundationmodels) | `LanguageModelSession`, `@Generable`, `Transcript`, `Tool` e o restante da superfície do framework | | [`ClaudeForFoundationModels` no GitHub](https://github.com/anthropics/ClaudeForFoundationModels) | Código-fonte, o exemplo executável e o rastreador de issues | | [Referência da Claude API](https://platform.claude.com/docs/pt-BR/api/overview) | A Messages API subjacente | O pacote é licenciado sob Apache 2.0. Relatos de bugs são bem-vindos por meio de issues no GitHub. Pull requests externos não estão sendo aceitos durante o período beta.