Apple Foundation Models

Claude for Foundation Models ist ein Swift-Paket, das Claude als serverseitiges Sprachmodell in Apples Foundation Models Framework verfügbar macht. Das Paket macht Claude konform zum LanguageModel-Protokoll des Frameworks, sodass du es mit derselben LanguageModelSession-API steuerst, die du für Apples On-Device-Modell verwendest: respond(to:), Streaming, geführte Generierung und Tool-Aufrufe funktionieren alle auf dieselbe Weise.

Anfragen gehen direkt von deiner App an die Claude API; Apple befindet sich nicht im Anfragepfad und sieht weder Prompts noch Antworten. Die Nutzung wird deinem Anthropic-Konto zu den Standard-API-Preisen in Rechnung gestellt, daher benötigt deine Organisation ein verfügbares Guthaben oder eine aktive Zahlungsmethode. Deine App entscheidet, wann Claude und wann Apples On-Device-Modell verwendet wird: Übergib jeder Session das Modell, das du möchtest.

Voraussetzungen

• iOS 27, macOS 27, visionOS 27 oder watchOS 27 (alle in Beta): die OS-Versionen, deren Foundation Models Framework serverseitige Sprachmodelle unterstützt
• Xcode 27 (Beta)
• Ein Claude API-Key aus der Claude Console für die Entwicklung. Siehe Authentifizierung für Produktionsoptionen.

Das Paket installieren

Füge das Paket zu deiner Package.swift hinzu:

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

Oder in Xcode: File > Add Package Dependencies… und gib die Repository-URL ein.

Füge dann ClaudeForFoundationModels zu den Abhängigkeiten deines Targets hinzu und importiere es zusammen mit FoundationModels:

import FoundationModels
import ClaudeForFoundationModels

Schnellstart

ClaudeLanguageModel ist der Einstiegspunkt. Übergib es an LanguageModelSession und verwende die Session genau so, wie du es mit jedem anderen Foundation-Models-Provider tun würdest:

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)

Der Initializer akzeptiert außerdem baseURL (Standard https://api.anthropic.com), timeout und serverTools (siehe Serverseitige Tools).

Als vollständiges, funktionierendes Programm enthält das Repository Examples/ClaudeExample, ein ausführbares Kommandozeilen-Target, das einen Chat-Turn ins Terminal streamt, mit einem --search-Flag, das serverseitige Websuche für den Turn aktiviert. Die Ausführung erfordert einen macOS-27-Host.

Ein Modell auswählen

Modellbezeichner sind Werte von ClaudeModel. Verwende eine einkompilierte Konstante oder konstruiere eine mit expliziten Fähigkeiten für eine ID, die noch nicht einkompiliert ist (siehe Fähigkeiten):

ClaudeLanguageModel(name: .opus5, auth: auth)

Konstanten spiegeln API-Modell-IDs wider (.opus5 ist claude-opus-5) und tragen die Fähigkeiten des jeweiligen Modells. Neue Modelle werden als neue Konstanten in Paket-Releases ausgeliefert; sieh dir ClaudeModel in Xcode für die aktuelle Liste an und die Modellübersicht, um Modelle zu vergleichen.

Fähigkeiten

Jedes ClaudeModel deklariert, was es akzeptiert: Sampling-Parameter, Effort-Level, adaptives Denken, strukturierte Ausgabe und Bildeingabe. Das Paket nutzt dies, um zu bestimmen, welche Anfragefelder gesendet werden, denn das Senden eines Feldes, das ein Modell ablehnt, ist ein harter Fehler. Die Konstanten tragen die richtigen Fähigkeiten. Für eine ID, die nicht einkompiliert ist, deklariere, was das Modell akzeptiert (es gibt bewusst keine Kurzform, die rät):

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

Effort

Lege mit fixedEffort: ein Claude-„effort level“ (Aufwandsstufe) für jede Anfrage fest. Es hat Vorrang vor den anfragebezogenen Reasoning-Hinweisen des Frameworks. Die benannten Reasoning-Level des Frameworks enden bei high; um stattdessen für eine einzelne Anfrage mehr Effort anzufordern, übergib ein benutzerdefiniertes Reasoning-Level, das den Claude-Effort benennt (.custom("xhigh") oder .custom("max")), was direkt abgebildet wird. Die API verwendet standardmäßig high, wenn kein Effort gesendet wird:

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

Das Level muss eines sein, das das Modell akzeptiert. Jedes ClaudeModel deklariert, welche der fünf Level (low, medium, high, xhigh, max) sein Modell annimmt, falls überhaupt: Manche Modelle akzeptieren gar keinen Effort.

Wann Claude und wann das On-Device-Modell verwenden

Apples On-Device-Modell ist schnell, privat und offline verfügbar, aber für leichtgewichtige Aufgaben dimensioniert. Eskaliere zu Claude, wenn du ein größeres Kontextfenster, Frontier-Reasoning oder serverseitige Tools wie Websuche und Codeausführung benötigst. Da beide dieselbe LanguageModelSession-API verwenden, kannst du durch Austauschen des model:-Arguments wechseln.

Authentifizierung

Setze die Anmeldedaten mit dem Parameter auth:. Verwende .appAttest, um ohne Backend auszuliefern, .proxied, um Anfragen über dein eigenes Backend zu leiten, oder .apiKey, um während der Entwicklung zu iterieren.

App Attest

Jede Installation deiner App nutzt Apples Dienst App Attest, um nachzuweisen, dass es sich um einen echten, unveränderten Build der von dir registrierten App handelt. Anthropic stellt dem Gerät anschließend ein kurzlebiges „access token“ (Zugriffstoken) aus, über das die Nutzung deinem Workspace in Rechnung gestellt wird. Die App wird ohne API-Key ausgeliefert, und es gibt keinen Proxy, den du betreiben musst.

Die App-Attest-Authentifizierung ist nur verfügbar, wenn deine App die Claude API direkt aufruft. Sie ist nicht über Amazon Bedrock, Google Cloud oder Microsoft Foundry verfügbar.

Um ohne den Betrieb eines Backends auszuliefern, verwende .appAttest:

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

Um App Attest einzurichten, benötigst du deine Apple Developer Team ID sowie die Rolle „Admin“, „Owner“ oder „Primary Owner“ in deiner Organisation. Konfiguriere dein Xcode-Projekt und registriere deine App in der Claude Console:

1. Füge in Xcode deinem App-Target unter Signing & Capabilities die Capability App Attest hinzu.
2. Öffne in den Einstellungen deines Workspace in der Claude Console App integrations.
3. Klicke auf Create app integration und gib einen Namen, deine Apple Developer Team ID sowie eine oder mehrere Bundle-IDs (bis zu 32) ein.
4. Kopiere die Client-ID (clid_...) aus dem Tab Overview der Integration und übergib sie an die Claude-Konfiguration deiner App.

Wenn deine App Claude zum ersten Mal auf einem Gerät verwendet, fordert die App eine Challenge von Anthropic an, attestiert das Gerät mit Apples DCAppAttestService und tauscht die verifizierte Attestierung gegen ein „access token“ (Zugriffstoken) ein. Das Paket Claude for Foundation Models führt diesen Ablauf automatisch aus und fordert neue Token an, sobald sie ablaufen; du musst keinen Attestierungscode schreiben.

Token sind auf deinen Workspace beschränkt, laufen nach einer Stunde ab und autorisieren ausschließlich Aufrufe der Messages API. Sie enthalten keine Endnutzer-Identität: App Attest identifiziert deine App, nicht die Person, die sie verwendet. Behandle daher jegliche nutzerspezifische Logik in deiner App.

Um eine kompromittierte oder eingestellte App zu stoppen, widerrufe ihre Integration: Öffne in den Einstellungen deines Workspace in der Claude Console App integrations, wähle die Integration aus, klicke auf Revoke und bestätige anschließend. Das Widerrufen einer Integration widerruft ihre ausstehenden Token, und ihre registrierten Geräte können keine neuen mehr anfordern. Der Widerruf ist dauerhaft, erstelle also eine neue App-Integration, um den Zugriff wiederherzustellen.

Proxy (Produktion)

Leite Anfragen für die Produktion mit .proxied über dein eigenes Backend. Das Relay unter baseURL fügt die Claude-API-Anmeldedaten serverseitig hinzu, sodass die App keinen Key ausliefert. Die von dir angegebenen headers werden bei jeder Anfrage gesendet, damit dein Proxy den Aufrufer autorisieren kann. Übergib [:], wenn er keine benötigt:

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

Dein Proxy empfängt standardmäßige Messages API-Anfragen, fügt den x-api-key-Header hinzu und leitet sie an https://api.anthropic.com weiter.

API-Key (Entwicklung)

Übergib während der Entwicklung direkt einen API-Key:

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

Streaming

streamResponse(to:) gibt die Antwort inkrementell zurück. Jedes Element ist ein kumulativer Snapshot der bisherigen Antwort, kein Delta:

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

Strukturierte Ausgabe

Annotiere einen Typ mit @Generable und fordere ihn mit generating: an. Das Modell gibt über strukturierte Ausgaben einen Wert dieses Typs zurück:

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

Strukturierte Ausgabe erfordert ein Modell, dessen Fähigkeiten sie einschließen (alle einkompilierten Konstanten tun dies). Falls das gewählte Modell dies nicht tut, wirft das Paket LanguageModelError.unsupportedGenerationGuide, anstatt stillschweigend zu degradieren.

Tool-Nutzung

Clientseitige Tools

Das tools:-Array des Frameworks funktioniert unverändert. Mache deine Typen konform zu Tool, übergib sie an LanguageModelSession, und das Framework ruft sie auf dem Gerät auf, wenn Claude sie aufruft. Siehe Tool-Nutzung mit Claude.

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

Serverseitige Tools

Server-Tools (Websuche, Web-Fetch und Codeausführung) laufen auf Anthropics Infrastruktur innerhalb eines einzigen Roundtrips, ohne dass das Framework etwas auf dem Gerät aufrufen muss. Konfiguriere sie für jedes Modell mit serverTools::

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

.webSearch und .webFetch akzeptieren optional allowedDomains, blockedDomains und maxUses. Server-Tool-Aktivität erscheint im Transkript als benutzerdefinierte ClaudeServerToolSegment-Segmente.

Bilder

Modelle, deren Fähigkeiten Bildeingabe einschließen, deklarieren die Vision-Fähigkeit des Frameworks. Übergib Bildinhalte über die Standard-Session-API des Frameworks; das Paket konvertiert sie in das Bildformat der Claude API. Siehe Vision für Bildanforderungen.

Fehlerbehandlung

Das Paket bildet Claude-API-Fehler auf Apples LanguageModelError-Fälle ab, wo einer passt: Ein Überlauf des Kontextfensters erscheint als .contextSizeExceeded, HTTP 429 als .rateLimited, eine Anfrage, die das konfigurierte Timeout überschreitet, als .timeout. Provider-Fehler ohne Framework-Äquivalent erscheinen als ClaudeError. Nutze Pattern-Matching, um Produktabläufe zu steuern:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Prompt for an API key.
} catch let error as LanguageModelError {
  // Framework-shaped errors (rate limits, guardrails, context length, decoding).
} catch {
  // Transport errors.
}

Ein gängiges Muster ist, .rateLimited abzufangen und für diesen Turn auf SystemLanguageModel zurückzufallen, die Anfrage in eine Warteschlange zu stellen oder eine Wiederholungsmöglichkeit anzuzeigen.

Funktionsunterstützung

Das Paket stellt die Messages-API-Fähigkeiten bereit, die das Foundation-Models-Provider-Protokoll ausdrücken kann. Funktionen ohne Repräsentation in Apples Protokoll sind darüber nicht verfügbar, darunter:

• Steuerung des Prompt-Cachings (das Paket wendet Prompt-Caching automatisch an; Cache-TTL und Breakpoint-Platzierung sind nicht konfigurierbar)
• Stop-Sequenzen
• Batch-Verarbeitung
• Files API
• Token-Zählung
• Beta-Header

Zusätzliche Ressourcen

Das Paket ist unter Apache 2.0 lizenziert. Fehlerberichte sind über GitHub Issues willkommen. Externe Pull Requests werden während der Beta-Phase nicht angenommen.