Apple Foundation Models

Claude for Foundation Models é um pacote Swift que torna Claude disponível como um modelo de linguagem do lado do servidor no framework Foundation Models da Apple. O pacote faz Claude estar em conformidade com o protocolo LanguageModel do framework, então 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 API do Claude; a Apple não está no caminho da requisição e não vê prompts ou respostas. O uso é cobrado na sua conta Anthropic com os preços padrão da API. Seu app decide quando usar Claude e quando usar o modelo no dispositivo da Apple: passe o modelo que você quiser para cada sessão.



Requisitos

• iOS 27, macOS 27, visionOS 27 ou watchOS 27 (todos em beta): as versões de SO cujo framework Foundation Models suporta 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 completo e funcional, o repositório inclui Examples/ClaudeExample, um target de linha de comando executável que transmite 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, ou construa uma com capacidades explícitas para um ID que ainda não está 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 nas 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 está 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 cada requisição 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 para uma única requisição, passe um nível de raciocínio personalizado nomeando o esforço do Claude (.custom("xhigh") ou .custom("max")), que mapeia 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 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 Claude quando você 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:.



Chave de API (desenvolvimento)

Passe uma chave de API diretamente durante o desenvolvimento:

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



Proxy (produção)

Para produção, roteie as requisições através do seu próprio back end com .proxied. O relay em baseURL adiciona a credencial da API do Claude do lado do servidor, então o app não é distribuído com 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.



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 através 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 estarem em conformidade com Tool, passe-os para LanguageModelSession, e o framework os invoca no dispositivo quando Claude os chama. Consulte Uso de ferramentas com Claude.

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



Ferramentas do lado do servidor

As ferramentas de servidor (busca na web, busca de páginas web e execução de código) são executadas na infraestrutura da Anthropic dentro de uma única 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 allowedDomains, blockedDomains e maxUses opcionais. 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 o conteúdo de imagem através da API de sessão padrão do framework; o pacote o converte para o formato de imagem da API do Claude. Consulte Visão para os requisitos de imagem.



Tratamento de erros

O pacote mapeia os erros da API do Claude para os casos de LanguageModelError da Apple quando há um correspondente: 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, comprimento de 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 nova tentativa.



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 através 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. Relatórios de bugs são bem-vindos através das issues do GitHub. Pull requests externos não estão sendo aceitos durante o período beta.