Foundation Models APIs

Available on iOS/macOS 27 with Swift 6.4 and Xcode 27. Create a LedgeSession through client.session(model:tools:instructions:agent:) or the equivalent trace.session factory. model defaults to SystemLanguageModel.default, and tools defaults to an empty array. Instructions accept String or native Instructions; use the transcript: overload to restore a conversation.

The factory installs an executor wrapper before creating the native session. Wrapping an already-created session is no longer supported.

All overloads are async throws and return Apple's original LanguageModelSession.Response<Content>. They accept options: GenerationOptions, contextOptions: ContextOptions, native metadata, and recording: LedgeRecording. Structured forms default to ContextOptions(includeSchemaInPrompt: true).

transcript and isResponding expose native session state. prewarm(promptPrefix:) forwards to the original model executor. Use separate sessions for concurrent requests.

For native streaming APIs, use withSession(recording:operation:). Await all model work inside the closure; do not retain its native session or stream outside the scope.

Every executor attempt saves its prepared request before forwarding it. modelInput contains id, transcript, tools, responseFormat, options, contextOptions, and metadata. It is immutable. Model identifiers or configuration fields that Apple does not expose are not inferred. Subsequent generation after a tool result creates a separate span. Output and provider transcript capture are added as the session processes responses, retaining the observed executor completion time.

Framework or tool errors outside an executor failure produce session-failure spans with application context and providerCapture.failurePhase. They have no fabricated model input. Standalone scopes own a trace named and versioned from the agent; trace-owned sessions add spans to their existing trace.

See the guide for examples.