--- title: Apple Foundation Models url: https://platform.claude.com/docs/es/cli-sdks-libraries/libraries/apple-foundation-models description: Usa Claude en plataformas Apple a través del framework Foundation Models con el paquete Swift Claude for Foundation Models. --- [Claude for Foundation Models](https://github.com/anthropics/ClaudeForFoundationModels) es un paquete Swift que hace que Claude esté disponible como modelo de lenguaje del lado del servidor en el framework [Foundation Models](https://developer.apple.com/documentation/foundationmodels) de Apple. El paquete hace que Claude cumpla con el protocolo `LanguageModel` del framework, por lo que lo controlas con la misma API `LanguageModelSession` que usas para el modelo en el dispositivo de Apple: `respond(to:)`, streaming, generación guiada y llamadas a herramientas funcionan todos de la misma manera. Las solicitudes van directamente desde tu aplicación a la API de Claude; Apple no está en la ruta de la solicitud y no ve las indicaciones ni las respuestas. El uso se factura a tu cuenta de Anthropic según los [precios estándar de la API](https://platform.claude.com/docs/es/about-claude/pricing), por lo que tu organización necesita un saldo de crédito disponible o un método de facturación activo. Tu aplicación decide cuándo usar Claude y cuándo usar el modelo en el dispositivo de Apple: pasa el modelo que quieras a cada sesión. **Beta.** Este paquete está dirigido a la API de modelo de lenguaje del lado del servidor de Foundation Models introducida en las betas de OS 27. Las APIs podrían cambiar durante la beta. Claude for Foundation Models **no** es un cliente de la API de Messages de propósito general. Su superficie pública es la conformidad del proveedor de Foundation Models más los tipos de configuración que la alcanzan (`ClaudeLanguageModel`, `ClaudeModel`, `AuthMode`, `ClaudeServerTool`). Para acceso directo a la API de Messages en otro lenguaje, consulta los [SDKs de cliente](https://platform.claude.com/docs/es/cli-sdks-libraries/overview#client-sdks). ## Requisitos * iOS 27, macOS 27, visionOS 27 o watchOS 27 (todos en beta): las versiones de OS cuyo framework Foundation Models admite modelos de lenguaje del lado del servidor * Xcode 27 (beta) * Una clave de API de Claude de la [Claude Console](https://platform.claude.com/) para desarrollo. Consulta [Autenticación](https://platform.claude.com/docs/es/cli-sdks-libraries/libraries/apple-foundation-models#authentication) para opciones de producción. ## Instalar el paquete Agrega el paquete a tu `Package.swift`: ```swift dependencies: [ .package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0") ] ``` O en Xcode: **File** > **Add Package Dependencies…** e ingresa la URL del repositorio. Luego agrega `ClaudeForFoundationModels` a las dependencias de tu target e impórtalo junto con `FoundationModels`: ```swift import FoundationModels import ClaudeForFoundationModels ``` ## Inicio rápido `ClaudeLanguageModel` es el punto de entrada. Pásalo a `LanguageModelSession` y usa la sesión exactamente como lo harías con cualquier proveedor de Foundation Models: ```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) ``` El inicializador también acepta `baseURL` (por defecto `https://api.anthropic.com`), `timeout` y `serverTools` (consulta [Herramientas del lado del servidor](https://platform.claude.com/docs/es/cli-sdks-libraries/libraries/apple-foundation-models#server-side-tools)). Para un programa funcional completo, el repositorio incluye [`Examples/ClaudeExample`](https://github.com/anthropics/ClaudeForFoundationModels/tree/main/Examples/ClaudeExample), un target de línea de comandos ejecutable que transmite un turno de chat a la terminal, con una bandera `--search` que habilita la búsqueda web del lado del servidor para el turno. Ejecutarlo requiere un host macOS 27. ## Elegir un modelo Los identificadores de modelo son valores de `ClaudeModel`. Usa una constante compilada, o construye una con capacidades explícitas para un ID que aún no esté compilado (consulta [Capacidades](https://platform.claude.com/docs/es/cli-sdks-libraries/libraries/apple-foundation-models#capabilities)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth) ``` Las constantes reflejan los IDs de modelo de la API (`.opus5` es `claude-opus-5`) y llevan las capacidades de cada modelo. Los nuevos modelos se envían como nuevas constantes en las versiones del paquete; revisa `ClaudeModel` en Xcode para la lista actual, y la [Descripción general de modelos](https://platform.claude.com/docs/es/models/overview) para comparar modelos. ### Capacidades Cada `ClaudeModel` declara lo que acepta: parámetros de muestreo, niveles de esfuerzo, pensamiento adaptativo, salida estructurada y entrada de imágenes. El paquete usa esto para determinar qué campos de solicitud enviar, porque enviar un campo que un modelo rechaza es un error grave. Las constantes llevan las capacidades correctas. Para un ID que no está compilado, declara lo que el modelo acepta (deliberadamente no hay una abreviatura que adivine): ```swift let model = ClaudeModel( id: "claude-experimental-x", capabilities: .init(samplingParams: false, effortLevels: [.low, .high]) ) ClaudeLanguageModel(name: model, auth: auth) ``` ### Esfuerzo Fija un [nivel de esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort) de Claude para cada solicitud con `fixedEffort:`. Tiene prioridad sobre las sugerencias de razonamiento por solicitud del framework. Los niveles de razonamiento con nombre del framework llegan hasta high; para solicitar más esfuerzo en una sola solicitud, pasa un nivel de razonamiento personalizado que nombre el esfuerzo de Claude (`.custom("xhigh")` o `.custom("max")`), que se asigna directamente. Cuando no se envía ningún esfuerzo, la API usa el nivel predeterminado del modelo, que varía según el modelo (consulta [Niveles de esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort#effort-levels)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth, fixedEffort: .xhigh) ``` El nivel debe ser uno que el modelo acepte. Cada `ClaudeModel` declara cuáles de los cinco niveles (`low`, `medium`, `high`, `xhigh`, `max`) toma su modelo, si es que toma alguno: algunos modelos no aceptan esfuerzo en absoluto. ### Cuándo usar Claude versus el modelo en el dispositivo El modelo en el dispositivo de Apple es rápido, privado y está disponible sin conexión, pero está dimensionado para tareas ligeras. Escala a Claude cuando necesites mayor contexto, razonamiento de frontera o herramientas del lado del servidor como búsqueda web y ejecución de código. Debido a que ambos usan la misma API `LanguageModelSession`, puedes cambiar intercambiando el argumento `model:`. ## Autenticación Establece la credencial con el parámetro `auth:`. Usa `.appAttest` para enviar sin un back end, `.proxied` para enrutar solicitudes a través de tu propio back end, o `.apiKey` para iterar durante el desarrollo. ### App Attest Cada instalación de tu aplicación usa el servicio [App Attest](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity) de Apple para demostrar que es una compilación genuina y sin modificaciones de la aplicación que registraste. Luego, Anthropic emite al dispositivo un token de acceso de corta duración que factura el uso a tu espacio de trabajo. La aplicación no incluye ninguna clave de API y no hay ningún proxy que debas operar. La autenticación con App Attest está disponible únicamente cuando tu aplicación llama a la Claude API directamente. No está disponible a través de Amazon Bedrock, Google Cloud ni Microsoft Foundry. Para enviar sin ejecutar un back end, usa `.appAttest`: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .appAttest(clientID: "clid_...") ) ``` App Attest requiere un dispositivo físico. El Simulador, y el hardware sin un Secure Enclave, no pueden realizar App Attest. Usa `.apiKey` mientras iteras en el Simulador, y `.appAttest` cuando ejecutes en un dispositivo. Para configurar App Attest, necesitas tu Apple Developer Team ID y el rol de administrador, propietario o propietario principal en tu organización. Configura tu proyecto de Xcode y registra tu aplicación en la [Claude Console](https://platform.claude.com/): 1. En Xcode, agrega la capacidad **App Attest** al target de tu aplicación en **Signing & Capabilities**. 2. En la Claude Console, ve a la página [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Cada integración de aplicación pertenece a un espacio de trabajo. Selecciona el espacio de trabajo que quieras en el selector de espacios de trabajo de la barra lateral. 3. Haz clic en **Create app integration** e ingresa un nombre, tu Apple Developer Team ID y uno o más bundle IDs (hasta 32). 4. Copia el ID de cliente (`clid_...`) de la pestaña **Overview** de la integración y pásalo a la configuración de Claude de tu aplicación. La primera vez que tu aplicación usa Claude en un dispositivo, la aplicación solicita un desafío a Anthropic, atestigua el dispositivo con el `DCAppAttestService` de Apple e intercambia la atestación verificada por un token de acceso. El paquete Claude for Foundation Models ejecuta este flujo automáticamente y solicita nuevos tokens a medida que expiran; no hay código de atestación que debas escribir. Los tokens están limitados a tu espacio de trabajo, expiran después de una hora y autorizan únicamente llamadas a la [Messages API](https://platform.claude.com/docs/es/api/messages/create). No contienen ninguna identidad del usuario final: App Attest identifica tu aplicación, no a la persona que la usa, así que maneja cualquier lógica por usuario en tu aplicación. Para detener una aplicación comprometida o retirada, revoca su integración. En la Claude Console, ve a la página [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Cada integración de aplicación pertenece a un espacio de trabajo. En el selector de espacios de trabajo de la barra lateral, selecciona el espacio de trabajo que contiene la integración. Selecciona la integración y haz clic en **Revoke**, luego confirma. Revocar una integración revoca sus tokens pendientes, y sus dispositivos registrados ya no pueden solicitar nuevos. La revocación es permanente, así que crea una nueva integración de aplicación para restaurar el acceso. ### Proxy (producción) Para producción, enruta las solicitudes a través de tu propio back end con `.proxied`. El relay en `baseURL` agrega la credencial de la API de Claude del lado del servidor, por lo que la aplicación no envía ninguna clave. Los `headers` que proporcionas se envían en cada solicitud para que tu proxy pueda autorizar al llamante. Pasa `[:]` si no necesita ninguno: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .proxied(headers: ["X-App-Token": "..."]), baseURL: URL(string: "https://api.yourapp.com/claude")! ) ``` Tu proxy recibe solicitudes estándar de la [API de Messages](https://platform.claude.com/docs/es/api/messages/create), adjunta el encabezado `x-api-key` y las reenvía a `https://api.anthropic.com`. ### Clave de API (desarrollo) Pasa una clave de API directamente mientras desarrollas: ```swift ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY")) ``` Una clave incluida en una aplicación es extraíble del binario enviado, y cualquiera que la extraiga puede hacer solicitudes facturadas a tu cuenta. Usa `.apiKey` solo para desarrollo, y cambia a App Attest o un proxy antes del lanzamiento. ## Streaming `streamResponse(to:)` devuelve la respuesta de forma incremental. Cada elemento es una instantánea acumulativa de la respuesta hasta el momento, no un delta: ```swift let stream = session.streamResponse(to: "Summarize today's top science stories.") for try await partial in stream { print(partial.content) } ``` ## Salida estructurada Anota un tipo con `@Generable` y solicítalo con `generating:`. El modelo devuelve un valor de ese tipo a través de [salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs): ```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) ``` La salida estructurada requiere un modelo cuyas capacidades la incluyan (todas las constantes compiladas lo hacen). Si el modelo elegido no lo hace, el paquete lanza `LanguageModelError.unsupportedGenerationGuide` en lugar de degradarse silenciosamente. ## Uso de herramientas ### Herramientas del lado del cliente El array `tools:` del framework funciona sin cambios. Haz que tus tipos cumplan con `Tool`, pásalos a `LanguageModelSession`, y el framework los invoca en el dispositivo cuando Claude los llama. Consulta [Uso de herramientas con Claude](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview). ```swift let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()]) ``` ### Herramientas del lado del servidor Las [herramientas del servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools) (búsqueda web, obtención web y ejecución de código) se ejecutan en la infraestructura de Anthropic dentro de un solo viaje de ida y vuelta, sin nada que el framework deba invocar en el dispositivo. Configúralas para cada modelo con `serverTools:`: ```swift let model = ClaudeLanguageModel( name: .sonnet5, auth: auth, serverTools: [ .webSearch(maxUses: 5), .codeExecution, ] ) ``` `.webSearch` y `.webFetch` aceptan `allowedDomains`, `blockedDomains` y `maxUses` opcionales. La actividad de las herramientas del servidor aparece en la transcripción como segmentos personalizados `ClaudeServerToolSegment`. `serverTools` se configura en `ClaudeLanguageModel` en lugar de en `LanguageModelSession` porque el tipo de sesión es de Apple. Para usar diferentes conjuntos de herramientas del servidor para cada conversación, construye múltiples instancias de `ClaudeLanguageModel`. ## Imágenes Los modelos cuyas capacidades incluyen entrada de imágenes declaran la capacidad de visión del framework. Pasa contenido de imagen a través de la API de sesión estándar del framework; el paquete lo convierte al formato de imagen de la API de Claude. Consulta [Visión](https://platform.claude.com/docs/es/build-with-claude/vision) para los requisitos de imagen. ## Manejo de errores El paquete mapea los errores de la API de Claude a los casos `LanguageModelError` de Apple donde uno encaja: el desbordamiento de la ventana de contexto aparece como `.contextSizeExceeded`, HTTP 429 como `.rateLimited`, una solicitud que supera el tiempo de espera configurado como `.timeout`. Los errores del proveedor sin equivalente en el framework aparecen como `ClaudeError`. Usa coincidencia de patrones para impulsar los flujos del producto: ```swift do { let response = try await session.respond(to: prompt) print(response.content) } catch ClaudeError.missingCredential { // Solicita una clave de API. } catch let error as LanguageModelError { // Errores con forma de framework (límites de velocidad, guardrails, longitud de contexto, decodificación). } catch { // Errores de transporte. } ``` Un patrón común es capturar `.rateLimited` y recurrir a `SystemLanguageModel` para ese turno, poner la solicitud en cola, o mostrar una opción de reintento. ## Soporte de funciones El paquete expone las capacidades de la API de Messages que el protocolo del proveedor de Foundation Models puede expresar. Las funciones sin representación en el protocolo de Apple no están disponibles a través de él, incluyendo: * Controles de almacenamiento en caché de prompts (el paquete aplica el almacenamiento en caché de prompts automáticamente; el TTL de caché y la colocación de puntos de interrupción no son configurables) * Secuencias de parada * Procesamiento por lotes * API de Files * Conteo de tokens * Encabezados beta ## Recursos adicionales | Referencia | Cubre | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | [Documentación de Apple Foundation Models](https://developer.apple.com/documentation/foundationmodels) | `LanguageModelSession`, `@Generable`, `Transcript`, `Tool`, y el resto de la superficie del framework | | [`ClaudeForFoundationModels` en GitHub](https://github.com/anthropics/ClaudeForFoundationModels) | Código fuente, el ejemplo ejecutable y el rastreador de problemas | | [Referencia de la API de Claude](https://platform.claude.com/docs/es/api/overview) | La API de Messages subyacente | El paquete tiene licencia Apache 2.0. Los informes de errores son bienvenidos a través de los issues de GitHub. Las pull requests externas no se aceptan durante el período beta.