iOS 27의 Foundation Models: 도구 호출 제어

iOS 26은 앱에 온디바이스 대규모 언어 모델, @Generable을 통해 타입 안전한 출력을 얻는 방법, 그리고 생성 도중에 모델이 여러분의 코드를 호출할 수 있게 해주는 Tool 프로토콜을 제공했습니다¹. 언제 도구를 사용할지는 모델이 결정했고, 도구 자체는 여러분이 작성했습니다. 할 수 없었던 단 한 가지는 호출 동작 자체를 조정하는 것이었고, 반드시 해야 했던 단 한 가지는 모든 앱에 필요한 도구까지 포함해 모든 도구를 직접 손으로 작성하는 것이었습니다. iOS 27은 이 두 가지 빈틈을 모두 메웁니다. GenerationOptions.ToolCallingMode를 사용하면 요청마다 모델이 도구와 어떻게 상호작용하는지를 제어할 수 있습니다². 또한 Vision 프레임워크는 이제 인식 코드를 직접 작성하지 않고도 세션에 붙일 수 있는 OCRTool과 BarcodeReaderTool이라는 두 가지 즉시 사용 가능한 도구를 제공합니다³⁴. 이 둘이 합쳐지면서 프레임워크가 시작한 에이전트형 루프가 완성됩니다. 무엇을 할지는 모델이 결정하고, 그것을 얼마나 적극적으로 허용할지는 여러분이 결정하며, 물리 세계를 읽어내는 인지 도구는 Apple이 공급하는 구조입니다.

지금부터 다루는 내용은 프레임워크 레퍼런스 위에 얹히는 iOS 27 계층입니다. LanguageModelSession이나 Tool 프로토콜, 가이드 생성을 아직 접해보지 않았다면 먼저 Foundation Models 프레임워크 설명부터 읽고 다시 돌아오세요.

핵심 요약

• GenerationOptions.ToolCallingMode는 iOS 27에 새로 등장한 구조체로, 도구 사용과 관련한 모델 동작을 기술하며 GenerationOptions를 통해 요청마다 설정합니다². Apple은 세 가지 모드를 문서화하고 있습니다.
• 프레임워크는 첫 번째 도구 호출 이후 모드를 변경할 수 있으며, 그러면 모델은 도구 호출을 멈추고 최종 응답을 생성합니다. 이것이 한 번의 요청에서 일어나는 도구 활동의 상한이 됩니다².
• OCRTool은 이미지 속 텍스트를 인식하고 읽어낸 모든 내용을 담은 문자열을 반환합니다. 활성화하려면 LanguageModelSession에 OCRTool 인스턴스를 구성하면 됩니다³.
• BarcodeReaderTool은 기계 판독 코드를 스캔하여 Barcode 결과의 배열을 반환하며, 각 결과에는 디코딩된 내용과 심볼 체계 유형이 담깁니다. 활성화 방법은 동일하게, 세션에 인스턴스를 구성하면 됩니다⁴.
• 두 Vision 도구 모두 기본 이름과 설명을 재정의할 수 있어, 모델이 각 도구를 어떻게 식별하고 사용할지를 여러분이 제어할 수 있습니다³⁴.
• 여기서 다루는 모든 내용은 iOS 27 베타(그리고 그에 대응하는 iPadOS, macOS, visionOS 베타, 세 가지 심볼 중 두 가지는 watchOS 베타)를 대상으로 합니다²³⁴.

iOS 26과 iOS 27 사이에 무엇이 바뀌었나

iOS 26 프레임워크는 API 표면에서 도구 호출을 이분법적으로 다뤘습니다. 세션에 도구 집합을 넘기면, 그 이후로는 호출 여부와 호출 빈도를 오직 모델만 결정했습니다. 단발성 조회라면 이걸로 충분합니다. 그러나 하나의 세션 안에서 요청마다 다른 동작을 원하는 순간 어색해집니다. 어떤 프롬프트에서는 모델이 반드시 도구를 참조해야 하고, 다른 프롬프트에서는 왕복을 건너뛰고 맥락에서 답하기를 바라는 경우입니다.

iOS 27은 그 결정을 여러분의 손에 넘깁니다. ToolCallingMode는 GenerationOptions를 통해 전달하는 값으로, 이미 디코딩을 제어하고 있던 바로 그 옵션 객체입니다²⁵. 그리고 모드는 세션이 아니라 요청의 속성입니다. 기본 제공 Vision 도구는 방정식의 다른 쪽을 바꿉니다. OCR 파이프라인이나 바코드 스캐너를 작성해 직접 만든 Tool 준수로 감싸는 대신, Apple의 구현을 붙이고 노력은 프롬프트에 쏟으면 됩니다.

GenerationOptions.ToolCallingMode: 호출을 조종하기

ToolCallingMode는 GenerationOptions 아래에 있는 구조체로, iOS 27, iPadOS 27, Mac Catalyst 27, macOS 27, visionOS 27, watchOS 27 베타에서 사용할 수 있습니다². Apple의 개요는 한 문장입니다. 도구 사용과 관련한 모델 동작을 기술하는 데 쓰는 값이라는 것입니다². 선언은 더없이 단순합니다.

// iOS 27 beta
struct ToolCallingMode

Apple 문서에 따르면 도구 호출 모드는 세 가지 모드를 지원합니다². 각 모드의 이름을 밝혀줄 설명 텍스트는 작성 시점의 레퍼런스에서 일부가 생략되어 있습니다. 그래서 식별자를 추측하기보다, 프레임워크가 동작에 관해 문서화한 내용을 설명하겠습니다. 설계를 실제로 좌우하는 것은 바로 그 부분이기 때문입니다.

Apple이 분명히 밝혀둔 동작은 이렇습니다. 프레임워크는 첫 번째 도구 호출 이후 모드를 변경할 수 있고, 그러면 모델은 최종 응답을 생성합니다². 이 한 문장이 모든 것을 떠받치는 핵심입니다. 즉 요청은 모델이 도구를 호출할 수 있는(혹은 호출해야 하는) 자세로 시작할 수 있고, 그 첫 호출이 돌아오면 프레임워크가 모드를 전환해 모델이 더 이상 도구로 손을 뻗지 않고 답으로 향하게 됩니다. 실질적인 효과는 한 번의 요청에서 일어나는 도구 활동에 상한을 두는 것입니다. 컨텍스트 윈도를 다 써버릴 때까지 루프를 돌며 도구를 계속 호출하는 모델에 휘둘릴 일이 없습니다.

모드는 이미 respond(to:)에 넘기고 있는 옵션 객체를 통해 설정합니다.

import FoundationModels

let session = LanguageModelSession(tools: [FindContacts()])

// A request where you want to govern tool-calling behavior explicitly.
var options = GenerationOptions()
options.toolCallingMode = .someMode   // one of the three documented modes
let response = try await session.respond(
    to: "Draft a dinner invite to three of my contacts.",
    options: options
)

.someMode의 정확한 철자는 문서화된 세 가지 케이스에서 옵니다. 중요한 것은 메커니즘이며, 그 메커니즘이란 동작이 요청별로 정해지고 GenerationOptions에 실려 전달된다는 점입니다. 이 객체는 디코딩 전략, 모델이 출력 토큰을 고르는 방식, 그리고 통제 불능의 장황함을 막고 싶을 때만 손대는 선택적 응답 토큰 상한을 관장하는 바로 그 iOS 26 구조체입니다⁵. 도구 호출 모드는 여러분이 이미 쓰고 있는 제어 면에 더해진 새 차원이지, 코드 곳곳에 새로 꿰어야 하는 새 객체가 아닙니다.

이 제어가 세션 수준이 아니라 요청 수준에 놓인 이유는, 도구가 필요한지 여부가 대화가 아니라 질문의 성질이기 때문입니다. 채팅 세션은 정말로 연락처 조회가 필요한 한 차례와, 이미 보유한 내용에서 모델이 다시 표현해 처리할 수 있는 다음 차례를 함께 다룰 수 있습니다. 두 번째 차례에 도구 호출을 강제하면 왕복이 낭비되고, 공유 컨텍스트 윈도가 내줄 여유가 없는 토큰을 태웁니다⁵. 요청별 모드는 각 차례가 스스로의 자세를 선언하도록 해줍니다.

기본 제공 Vision 도구: OCRTool과 BarcodeReaderTool

iOS 27 이야기의 후반부는 Foundation Models 도구로 노출된 Vision 프레임워크에서 옵니다. 이제 Apple은 여러분이 직접 만든 도구를 붙이는 것과 똑같은 방식으로 LanguageModelSession에 붙일 수 있는 두 가지 도구를 제공합니다. 다만 인식 코드는 전혀 작성하지 않아도 됩니다.

세션 241에서 Apple은 BarcodeReaderTool과 OCRTool을, 모델이 시각 정보를 네이티브로는 할 수 없는 방식으로 추론하는 능력을 높여주는 기본 제공 시스템 도구로 소개합니다.⁷

OCRTool

OCRTool은 이미지 속 텍스트를 인식합니다. Apple의 개요가 바로 그것이며, 계약에 관한 설명은 정확합니다. 이 도구는 이미지에서 인식한 모든 텍스트를 담은 문자열을 반환합니다³. 켜려면 LanguageModelSession에 OCRTool 인스턴스를 구성하면 됩니다³. 선언은 이렇습니다.

// iOS 27 beta, Vision framework
struct OCRTool

붙이는 방법은 다른 어떤 도구와도 같은 모양입니다. 세션 입장에서는 이것 역시 또 하나의 Tool일 뿐이기 때문입니다.

import FoundationModels
import Vision

// Configure the session with an OCRTool instance to enable it.
let session = LanguageModelSession(tools: [OCRTool()])

let response = try await session.respond(
    to: "Pull the total and the date off this receipt image and summarize them."
)

프롬프트가 이미지에서 텍스트를 필요로 한다고 모델이 판단하면 OCRTool을 호출해 도구가 읽어낸 모든 내용을 문자열로 받고, 여러분이 작성한 도구의 결과를 엮어 넣을 때와 똑같이 그 문자열을 답에 엮어 넣습니다³. Vision 요청도, 처리 코드도 작성하지 않았습니다. 도구를 붙이고 할 일을 설명했을 뿐입니다.

Apple은 기본 이름과 설명을 재정의할 수 있게 하여, 모델이 도구를 어떻게 식별하고 사용할지를 맞춤 설정하도록 합니다³. 이 후크가 모델이 OCR로 손을 뻗는 시점에 대해 여러분이 가진 유일한 지렛대입니다. 앱이 영수증을 읽는다면 도구의 설명을 영수증의 언어로 쓰세요. 그러면 영수증 같은 프롬프트에서는 호출하도록, 이미지가 장식에 불과한 프롬프트에서는 호출하지 않도록 모델을 치우치게 할 수 있습니다. 설명은 모델이 읽는 함수 문서이니, 그렇게 여기고 작성하세요.

BarcodeReaderTool

BarcodeReaderTool은 이미지 속 기계 판독 코드를 스캔합니다⁴. OCRTool이 평평한 문자열을 반환하는 데 비해, 바코드 도구는 구조를 반환합니다. 기계 판독 코드를 담은 이미지를 모델이 마주치면 이 도구를 호출해 그것들을 디코딩할 수 있고, 도구는 Barcode 결과의 배열을 반환하며 각 결과에는 디코딩된 내용과 심볼 체계 유형이 담깁니다⁴. 선언과 부착은 OCRTool을 그대로 옮긴 모습입니다.

// iOS 27 beta, Vision framework
struct BarcodeReaderTool

// Configure the session with a BarcodeReaderTool instance to enable it.
let session = LanguageModelSession(tools: [BarcodeReaderTool()])

let response = try await session.respond(
    to: "Scan this label and tell me what product it is and which standard the code uses."
)

각 Barcode 결과에 담긴 심볼 체계 유형이야말로, 구조화된 반환값의 가치를 만들어내는 세부 사항입니다⁴. QR 코드, 식료품의 EAN-13 바코드, 운전면허증의 PDF417은 모두 기계 판독 코드이지만, 여러분의 앱에는 저마다 다른 의미를 갖습니다. 도구가 디코딩된 페이로드와 함께 심볼 체계를 돌려주므로, 모델은(그리고 하류 코드는) 내부의 바이트만이 아니라 코드의 종류에 따라 분기할 수 있습니다. OCRTool과 마찬가지로, 기본 이름과 설명을 재정의해 모델이 도구를 어떻게 식별하고 사용할지를 조종할 수 있습니다⁴.

두 도구 모두 같은 베타 제공 범위를 가집니다. 둘 다 iOS 27, iPadOS 27, Mac Catalyst 27, macOS 27, visionOS 27에서 제공되며, BarcodeReaderTool은 watchOS 27에도 기재되어 있습니다³⁴.

루프 짜기: 인지와 통제된 호출

두 기능은 각각만으로도 흥미롭지만 함께일 때 더 낫습니다. 둘은 하나의 에이전트형 요청에서 정반대 양끝에 자리하기 때문입니다. Vision 도구는 인지, 즉 이미지를 향한 모델의 눈입니다. ToolCallingMode는 거버넌스, 즉 모델이 그 눈에 얼마나 기대게 할지를 쥔 여러분의 손입니다.

식료품 저장고 재입고 기능을 그려보세요. 사용자가 선반을 촬영합니다. 세션에는 두 Vision 도구가 모두 붙어 있고, 앱 카탈로그에 접근하는 여러분만의 도구인 LookUpProduct도 하나 붙어 있습니다. 한 번의 요청으로 모델에게 품목을 식별하고 재주문 목록을 만들라고 요청합니다. 모델은 보이는 라벨을 디코딩하려고 BarcodeReaderTool을 호출하고, 깔끔한 코드가 없는 품목은 OCRTool로 인쇄된 텍스트를 읽으며, 디코딩한 각 페이로드를 카탈로그 항목으로 해석하려고 여러분의 LookUpProduct를 호출합니다. 도구 셋, 프롬프트 하나, 일관된 답 하나입니다.

import FoundationModels
import Vision

let session = LanguageModelSession(tools: [
    OCRTool(),
    BarcodeReaderTool(),
    LookUpProduct(),     // your own Tool conformance over the app catalog
])

var options = GenerationOptions()
options.toolCallingMode = .someMode   // govern how the model sequences the calls
let response = try await session.respond(
    to: "Identify everything on this shelf and build a reorder list.",
    options: options
)

이것이 바로 프레임워크가 향해 쌓아온 루프입니다. iOS 26은 런타임 모델, 가이드 생성, 그리고 여러분이 자유 텍스트를 파싱하지 않고도 온디바이스 모델이 코드를 호출할 수 있게 해주는 Tool 프로토콜을 제공했습니다¹. 이 클러스터의 아키텍처 글은 그 런타임 모델과, 개발자가 앱을 작성하려고 Claude Code에서 돌리는 도구용 LLM 사이의 선을 그었고, Foundation Models의 Tool, App Intent, MCP 도구를 세 개의 얇은 어댑터를 통해 하나의 Swift 도메인 함수로 떠받치자는 주장을 펼쳤습니다⁶. iOS 27은 그 그림의 런타임 쪽에 들어맞습니다. 기본 제공 Vision 도구는 Apple이 작성하고 여러분이 장착하는 도메인 함수이고, LookUpProduct는 여러분이 작성한 도메인 함수이며, 모델이 그것들 전부를 조율하고, ToolCallingMode는 그 조율의 스로틀입니다.

신뢰 경계는 움직이지 않습니다. OCRTool과 BarcodeReaderTool은 여러분이 직접 작성한 도구와 동일한 샌드박스와 프라이버시 자세 아래에서, 사용자의 이미지를 대상으로 온디바이스로 앱 프로세스 안에서 실행됩니다. Apple이 구현을 공급함으로써 바뀌는 것은 누가 인식 코드를 유지보수하는가이지, 누가 그 기능에 책임을 지는가가 아닙니다. 프롬프트, 세션, 가용성 확인, 그리고 사용자 앞에 카메라를 두겠다는 결정은 여전히 여러분의 몫입니다.

각 모드와 도구를 언제 쓸 것인가

위의 계약에서 따라 나오는 몇 가지 규칙입니다.

도구 필요가 요청마다 달라질 때 ToolCallingMode로 손을 뻗으세요. 세션의 모든 차례가 같은 도구 동작을 필요로 한다면 기본값으로 충분하며, 모드는 잡음에 불과합니다. 모드가 제값을 하는 때는, 어떤 요청은 반드시 도구를 참조해야 하고 다른 요청은 맥락에서 답해야 할 때, 혹은 프레임워크의 첫 호출 이후 전환을 이용해 그냥 두면 루프에 빠질 수 있는 요청에 상한을 두고 싶을 때입니다². 제어가 그곳에 있으니, 세션에 한 번 설정하지 말고 요청에 설정하세요².

답이 이미지 속에 갇힌 텍스트일 때 OCRTool로 손을 뻗으세요. 영수증, 표지판, 손글씨 메모, 텍스트 스크린숏 같은 것들입니다. 이 도구는 읽어낸 모든 것을 하나의 문자열로 반환하므로³, 레이아웃이 아니라 단어를 두고 모델이 추론하기를 바라는 프롬프트에 잘 맞습니다. 경계 상자나 줄별 신뢰도가 필요하다면, 그것은 이 도구가 아니라 더 낮은 수준의 Vision 요청입니다.

이미지가 기계 판독 코드를 담고 있고 코드의 종류가 중요할 때 BarcodeReaderTool로 손을 뻗으세요. 제품 라벨, 티켓, 신분증, 재고 태그 같은 것들입니다. 구조화된 반환값, 즉 디코딩된 내용에 심볼 체계를 더한 것⁴이야말로 바코드를 일반 텍스트로 다루기보다 이 도구를 택할 이유입니다. 여러분만의 도구나 후처리에서 심볼 체계에 따라 분기하세요.

앱이 일반 도구에 특정한 일을 맡길 때는 언제든 이름과 설명을 재정의하세요. 두 Vision 도구 모두 기본적으로 일반적인 정체성을 갖고, 모델은 설명을 일부 단서로 삼아 도구를 고릅니다³⁴. 오직 영수증만 읽는 앱이라면 OCR 도구의 설명에 그렇게 밝혀야 합니다. 그래야 우연히 글자가 들어간 모든 사진에서 모델이 그것을 호출하지 않습니다.

FAQ

iOS 27의 GenerationOptions.ToolCallingMode란 무엇인가요?

iOS 27 베타에 새로 등장한 구조체로, 특정 요청에 대한 도구 사용 주변의 모델 동작을 기술합니다. respond(to:)에 넘기는 GenerationOptions를 통해 설정하므로, 도구 호출 동작은 세션 전체가 아니라 각 요청의 속성이 됩니다. Apple은 세 가지 모드를 문서화하고 있습니다².

Apple은 도구 호출 모드를 몇 개 문서화하고 있으며, 이름은 무엇인가요?

Apple 문서에 따르면 도구 호출 모드는 세 가지 모드를 지원합니다². 각 모드를 개별적으로 명명하는 레퍼런스 텍스트는 작성 시점에 일부가 생략되어 있어, 식별자를 추측하기보다 문서화된 동작을 설명합니다. Apple이 명시적으로 밝힌 동작은 이렇습니다. 프레임워크는 첫 번째 도구 호출 이후 모드를 변경할 수 있어 모델이 최종 응답을 생성하게 하고, 이것이 한 번의 요청에서 일어나는 도구 활동에 상한을 둡니다².

Apple의 기본 제공 OCR 도구는 어떻게 활성화하나요?

다른 어떤 도구를 붙이는 것과 똑같이, LanguageModelSession에 OCRTool 인스턴스를 구성하세요³. 그러면 모델은 프롬프트가 이미지에서 텍스트를 필요로 할 때 그것을 호출하고, 도구는 인식한 모든 텍스트를 담은 문자열을 반환합니다. OCRTool은 Vision 프레임워크에 있으며 iOS 27 베타에서 사용할 수 있습니다³.

BarcodeReaderTool은 무엇을 반환하나요?

Barcode 결과의 배열을 반환하며, 각 결과에는 디코딩된 내용과 심볼 체계 유형이 담깁니다⁴. 심볼 체계가 있으면 QR 코드와 EAN-13, PDF417을 구분하고, 페이로드뿐 아니라 코드의 종류에 따라 분기할 수 있습니다. 활성화하려면 LanguageModelSession에 BarcodeReaderTool 인스턴스를 구성하면 됩니다⁴.

모델이 기본 제공 Vision 도구를 사용하는 판단 방식을 바꿀 수 있나요?

네. OCRTool과 BarcodeReaderTool 모두 기본 이름과 설명을 재정의해, 모델이 도구를 어떻게 식별하고 사용할지를 맞춤 설정할 수 있습니다³⁴. 설명은 모델이 도구로 손을 뻗는 시점을 좌우하는 지렛대이므로, 앱 고유의 언어로 작성하면 올바른 호출 쪽으로 모델을 치우치게 할 수 있습니다.

기본 제공 Vision 도구는 이미지를 기기 밖으로 보내나요?

아니요. OCRTool과 BarcodeReaderTool은 Foundation Models 도구로, 여러분이 직접 작성하는 도구와 동일한 샌드박스와 프라이버시 자세 아래에서 온디바이스로 앱 프로세스 안에서 실행됩니다¹³⁴. Apple이 인식 코드를 공급함으로써 바뀌는 것은 누가 그것을 유지보수하는가이지, 어디서 실행되는가나 누가 그 기능에 책임을 지는가가 아닙니다.

Apple Ecosystem 클러스터 전체입니다. Foundation Models 프레임워크 설명, 온디바이스 LLM, 런타임 LLM과 도구용 LLM의 구분, 커스텀 어댑터, 타입이 있는 App Intents, 새로운 App Intents iOS 27 백그라운드 실행과 동기화, MCP 도구에 맞선 라우팅 질문, Vision 프레임워크, Core ML 추론, 세 가지 표면. 허브는 Apple Ecosystem 시리즈에 있습니다. AI 에이전트를 동반한 iOS의 더 넓은 맥락은 iOS 에이전트 개발 가이드를 참고하세요.