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 estar em conformidade com o protocolo LanguageModel do framework, então você o utiliza com a mesma API LanguageModelSession que usa para o modelo on-device da Apple: respond(to:), streaming, geração guiada e chamadas de ferramentas funcionam 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 nem respostas. O uso é cobrado na sua conta da Anthropic de acordo com os preços padrão da API. Seu app decide quando usar o Claude e quando usar o modelo on-device 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 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.

Instalar 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 provider do Foundation Models:

import FoundationModels
import ClaudeForFoundationModels

let model = ClaudeLanguageModel(
  name: .sonnet4_6,
  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 macOS 27.

Escolhendo um modelo

Identificadores de modelo são valores de ClaudeModel. Use uma constante compilada, ou construa um com capacidades explícitas para um ID que ainda não está compilado (consulte Capacidades):

ClaudeLanguageModel(name: .opus4_8, auth: auth)

As constantes espelham os IDs de modelo da API (.opus4_8 é claude-opus-4-8) e carregam as capacidades de cada modelo. Novos modelos são disponibilizados como novas constantes em releases 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 decidir 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á 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, e é a única forma de solicitar .xhigh ou .max, porque os níveis de raciocínio do framework param em high. A API usa high como padrão quando nenhum esforço é enviado:

ClaudeLanguageModel(name: .opus4_8, 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 algum: alguns modelos não aceitam esforço de forma alguma.

Quando usar o Claude versus o modelo on-device

O modelo on-device da Apple é rápido, privado e funciona 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:.

Chave de API (desenvolvimento)

Passe uma chave de API diretamente durante o desenvolvimento:

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

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 o Claude os chama. Consulte Uso de ferramentas com o Claude.

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

Ferramentas do lado do servidor

Ferramentas de servidor (busca na web, busca de páginas web e execução de código) rodam na infraestrutura da Anthropic dentro de uma única ida e volta, sem nada para o framework invocar no dispositivo. Configure-as por modelo com serverTools::

let model = ClaudeLanguageModel(
  name: .sonnet4_6,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

.webSearch e .webFetch aceitam allowedDomains, blockedDomains e maxUses opcionais. A atividade de 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 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 requisitos de imagem.

Tratamento de erros

O pacote mapeia erros da API do Claude para os casos de LanguageModelError da Apple quando há correspondência: estouro da janela de contexto aparece como .contextSizeExceeded, HTTP 429 como .rateLimited, uma requisição além do timeout configurado como .timeout. Erros do provider sem equivalente no framework aparecem como ClaudeError. Use pattern matching para direcionar 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 relacionados ao framework (limites de taxa, guardrails, tamanho do contexto, decodificação).
} catch {
  // Erros de transporte.
}

Um padrão comum é capturar .rateLimited e fazer fallback para SystemLanguageModel naquele 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 provider 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
• Headers beta

Recursos adicionais

O pacote é licenciado sob Apache 2.0. Relatórios de bugs são bem-vindos através de issues no GitHub. Pull requests externos não estão sendo aceitos durante o período beta.