Apple Foundation Models

Claude for Foundation Models é um pacote Swift que disponibiliza o Claude como um modelo de linguagem do lado do servidor no framework Foundation Models 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, 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.

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 para desenvolvimento. Consulte Autenticação para opções de produção.

Instale o pacote

Adicione o pacote ao seu Package.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:

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:

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

Para um programa funcional completo, o repositório inclui 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):

ClaudeLanguageModel(name: .opus5, 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 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):

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 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 param em high; para solicitar mais esforço em uma única requisição, passe um nível de raciocínio personalizado nomeando o esforço do Claude (.custom("xhigh") ou .custom("max")), que é mapeado diretamente. A API usa high como padrão quando nenhum esforço é enviado:

ClaudeLanguageModel(name: .opus5, 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 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:

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .appAttest(clientID: "clid_...")
)

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:

1. No Xcode, adicione a capability App Attest ao target do seu aplicativo em Signing & Capabilities.
2. Nas configurações do seu workspace no Claude Console, abra App integrations.
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. 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: nas configurações do seu workspace no Claude Console, abra App integrations, 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. 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:

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, 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:

ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY"))

Streaming

streamResponse(to:) retorna a resposta de forma incremental. Cada elemento é um snapshot cumulativo da resposta até o momento, não um delta:

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:

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

let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()])

Ferramentas do lado do servidor

As ferramentas de servidor (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::

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.

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 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:

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

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.