Apple Foundation Models

Claude for Foundation Models est un package Swift qui rend Claude disponible en tant que modèle de langage côté serveur dans le framework Foundation Models d'Apple. Le package rend Claude conforme au protocole LanguageModel du framework, de sorte que vous le pilotez avec la même API LanguageModelSession que vous utilisez pour le modèle sur appareil d'Apple : respond(to:), le streaming, la génération guidée et l'appel d'outils fonctionnent tous de la même manière.

Les requêtes vont directement de votre application à l'API Claude ; Apple n'est pas dans le chemin de la requête et ne voit ni les invites ni les réponses. L'utilisation est facturée à votre compte Anthropic selon la tarification API standard, donc votre organisation a besoin d'un solde de crédit disponible ou d'une méthode de facturation active. Votre application décide quand utiliser Claude et quand utiliser le modèle sur appareil d'Apple : passez le modèle que vous souhaitez à chaque session.

Prérequis

• iOS 27, macOS 27, visionOS 27 ou watchOS 27 (tous en bêta) : les versions d'OS dont le framework Foundation Models prend en charge les modèles de langage côté serveur
• Xcode 27 (bêta)
• Une clé API Claude depuis la Claude Console pour le développement. Consultez Authentification pour les options de production.

Installer le package

Ajoutez le package à votre Package.swift :

dependencies: [
  .package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0")
]

Ou dans Xcode : File > Add Package Dependencies… et entrez l'URL du dépôt.

Ajoutez ensuite ClaudeForFoundationModels aux dépendances de votre cible et importez-le aux côtés de FoundationModels :

import FoundationModels
import ClaudeForFoundationModels

Démarrage rapide

ClaudeLanguageModel est le point d'entrée. Passez-le à LanguageModelSession et utilisez la session exactement comme vous le feriez avec n'importe quel fournisseur 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)

L'initialiseur accepte également baseURL (par défaut https://api.anthropic.com), timeout et serverTools (voir Outils côté serveur).

Pour un programme fonctionnel complet, le dépôt inclut Examples/ClaudeExample, une cible en ligne de commande exécutable qui diffuse un tour de conversation vers le terminal, avec un indicateur --search qui active la recherche web côté serveur pour le tour. Son exécution nécessite un hôte macOS 27.

Choisir un modèle

Les identifiants de modèle sont des valeurs de ClaudeModel. Utilisez une constante compilée, ou construisez-en une avec des capacités explicites pour un ID qui n'est pas encore compilé (voir Capacités) :

ClaudeLanguageModel(name: .opus5, auth: auth)

Les constantes reflètent les ID de modèle de l'API (.opus5 est claude-opus-5) et portent les capacités de chaque modèle. Les nouveaux modèles sont livrés sous forme de nouvelles constantes dans les versions du package ; consultez ClaudeModel dans Xcode pour la liste actuelle, et l'aperçu des modèles pour comparer les modèles.

Capacités

Chaque ClaudeModel déclare ce qu'il accepte : paramètres d'échantillonnage, niveaux d'effort, réflexion adaptative, sortie structurée et entrée d'image. Le package utilise cela pour déterminer quels champs de requête envoyer, car envoyer un champ qu'un modèle rejette est une erreur fatale. Les constantes portent les bonnes capacités. Pour un ID qui n'est pas compilé, déclarez ce que le modèle accepte (il n'y a délibérément aucun raccourci qui devine) :

let model = ClaudeModel(
  id: "claude-experimental-x",
  capabilities: .init(samplingParams: false, effortLevels: [.low, .high])
)
ClaudeLanguageModel(name: model, auth: auth)

Effort

Fixez un niveau d'effort Claude pour chaque requête avec fixedEffort:. Il a priorité sur les indices de raisonnement par requête du framework. Les niveaux de raisonnement nommés du framework s'arrêtent à high ; pour demander plus d'effort pour une seule requête à la place, passez un niveau de raisonnement personnalisé nommant l'effort Claude (.custom("xhigh") ou .custom("max")), qui correspond directement. L'API utilise high par défaut lorsqu'aucun effort n'est envoyé :

ClaudeLanguageModel(name: .opus5, auth: auth, fixedEffort: .xhigh)

Le niveau doit être un que le modèle accepte. Chaque ClaudeModel déclare lequel des cinq niveaux (low, medium, high, xhigh, max) son modèle prend, le cas échéant : certains modèles n'acceptent pas du tout l'effort.

Quand utiliser Claude par rapport au modèle sur appareil

Le modèle sur appareil d'Apple est rapide, privé et disponible hors ligne, mais il est dimensionné pour des tâches légères. Passez à Claude lorsque vous avez besoin d'un contexte plus large, d'un raisonnement de pointe ou d'outils côté serveur tels que la recherche web et l'exécution de code. Comme les deux utilisent la même API LanguageModelSession, vous pouvez basculer en échangeant l'argument model:.

Authentification

Définissez les identifiants avec le paramètre auth:. Utilisez .appAttest pour livrer sans back end, .proxied pour acheminer les requêtes via votre propre back end, ou .apiKey pour itérer pendant le développement.

App Attest

Chaque installation de votre application utilise le service App Attest d'Apple pour prouver qu'il s'agit d'une version authentique et non modifiée de l'application que vous avez enregistrée. Anthropic délivre ensuite à l'appareil un « access token » (jeton d'accès) de courte durée qui facture l'utilisation à votre espace de travail. L'application n'embarque aucune clé API, et vous n'avez aucun proxy à exploiter.

L'authentification App Attest n'est disponible que lorsque votre application appelle directement la Claude API. Elle n'est pas disponible via Amazon Bedrock, Google Cloud ou Microsoft Foundry.

Pour livrer sans exécuter de back end, utilisez .appAttest :

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

Pour configurer App Attest, vous avez besoin de votre Apple Developer Team ID et du rôle d'administrateur, de propriétaire ou de propriétaire principal dans votre organisation. Configurez votre projet Xcode et enregistrez votre application dans la Claude Console :

1. Dans Xcode, ajoutez la capacité App Attest à la cible de votre application sous Signing & Capabilities.
2. Dans les paramètres de votre espace de travail dans la Claude Console, ouvrez App integrations.
3. Cliquez sur Create app integration et saisissez un nom, votre Apple Developer Team ID et un ou plusieurs identifiants de bundle (jusqu'à 32).
4. Copiez l'identifiant client (clid_...) depuis l'onglet Overview de l'intégration et transmettez-le à la configuration Claude de votre application.

La première fois que votre application utilise Claude sur un appareil, l'application demande un défi (challenge) à Anthropic, atteste l'appareil avec le DCAppAttestService d'Apple, puis échange l'attestation vérifiée contre un jeton d'accès (access token). Le package Claude for Foundation Models exécute ce flux automatiquement et demande de nouveaux jetons à mesure qu'ils expirent ; vous n'avez aucun code d'attestation à écrire.

Les jetons sont limités à votre espace de travail, expirent au bout d'une heure et n'autorisent que les appels à la Messages API. Ils ne portent aucune identité d'utilisateur final : App Attest identifie votre application, et non la personne qui l'utilise ; gérez donc toute logique propre à chaque utilisateur dans votre application.

Pour arrêter une application compromise ou retirée, révoquez son intégration : dans les paramètres de votre espace de travail dans la Claude Console, ouvrez App integrations (Intégrations d'applications), sélectionnez l'intégration, puis cliquez sur Revoke (Révoquer), et confirmez. La révocation d'une intégration révoque ses jetons en cours de validité, et ses appareils enregistrés ne peuvent plus en demander de nouveaux. La révocation est définitive ; créez donc une nouvelle intégration d'application pour rétablir l'accès.

Proxy (production)

Pour la production, acheminez les requêtes via votre propre back end avec .proxied. Le relais à baseURL ajoute les identifiants de l'API Claude côté serveur, de sorte que l'application ne livre aucune clé. Les headers que vous fournissez sont envoyés à chaque requête afin que votre proxy puisse autoriser l'appelant. Passez [:] s'il n'en a besoin d'aucun :

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .proxied(headers: ["X-App-Token": "..."]),
  baseURL: URL(string: "https://api.yourapp.com/claude")!
)

Votre proxy reçoit des requêtes API Messages standard, attache l'en-tête x-api-key et les transfère à https://api.anthropic.com.

Clé API (développement)

Passez une clé API directement pendant le développement :

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

Streaming

streamResponse(to:) renvoie la réponse de manière incrémentale. Chaque élément est un instantané cumulatif de la réponse jusqu'à présent, et non un delta :

let stream = session.streamResponse(to: "Summarize today's top science stories.")
for try await partial in stream {
  print(partial.content)
}

Sortie structurée

Annotez un type avec @Generable et demandez-le avec generating:. Le modèle renvoie une valeur de ce type via les sorties structurées :

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

La sortie structurée nécessite un modèle dont les capacités l'incluent (toutes les constantes compilées le font). Si le modèle choisi ne le fait pas, le package lève LanguageModelError.unsupportedGenerationGuide plutôt que de se dégrader silencieusement.

Utilisation d'outils

Outils côté client

Le tableau tools: du framework fonctionne sans modification. Rendez vos types conformes à Tool, passez-les à LanguageModelSession, et le framework les invoque sur l'appareil lorsque Claude les appelle. Consultez Utilisation d'outils avec Claude.

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

Outils côté serveur

Les outils serveur (recherche web, récupération web et exécution de code) s'exécutent sur l'infrastructure d'Anthropic en un seul aller-retour, sans rien à invoquer par le framework sur l'appareil. Configurez-les pour chaque modèle avec serverTools: :

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

.webSearch et .webFetch acceptent les paramètres optionnels allowedDomains, blockedDomains et maxUses. L'activité des outils serveur apparaît dans la transcription sous forme de segments personnalisés ClaudeServerToolSegment.

Images

Les modèles dont les capacités incluent l'entrée d'image déclarent la capacité de vision du framework. Passez le contenu d'image via l'API de session standard du framework ; le package le convertit au format d'image de l'API Claude. Consultez Vision pour les exigences relatives aux images.

Gestion des erreurs

Le package mappe les erreurs de l'API Claude sur les cas LanguageModelError d'Apple lorsqu'un correspond : le dépassement de la fenêtre de contexte apparaît comme .contextSizeExceeded, HTTP 429 comme .rateLimited, une requête dépassant le délai d'expiration configuré comme .timeout. Les erreurs du fournisseur sans équivalent dans le framework apparaissent comme ClaudeError. Utilisez la correspondance de motifs pour piloter les flux produit :

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Demande une clé API.
} catch let error as LanguageModelError {
  // Erreurs liées au framework (limites de débit, garde-fous, longueur de contexte, décodage).
} catch {
  // Erreurs de transport.
}

Un modèle courant consiste à intercepter .rateLimited et à se rabattre sur SystemLanguageModel pour ce tour, à mettre la requête en file d'attente, ou à présenter une option de nouvelle tentative.

Prise en charge des fonctionnalités

Le package expose les capacités de l'API Messages que le protocole du fournisseur Foundation Models peut exprimer. Les fonctionnalités sans représentation dans le protocole d'Apple ne sont pas disponibles via celui-ci, notamment :

• Les contrôles de mise en cache des prompts (le package applique la mise en cache des prompts automatiquement ; le TTL du cache et le placement des points d'arrêt ne sont pas configurables)
• Les séquences d'arrêt
• Le traitement par lots
• L'API Files
• Le comptage de tokens
• Les en-têtes bêta

Ressources supplémentaires

Le package est sous licence Apache 2.0. Les rapports de bogues sont les bienvenus via les problèmes GitHub. Les pull requests externes ne sont pas acceptées pendant la période bêta.