Gemini 3 Flash / Pro Preview 기준
Gemini API 도구 조합, 되는 것과 안 되는 조건
Google이 2026년 3월 17일, 내장 도구와 커스텀 함수를 단일 API 호출 안에 동시에 쓸 수 있는 기능을 공개했습니다. Google Search로 실시간 데이터를 가져오고, 그 결과를 그대로 내부 함수에 넘기는 흐름이 이제 별도 오케스트레이션 없이 가능해졌습니다. 그런데 막상 써보면 “왜 안 되지?”가 생기는 지점이 있습니다.
이 기능이 등장한 맥락
Gemini API 도구 조합 기능은 2026년 3월 17일(현지 시각) 구글 공식 블로그를 통해 발표됐습니다. 공식 명칭은 “Combine built-in tools and function calling”으로, 이전까지는 Google Search 같은 내장 도구와 개발자가 직접 만든 함수 선언(function declarations)을 같은 요청에 동시에 넣으면 오류가 났습니다. 이를 분리해서 호출하거나, 중간에 오케스트레이션 레이어를 직접 짜야 했죠.
공식 블로그는 “에이전트 워크플로가 확장될수록 오케스트레이션이 병목이 된다”는 문제의식을 직접 명시했습니다. 즉 이 기능은 단순 편의 기능이 아니라 에이전트 아키텍처를 단순화하기 위한 구조적 변경입니다. 구글 내부 발표 자료에 따르면 이 조합이 “개발자들이 내장 도구 출시 이후 가장 많이 요청한 기능”이었다고 합니다.
“종전까지 별도로 처리하던 두 흐름을 하나로 합쳤다”는 표현이 핵심입니다. 지원 모델은 Gemini 3 Flash Preview (`gemini-3-flash-preview`), Gemini 3 Pro Preview (`gemini-3-pro-preview`)이며, Gemini 3 모델 패밀리에서만 동작합니다.
실제로 어떻게 동작하나
핵심은 `include_server_side_tool_invocations: true` 플래그 하나입니다. 이 플래그를 켜야만 도구 컨텍스트 순환(tool context circulation)이 활성화됩니다. 이게 꺼져 있으면 내장 도구와 함수 선언을 같이 넣어도 조합 동작이 트리거되지 않습니다.
동작 흐름은 두 단계입니다. 첫 번째 호출에서 모델이 Google Search를 실행해 실시간 데이터를 가져오고, 그 결과(`toolCall`, `toolResponse`)와 함께 커스텀 함수 호출 요청(`functionCall`)을 단일 응답에 담아 반환합니다. 두 번째 호출에서 개발자는 함수 실행 결과를 `functionResponse`로 돌려보내면, 모델이 두 도구의 컨텍스트를 합산해 최종 응답을 생성합니다.
Tool은 서버 측(내장), Function은 클라이언트 측(커스텀)으로 나뉩니다. 내장 도구의 실행은 구글 서버에서 처리되고, 커스텀 함수 실행은 개발자 코드에서 처리됩니다. 이 둘의 컨텍스트를 순환시키는 것이 이번 기능의 핵심입니다.
단일 `tools` 배열 안에 `googleSearch`(내장)과 `functionDeclarations`(커스텀)를 함께 넣으면 됩니다. Python, JavaScript, Go, REST 모두 지원하며, 공식 문서에 각 언어별 코드 샘플이 있습니다. (출처: Gemini API 공식 문서, 2026.03.21)
Google Search 토큰만 이중 청구 안 됩니다 — 나머지 내장 도구는 다릅니다
도구 조합을 쓰면 내장 도구가 반환하는 `toolCall`과 `toolResponse` 부분이 대화 기록의 일부가 됩니다. 이게 다음 호출의 입력 토큰(`prompt_token_count`)에 그대로 포함됩니다. 쉽게 말하면, 모델이 Google Search를 한 번 실행할 때마다 그 결과가 다음 요청의 입력 토큰으로 쌓입니다.
공식 가격 페이지에는 이렇게 적혀 있습니다. “Google 검색 도구는 이 규칙의 예외입니다. Google 검색은 이미 쿼리 수준에서 자체 가격 책정 모델을 적용하므로 토큰이 이중 청구되지 않습니다.” (출처: Gemini API 가격 페이지, 2026.03.22) Google Search 1,000회 기준 $35가 별도 적용됩니다.
Google Maps, URL Context, File Search 같은 다른 내장 도구는 이 예외 적용을 받지 않습니다. 이 도구들의 실행 결과는 입력 토큰에 그대로 포함되어 과금됩니다. 도구 조합을 실서비스에 쓴다면, Google Search 외 내장 도구를 많이 사용할수록 토큰 비용이 예상보다 높게 나올 수 있습니다.
| 내장 도구 | 컨텍스트 순환 | 토큰 이중 청구 | 비고 |
|---|---|---|---|
| Google Search | ✅ 지원 | 없음 | 1,000회 $35 별도 |
| Google Maps | ✅ 지원 | 있음 | toolResponse → 입력 토큰 포함 |
| URL Context | ✅ 지원 | 있음 | URL 크롤 결과 토큰 누적 |
| File Search | ✅ 지원 | 있음 | 파일 검색 결과 토큰 누적 |
| Code Execution | ✅ 지원 | 있음 | 코드 실행 결과 토큰 누적 |
| 커스텀 함수 | ✅ 지원 | 있음 | functionResponse → 입력 토큰 포함 |
※ 모든 토큰 과금 기준은 입력 토큰(prompt_token_count)입니다. Gemini 3 Flash Preview 기준 20만 토큰 이하 $0.30/1M, 초과 시 $0.625/1M 적용. (출처: Gemini API 가격 페이지)
Vercel AI SDK에서 막히는 이유
구글 공식 SDK(Python, JavaScript `@google/genai`, Go, REST)에서는 이 기능이 정상 동작합니다. 그런데 Vercel AI SDK(`@ai-sdk/google`)에서는 현재 지원하지 않습니다. GitHub 이슈 #11695에는 `gemini-3-flash-preview`와 `gemini-3-pro-preview`에서 provider-defined 도구와 커스텀 함수를 동시에 사용하면 다음 경고가 뜬다고 보고됩니다.
2026년 1월 9일에 올라온 이 이슈는 아직 해결되지 않은 상태입니다. Vercel AI SDK 측에서 구글 공식 SDK의 `include_server_side_tool_invocations` 플래그를 내부적으로 래핑하지 않았기 때문입니다. (출처: Vercel AI SDK GitHub 이슈 #11695)
즉, 현재 기준으로 이 기능을 쓰려면 구글 공식 SDK를 직접 사용해야 합니다. Vercel AI SDK 기반으로 프로덕션을 운영 중이라면 당장 적용이 어렵습니다. 구글 공식 답변은 아직 나오지 않은 부분입니다.
thought_signature를 빠뜨리면 생기는 일
공식 문서에 딱 이렇게 나옵니다. “사고 서명 없이는 컨텍스트를 재구성할 수 없습니다. 턴마다 모든 파트에 대한 사고 서명을 반환하지 않으면 모델에 오류가 발생합니다.” `thought_signature`는 API가 반환하는 각 파트에 삽입된 암호화된 컨텍스트 값입니다.
이게 문제가 되는 이유는, 기존 함수 호출 코드에서 “필요한 부분만 골라서 다음 턴에 넘기던” 패턴이 여기서는 통하지 않기 때문입니다. 기존에는 `functionCall`과 `functionResponse`만 주고받으면 충분했습니다. 하지만 도구 조합 기능을 쓸 때는 모델이 반환한 응답의 모든 파트(`toolCall`, `toolResponse`, `functionCall`, `thought_signature`를 포함한 부분 전체)를 다음 요청에 그대로 실어야 합니다.
기존 코드에서 `response.candidates[0].content.parts`를 순회하며 `functionCall` 파트만 추출해서 히스토리를 쌓는 구조라면, `toolCall`/`toolResponse`/`thought_signature`가 빠지게 됩니다. 도구 조합으로 전환 시 히스토리 빌드 로직을 전면 수정해야 합니다.
공식 문서 예제 코드에서는 Turn 1 응답을 `response.candidates[0].content` 통째로 히스토리에 넣습니다. 파트를 개별 추출하지 않고, 응답 컨텐츠 객체 자체를 다음 요청의 `contents` 배열에 그대로 포함하는 방식입니다. (출처: Gemini API 공식 문서, 2026.03.21)
Interactions API를 권장하는 이유가 따로 있습니다
공식 블로그는 이렇게 적습니다. “이 기능들은 `generateContent` API에서도 지원되지만, 서버 측 상태 관리와 통합 추론 트레이스를 활용하려면 새로운 Interactions API 사용을 권장합니다.” (출처: 구글 공식 블로그, 2026.03.17)
Interactions API는 2025년 12월 11일에 공개된 기능으로, `thought_signature`와 히스토리 관리를 서버 측에서 자동으로 처리합니다. 즉, `generateContent`로 도구 조합을 쓰면 히스토리를 직접 관리해야 하는 부담이 있지만, Interactions API를 쓰면 이를 위임할 수 있습니다.
다만 Interactions API는 별도 설정이 필요하며, 2026년 3월 현재 기준으로 프리뷰 상태입니다. 빠른 프로토타입에는 `generateContent` + 도구 조합이, 프로덕션 에이전트에는 Interactions API가 더 적합합니다.
Q&A
Q1. Gemini 2.5 Flash에서도 도구 조합이 되나요?
안 됩니다. 이 기능은 Gemini 3 모델 패밀리(`gemini-3-flash-preview`, `gemini-3-pro-preview`)에서만 지원됩니다. Gemini 2.5 계열은 `useSearchGrounding: true`로 Search를 단독 사용할 수 있지만, 커스텀 함수와 동시 조합은 지원하지 않습니다. (출처: Gemini API 공식 문서, 2026.03.21)
Q2. AUTO 모드가 안 된다는 게 실제로 어떤 의미인가요?
function_calling_config.mode가 기본값인 AUTO일 때는 도구 조합이 제대로 작동하지 않습니다. include_server_side_tool_invocations: true를 설정하면 자동으로 VALIDATED 모드로 전환됩니다. AUTO 모드에서는 모델이 도구를 쓸지 말지 자율적으로 결정하지만, VALIDATED 모드에서는 선언된 도구를 반드시 사용하는 방향으로 동작합니다. (출처: Gemini API 공식 문서 제한사항 섹션, 2026.03.21)
Q3. id 필드를 꼭 맞춰줘야 하나요?
네, 필수입니다. `functionResponse`를 돌려줄 때 API가 `functionCall`에 부여한 것과 동일한 `id`를 반드시 포함해야 합니다. 이 매핑이 어긋나면 모델이 어떤 호출의 응답인지 식별하지 못해 오류가 납니다. 기존 코드에 id 매핑 로직이 없다면 추가가 필요합니다. (출처: Gemini API 공식 문서, 2026.03.21)
Q4. system_instruction에 위치 정보를 넣으면 문제가 되나요?
됩니다. 공식 문서는 이렇게 명시합니다. “Google Search 같은 내장 도구는 위치 및 현재 시간 정보를 사용하므로 `system_instruction` 또는 `function_declaration.description`에 충돌하는 위치/시간 정보가 있으면 도구 조합 기능이 제대로 작동하지 않을 수 있습니다.” 시스템 프롬프트에 날짜나 지역을 고정해 두는 패턴을 사용 중이라면 제거가 필요합니다. (출처: Gemini API 공식 문서 제한사항, 2026.03.21)
Q5. 이 기능이 무료 티어에서도 사용 가능한가요?
모델 자체(Gemini 3 Flash/Pro Preview)는 유료 플랜에서만 사용 가능합니다. Google AI Studio 무료 티어에서는 Gemini 3 모델의 API 접근이 제한될 수 있습니다. Google Search 도구를 포함할 경우 1,500 RPD(일일 요청 한도) 이후부터 1,000 요청당 $35가 적용됩니다. (출처: Gemini API 가격 페이지, 2026.03.22)
마치며
Gemini API 도구 조합은 에이전트 개발의 복잡도를 줄여주는 방향으로 분명히 의미 있는 업데이트입니다. “Google Search로 웹을 검색하고, 그 결과를 내 백엔드 함수에 넘긴다”는 흐름이 하나의 API 호출 안에서 처리된다는 건 실용적인 이점이 분명합니다.
다만 현재 시점(2026.03)에는 몇 가지를 확인하고 시작하는 게 낫습니다. Gemini 3 전용 기능이므로 기존 2.5 코드베이스를 그대로 올리면 안 됩니다. Vercel AI SDK는 아직 지원 전입니다. `thought_signature`와 `id` 매핑을 빠뜨리면 예상치 못한 오류가 납니다. Google Search 외 내장 도구는 토큰이 입력에 포함되어 과금됩니다.
프로덕션 적용을 고려한다면 Interactions API와의 조합을 같이 검토하는 쪽이 낫습니다. 이 업데이트는 완성된 기능이라기보다 에이전트 아키텍처의 방향을 가리키는 첫 단추로 보입니다.
본 포스팅 참고 자료
본 포스팅은 2026년 3월 22일 기준으로 작성되었습니다. Gemini API의 기능·가격·정책은 구글의 업데이트에 따라 언제든지 변경될 수 있습니다. 최신 정보는 Google AI for Developers 공식 사이트에서 확인하시기 바랍니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다.
댓글 남기기