Apple Foundation Models

Claude for Foundation Models es un paquete Swift que hace que Claude esté disponible como modelo de lenguaje del lado del servidor en el framework Foundation Models de Apple. El paquete hace que Claude cumpla con el protocolo LanguageModel del framework, de modo 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 app a la API de Claude; Apple no está en la ruta de la solicitud y no ve los prompts ni las respuestas. El uso se factura a tu cuenta de Anthropic según los precios estándar de la API. Tu app 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.



Requisitos

• iOS 27, macOS 27, visionOS 27 o watchOS 27 (todos en beta): las versiones del sistema operativo cuyo framework Foundation Models admite modelos de lenguaje del lado del servidor
• Xcode 27 (beta)
• Una clave de API de Claude desde la Claude Console para desarrollo. Consulta Autenticación para opciones de producción.



Instalar el paquete

Agrega el paquete a tu Package.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:

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:

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)

El inicializador también acepta baseURL (por defecto https://api.anthropic.com), timeout y serverTools (consulta Herramientas del lado del servidor).

Para un programa funcional completo, el repositorio incluye 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 ese turno. Ejecutarlo requiere un host con macOS 27.



Elegir un modelo

Los identificadores de modelo son valores de ClaudeModel. Usa una constante compilada, o construye uno con capacidades explícitas para un ID que aún no esté compilado (consulta Capacidades):

ClaudeLanguageModel(name: .opus4_8, auth: auth)

Las constantes reflejan los IDs de modelo de la API (.opus4_8 es claude-opus-4-8) y llevan las capacidades de cada modelo. Los modelos nuevos se publican como nuevas constantes en las versiones del paquete; revisa ClaudeModel en Xcode para ver la lista actual, y la descripción general de modelos 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 decidir qué campos de solicitud enviar, porque enviar un campo que un modelo rechaza es un error fatal. Las constantes llevan las capacidades correctas. Para un ID que no está compilado, declara lo que el modelo acepta (deliberadamente no hay una forma abreviada que adivine):

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 de Claude para cada solicitud con fixedEffort:. Tiene prioridad sobre las sugerencias de razonamiento por solicitud del framework, y es la única forma de solicitar .xhigh o .max, porque los niveles de razonamiento del framework llegan solo hasta high. La API usa high por defecto cuando no se envía ningún esfuerzo:

ClaudeLanguageModel(name: .opus4_8, 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) acepta su modelo, si es que acepta 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 funciona sin conexión, pero está dimensionado para tareas ligeras. Escala a Claude cuando necesites un contexto más grande, razonamiento de frontera o herramientas del lado del servidor como búsqueda web y ejecución de código. Como ambos usan la misma API LanguageModelSession, puedes cambiar intercambiando el argumento model:.



Autenticación

Establece la credencial con el parámetro auth:.



Clave de API (desarrollo)

Pasa una clave de API directamente mientras desarrollas:

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



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, de modo que la app no incluye ninguna clave. Los headers que proporcionas se envían en cada solicitud para que tu proxy pueda autorizar al llamador. Pasa [:] si no necesita ninguno:

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

Tu proxy recibe solicitudes estándar de la Messages API, adjunta el encabezado x-api-key y las reenvía a https://api.anthropic.com.



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:

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:

@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 la incluyen). Si el modelo elegido no la incluye, 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.

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



Herramientas del lado del servidor

Las herramientas de servidor (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 por modelo con serverTools::

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

.webSearch y .webFetch aceptan opcionalmente allowedDomains, blockedDomains y maxUses. La actividad de las herramientas de servidor aparece en la transcripción como segmentos personalizados ClaudeServerToolSegment.



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 para los requisitos de imagen.



Manejo de errores

El paquete mapea los errores de la API de Claude a los casos de LanguageModelError de Apple cuando hay uno que 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 pattern matching para controlar los flujos del producto:

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 propios del 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.



Compatibilidad de funciones

El paquete expone las capacidades de la Messages API que el protocolo de 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 ubicación de los puntos de interrupción no son configurables)
• Secuencias de parada
• Procesamiento por lotes
• Files API
• Conteo de tokens
• Encabezados beta



Recursos adicionales

El paquete está licenciado bajo Apache 2.0. Los reportes de errores son bienvenidos a través de issues de GitHub. No se aceptan pull requests externos durante el período beta.