오늘 출시된 기능, 정확히 무엇이 달라졌나요?

2026년 3월 18일, Gemini API 공식 릴리스 노트에 한 줄이 추가됐습니다. “Built-in Tools and Function Calling Combination 기능이 출시됐습니다. 이제 하나의 API 호출에서 Gemini 빌트인 툴과 커스텀 함수 호출을 함께 사용할 수 있습니다.”(출처: Gemini API 출시 노트, 2026.03.18)

이전까지는 Google Search 같은 빌트인 툴을 쓸 때 개발자가 직접 만든 함수(예: 사내 DB 조회 함수)를 같은 요청에 넣을 수 없었습니다. 검색으로 최신 정보를 가져오고, 그 결과를 토대로 사내 API를 호출하는 흐름을 한 번에 처리하려면 매번 별도 요청을 두 번 보내야 했죠. 오늘 출시된 기능은 그 장벽을 없앤 겁니다.

지원 모델은 현재 gemini-3-flash-preview와 gemini-3.1-pro-preview입니다. Gemini 2.x 계열에서는 동작하지 않습니다.(출처: Gemini API 공식 문서 — Combine built-in tools and function calling, 2026.03.18)

▲ 목차로 돌아가기

toolCall·toolResponse도 프롬프트 토큰으로 빠져나갑니다

잘못 알고 있으면 청구서에서 놀랍니다

대부분 개발자들이 “API 호출 비용 = 내가 보낸 프롬프트 + 모델 응답”이라고 생각합니다. 그런데 툴 조합 기능을 켜는 순간 이 공식이 바뀝니다. 공식 문서에 명확하게 적혀 있습니다. “toolCall 및 toolResponse 파트는 prompt_token_count에 포함됩니다. 이 중간 도구 단계가 이제 노출되므로, 요청의 대화 기록에 포함됩니다.”(출처: Gemini API 공식 문서 — Tokens and pricing, 2026.03.18)

구체적으로 어떤 의미인지 계산해보겠습니다. Google Search 빌트인 툴이 실행되면 API는 toolCall 파트(검색 쿼리 포함)와 toolResponse 파트(검색 결과 포함)를 반환합니다. 다음 턴에서 이 파트들을 히스토리에 넣어 전달해야 하는데, 그 부피가 그대로 프롬프트 토큰으로 청구됩니다.

예를 들어 Google Search 결과로 500토큰 분량의 toolResponse가 반환됐다면, Turn 2에서 그 500토큰은 고스란히 입력 토큰 비용에 더해집니다. Gemini 3.1 Pro 기준 입력 토큰 가격은 200K 이하일 때 100만 토큰당 $1.25 (출처: Gemini API Pricing, March 2026)이므로 턴이 길어질수록 누적 비용은 예상치를 초과합니다. 이 구조를 모른 채 멀티턴 에이전트를 설계하면 비용 예산이 틀어집니다.

▲ 목차로 돌아가기

AUTO 모드가 왜 안 되는 걸까요?

함수 호출을 편하게 써온 방식이 여기서 막힙니다

Gemini API의 함수 호출에는 세 가지 모드가 있습니다. AUTO(모델이 알아서 판단), ANY(반드시 함수 호출), NONE(함수 호출 금지)입니다. 기존 코드를 짜본 분들은 대부분 AUTO 모드를 씁니다. 모델이 판단해서 알아서 처리하니 편하기 때문이죠.

그런데 include_server_side_tool_invocations: true 플래그를 켜서 툴 조합을 활성화하면, AUTO 모드가 지원되지 않습니다. 공식 문서의 Limitations 항목에 명확히 적혀 있습니다. “include_server_side_tool_invocations 플래그가 활성화된 경우 AUTO 모드가 아닌 VALIDATED 모드로 기본 동작합니다.”(출처: Gemini API 공식 문서 — Limitations, 2026.03.18)

VALIDATED 모드는 모델이 반환한 함수 호출 구조가 선언한 스키마와 일치하는지 엄격하게 검사합니다. 기존 코드에서 느슨하게 스키마를 정의했거나, 선택적 파라미터를 일부 생략했다면 400 에러로 바로 막힐 수 있습니다. 기존 function calling 코드에 빌트인 툴만 추가하면 되겠다고 생각했다면, 이 제약이 걸림돌이 됩니다.

▲ 목차로 돌아가기

2월부터 이미 쓰다가 막힌 팀들이 있었습니다

오늘 출시됐다고 하는데, 사실 3~4주 전부터 쓰던 기능입니다

이 부분이 가장 주목할 만한 부분입니다. 오늘 공식 출시됐지만, 실제로는 2월 초중순부터 파일 검색(fileSearch)과 함수 호출을 조합해 쓰던 개발자들이 존재했습니다. Gemini API 공식 개발자 포럼에는 2월 16일부터 관련 스레드가 열렸습니다.

포럼 글에 따르면 2026년 2월 9일 전후로 fileSearch와 functionDeclarations를 동시에 사용하던 프로덕션 코드가 갑자기 400 에러를 반환하기 시작했습니다. 에러 메시지는 “Tool use with function calling is unsupported by the model.”이었습니다. 구현을 바꾼 게 없는데, 같은 모델 ID를 가리키는 백엔드가 업데이트되면서 발생한 문제였습니다.(출처: Google AI Developer Forum, 2026.02.16)

한 팀은 임시방편으로 파일 검색 전용 서브에이전트를 만들어 함수 선언으로 감싸는 방식을 택했는데, 이 자체가 라운드트립을 한 번 더 추가해 응답 지연을 악화시켰다고 공개적으로 언급했습니다. 오늘 출시된 공식 기능이 바로 이 문제의 공식 해결책입니다.

▲ 목차로 돌아가기

include_server_side_tool_invocations 플래그 하나로 모든 게 결정됩니다

이 플래그를 빠뜨리면 조합이 안 됩니다

공식 문서에 “This flag needs to be enabled for built-in tool context circulation and tool combination”이라고 명확히 나옵니다. 즉, include_server_side_tool_invocations: true가 없으면 빌트인 툴과 함수 호출을 동시에 선언해도 조합이 작동하지 않습니다.(출처: Gemini API 공식 문서, 2026.03.18)

Python SDK 기준으로 GenerateContentConfig에 include_server_side_tool_invocations=True를 추가해야 합니다. REST API를 직접 사용한다면 toolConfig 안에 "includeServerSideToolInvocations": true를 넣어야 합니다. 플래그가 빠지면 기존 방식과 동일하게 동작하며 400 에러도 발생하지 않기 때문에, 조합이 안 되는지조차 모르고 지나칠 수 있습니다.

from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3-flash-preview",
contents="미국 최북단 도시는 어디? 오늘 거기 날씨는?",
config=types.GenerateContentConfig(
tools=[
types.Tool(
google_search=types.ToolGoogleSearch(),   # 빌트인 툴
function_declarations=[getWeather]         # 커스텀 함수
),
],
include_server_side_tool_invocations=True  # ← 이 줄이 핵심
),
)

또한 턴 간에 toolCall, toolResponse, thought_signature 파트를 모두 그대로 히스토리에 포함해 다음 요청에 넣어야 합니다. 하나라도 빠지면 모델이 오류를 반환합니다. 특히 thought_signature가 누락되면 400 에러가 발생하는데, 이 필드는 암호화된 내부 추론 컨텍스트이므로 임의로 수정하거나 생략해서는 안 됩니다.

▲ 목차로 돌아가기

customtools 전용 엔드포인트가 따로 있다는 걸 모르는 분들이 많습니다

함수 호출 성능이 예상보다 낮을 때 먼저 바꿔볼 수 있는 것

Gemini API 2026년 2월 19일 릴리스 노트에 조용히 추가된 항목이 있습니다. gemini-3.1-pro-preview-customtools라는 별도 엔드포인트입니다. 설명은 간결합니다. “bash와 툴을 혼합해서 사용하는 경우 커스텀 툴의 우선순위를 더 잘 지정합니다.”(출처: Gemini API 출시 노트, 2026.02.19)

이는 단순히 편의를 위한 이름 분리가 아닙니다. 구글이 빌트인 툴(구글 검색, 지도 등)의 비중이 높은 기본 모델과, 커스텀 함수 호출이 많은 에이전트 워크플로에 최적화된 모델을 분리해서 운영한다는 의미입니다. 빌트인 툴과 함수 호출을 조합할 때 함수 호출 응답 품질이 기대에 못 미친다면, gemini-3.1-pro-preview에서 gemini-3.1-pro-preview-customtools로 전환하는 것이 공식 권장 경로입니다.

(출처: Gemini API 공식 문서 — Changelog 2026.02.19, tool-combination 2026.03.18)

▲ 목차로 돌아가기

자주 묻는 것들

▲ 목차로 돌아가기

마치며

Gemini API 툴 조합 기능은 분명히 에이전트 개발의 병목 하나를 해소하는 업데이트입니다. 빌트인 툴과 커스텀 함수를 한 번의 API 호출로 엮을 수 있다는 건, 라운드트립을 줄이고 응답 시간을 줄인다는 의미니까요.

다만 솔직히 말하면, 공식 문서를 열어보기 전까지 모르고 지나치기 쉬운 함정이 세 가지나 있었습니다. toolCall/toolResponse 파트의 토큰 과금, AUTO 모드 미지원, thought_signature 필드 강제 반환. 이 세 가지를 모른 채 프로덕션 코드를 짜면 비용 초과 또는 400 에러로 돌아올 가능성이 높습니다.

공식 문서에서 직접 확인하지 않았다면 놓쳤을 부분들입니다. 특히 customtools 전용 엔드포인트의 존재는 지금 시점에서 한국어로 정리된 곳이 거의 없습니다. 이번 정보가 Gemini 에이전트를 구축 중인 분들께 실질적인 도움이 됐으면 합니다.

본 포스팅 참고 자료

1. Gemini API 출시 노트 (ai.google.dev/gemini-api/docs/changelog)
2. Gemini API 공식 문서 — Combine built-in tools and function calling (ai.google.dev, 2026.03.18 업데이트)
3. Gemini API Billing 공식 문서 (ai.google.dev/gemini-api/docs/billing)
4. Google AI Developer Forum — fileSearch + functionDeclarations 조합 오류 스레드 (2026.02.16)
5. Gemini API Pricing (March 2026) — TLDL.io