--- title: Apple Foundation Models url: https://platform.claude.com/docs/de/cli-sdks-libraries/libraries/apple-foundation-models description: Verwende Claude auf Apple-Plattformen über das Foundation Models Framework mit dem Swift-Paket Claude for Foundation Models. --- [Claude for Foundation Models](https://github.com/anthropics/ClaudeForFoundationModels) ist ein Swift-Paket, das Claude als serverseitiges Sprachmodell in Apples [Foundation Models](https://developer.apple.com/documentation/foundationmodels) 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](https://platform.claude.com/docs/de/about-claude/pricing) 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. **Beta.** Dieses Paket zielt auf die serverseitige Sprachmodell-API von Foundation Models ab, die in den OS-27-Betas eingeführt wurde. APIs können sich während der Beta ändern. Claude for Foundation Models ist **kein** universeller Messages-API-Client. Seine öffentliche Oberfläche besteht aus der Foundation-Models-Provider-Konformität sowie den Konfigurationstypen, die sie erreichen (`ClaudeLanguageModel`, `ClaudeModel`, `AuthMode`, `ClaudeServerTool`). Für direkten Zugriff auf die Messages API in einer anderen Sprache siehe die [Client SDKs](https://platform.claude.com/docs/de/cli-sdks-libraries/overview#client-sdks). ## 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](https://platform.claude.com/) für die Entwicklung. Siehe [Authentifizierung](https://platform.claude.com/docs/de/cli-sdks-libraries/libraries/apple-foundation-models#authentication) für Produktionsoptionen. ## Das Paket installieren Füge das Paket zu deiner `Package.swift` hinzu: ```swift 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`: ```swift 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: ```swift 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](https://platform.claude.com/docs/de/cli-sdks-libraries/libraries/apple-foundation-models#server-side-tools)). Als vollständiges, funktionierendes Programm enthält das Repository [`Examples/ClaudeExample`](https://github.com/anthropics/ClaudeForFoundationModels/tree/main/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](https://platform.claude.com/docs/de/cli-sdks-libraries/libraries/apple-foundation-models#capabilities)): ```swift ClaudeLanguageModel(name: .opus5_5, 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](https://platform.claude.com/docs/de/models/overview), um Modelle zu vergleichen. ### Fähigkeiten Jedes `ClaudeModel` deklariert, was es akzeptiert: Sampling-Parameter, Effort-Level, adaptives Nachdenken, 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): ```swift 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](https://platform.claude.com/docs/de/build-with-claude/effort) für jede Anfrage fest. Es hat Vorrang vor den Reasoning-Hinweisen des Frameworks pro Anfrage. 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")`) und direkt abgebildet wird. Wenn kein Effort gesendet wird, verwendet die API das Standard-Level des Modells, das sich je nach Modell unterscheidet (siehe [Effort-Level](https://platform.claude.com/docs/de/build-with-claude/effort#effort-levels)): ```swift ClaudeLanguageModel(name: .opus5_5, 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](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity), 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`: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .appAttest(clientID: "clid_...") ) ``` App Attest erfordert ein physisches Gerät. Der Simulator sowie Hardware ohne Secure Enclave können App Attest nicht durchführen. Verwende `.apiKey`, während du im Simulator iterierst, und `.appAttest`, wenn du auf einem Gerät ausführst. 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](https://platform.claude.com/): 1. Füge in Xcode deinem App-Target unter **Signing & Capabilities** die Capability **App Attest** hinzu. 2. Gehe in der Claude Console zur Seite [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Jede App-Integration gehört zu einem Workspace. Wähle den gewünschten Workspace in der Workspace-Auswahl in der Seitenleiste aus. 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](https://platform.claude.com/docs/de/api/messages/create). 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. Gehe in der Claude Console zur Seite [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Jede App-Integration gehört zu einem Workspace. Wähle in der Workspace-Auswahl in der Seitenleiste den Workspace aus, der die Integration enthält. Wähle die Integration aus, klicke auf **Revoke** und bestätige anschließend. Durch das Widerrufen einer Integration werden ihre ausstehenden Token widerrufen, 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: ```swift 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](https://platform.claude.com/docs/de/api/messages/create)-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: ```swift ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY")) ``` Ein in eine App gebündelter Key ist aus dem ausgelieferten Binary extrahierbar, und jeder, der ihn extrahiert, kann Anfragen stellen, die deinem Konto in Rechnung gestellt werden. Verwende `.apiKey` nur für die Entwicklung und wechsle vor der Veröffentlichung zu App Attest oder einem Proxy. ## Streaming `streamResponse(to:)` gibt die Antwort inkrementell zurück. Jedes Element ist ein kumulativer Snapshot der bisherigen Antwort, kein Delta: ```swift 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](https://platform.claude.com/docs/de/build-with-claude/structured-outputs) einen Wert dieses Typs zurück: ```swift @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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/overview). ```swift let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()]) ``` ### Serverseitige Tools [Server-Tools](https://platform.claude.com/docs/de/agents-and-tools/tool-use/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:`: ```swift 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. `serverTools` wird auf `ClaudeLanguageModel` statt auf `LanguageModelSession` konfiguriert, da der Session-Typ Apple gehört. Um für jede Konversation unterschiedliche Server-Tool-Sets zu verwenden, konstruiere mehrere `ClaudeLanguageModel`-Instanzen. ## 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](https://platform.claude.com/docs/de/build-with-claude/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: ```swift 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 | Referenz | Behandelt | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [Apple Foundation Models Dokumentation](https://developer.apple.com/documentation/foundationmodels) | `LanguageModelSession`, `@Generable`, `Transcript`, `Tool` und den Rest der Framework-Oberfläche | | [`ClaudeForFoundationModels` auf GitHub](https://github.com/anthropics/ClaudeForFoundationModels) | Quellcode, das ausführbare Beispiel und den Issue-Tracker | | [Claude API-Referenz](https://platform.claude.com/docs/de/api/overview) | Die zugrunde liegende Messages API | 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.