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, 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, 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.

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 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: .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).

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

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

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. Los niveles de razonamiento nombrados del framework se detienen en high; para solicitar más esfuerzo para una sola solicitud en su lugar, pasa un nivel de razonamiento personalizado que nombre el esfuerzo de Claude (.custom("xhigh") o .custom("max")), que se mapea directamente. La API usa high por defecto cuando no se envía ningún esfuerzo:

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 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:

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

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:

1. En Xcode, agrega la capacidad App Attest al target de tu aplicación en Signing & Capabilities.
2. En la configuración de tu espacio de trabajo en la Claude Console, abre App integrations.
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. 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 configuración de tu espacio de trabajo en la Claude Console, abre App integrations, 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:

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, 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:

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

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

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

Herramientas del lado del servidor

Las herramientas del 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 para cada modelo con serverTools::

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.

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 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:

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

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.