2026년 3월 18일, Google이 조용히 공개한 Gemini API 업데이트 하나가 개발자 커뮤니티에서 주목받고 있습니다. Google Search·Google Maps 같은 내장도구와 커스텀 함수 선언(function declarations)을 단일 API 요청 하나로 동시에 쓸 수 있게 됐습니다. 기존엔 둘을 조합하면 400 에러가 떴고, 개발자들이 우회 로직을 직접 짜야 했습니다. 그런데 막상 공식 문서를 뜯어보면, 편리해진 만큼 놓치기 쉬운 함정이 있습니다.
이게 왜 뉴스가 됐는지 — 6개월 전 얘기부터
그런데 실제로는 이게 오랫동안 안 됐습니다. 2026년 2월까지만 해도 공식 Gemini 3 문서에 “combining built-in tools with function calling is not yet supported”라고 명시돼 있었고, 이를 시도하면 Tool use with function calling is unsupported by the model 에러가 반환됐습니다.
💡 공식 발표 시점과 실제 사용 가능 시점을 같이 놓고 보면, 이 기능은 2025년 하반기부터 일부 개발자 환경에서 작동했다가 2026년 2월에 갑자기 막혔고, 결국 3월 18일에 공식 지원으로 정착했습니다. 즉, 오늘 처음 생긴 기능이 아니라 꽤 오랫동안 혼란이 있었던 영역입니다.
3월 18일 업데이트, 실제로 뭐가 달라졌나
2026년 3월 18일, Google은 Gemini API에 세 가지를 동시에 추가했습니다. ① 내장도구+커스텀 함수 단일 요청 조합, ② 도구 간 컨텍스트 순환(context circulation), ③ Gemini 3 패밀리에 Google Maps 그라운딩 확대. 이 세 가지는 세트로 이해해야 합니다. (출처: Google AI for Developers Blog, 2026.03.18)
핵심 변경을 한 문장으로 요약하면, 이제 하나의 tools 배열 안에 google_search와 function_declarations를 함께 넣을 수 있습니다. 기존에는 둘 중 하나만 선택해야 했고, 양쪽 데이터가 모두 필요한 경우 API를 두 번 호출하거나 별도 오케스트레이션 로직을 짜야 했습니다. 구글 공식 블로그는 “이 변경이 end-to-end 지연을 줄이고 에이전트 아키텍처를 단순화한다”고 밝혔습니다.
Python 예시 (gemini-3-flash-preview 기준)
config=types.GenerateContentConfig(
tools=[
types.Tool(
google_search=types.ToolGoogleSearch(), # 내장도구
function_declarations=[getWeather] # 커스텀 함수
),
],
include_server_side_tool_invocations=True # ← 이 플래그 필수!
)
include_server_side_tool_invocations=True 플래그를 켜지 않으면 컨텍스트 순환 자체가 작동하지 않습니다. 공식 문서에 “This flag needs to be enabled for built-in tool context circulation and tool combination”이라고 명시돼 있습니다. (출처: Gemini API 공식 문서 — Combine Tools, 2026.03.18 업데이트)
조합 기능을 쓰면 비용이 올라가는 이유
toolCall과 toolResponse가 프롬프트 토큰으로 잡힙니다
이게 많은 블로그가 다루지 않는 부분입니다. 공식 문서 Pricing 섹션에는 이렇게 적혀 있습니다: “toolCall and toolResponse parts in requests are counted towards prompt_token_count.” 조합 기능을 켜면 API가 매 턴마다 toolCall과 toolResponse 파트를 반환하고, 다음 요청에서 이 파트들을 포함한 대화 히스토리를 통째로 보내야 합니다. 히스토리가 쌓일수록 입력 토큰도 함께 불어납니다. (출처: Gemini API Developer Pricing 페이지, 2026.03.18 기준)
📊 Gemini 3.1 Flash 기준 토큰 단가 (2026.03 공식)
| 항목 | 단가 (유료 플랜) |
|---|---|
| 입력 토큰 (텍스트/이미지/영상) | $0.50 / 1M 토큰 |
| 출력 토큰 (thinking 포함) | $3.00 / 1M 토큰 |
| Google Search 그라운딩 | 월 5,000회 무료, 이후 $14 / 1,000 쿼리 |
| toolCall/toolResponse 파트 | 입력 토큰 단가로 과금 (별도 고지) |
출처: ai.google.dev/gemini-api/docs/pricing (2026.03.18 기준)
단, Google Search는 예외입니다. 공식 문서에 “Google Search already applies its own pricing model at the query level, so tokens are not double-charged”라고 명시돼 있습니다. Google Search 내장도구만큼은 toolCall/toolResponse가 토큰 이중 과금으로 이어지지 않습니다. 복잡한 멀티스텝 에이전트에서 Search 이외의 내장도구(Maps, URL Context, File Search)를 섞어 쓴다면 대화 히스토리가 길어질수록 입력 토큰 비용이 눈에 띄게 올라갑니다.
thought_signature를 빠뜨리면 에러가 납니다
히스토리를 그대로 돌려줘야 하는 이유
공식 문서에서 읽다 보면 thought_signature라는 필드가 등장합니다. 이 필드는 API가 각 파트와 함께 반환하는 암호화된 컨텍스트 데이터입니다. 공식 설명은 다음과 같습니다: “Context can’t be reconstructed without thought signatures; if you don’t return the thought signatures for all parts in every turn, the model will error out.” 즉, 이전 턴에서 받은 모든 파트를 있는 그대로 다음 요청 히스토리에 포함하지 않으면 에러가 납니다. (출처: Gemini API 공식 문서 — Combine Tools, 2026.03.18)
💡 공식 응답 구조와 실제 히스토리 구성 방식을 같이 들여다보면, 기존의 일반 함수 호출과 달리 각 파트의 id·tool_type·thought_signature 세 필드가 “반드시 유지돼야 하는 핵심 필드”로 분리되어 있습니다. 기존 LangChain 래퍼나 커스텀 히스토리 관리 로직이 이 세 필드를 무시하고 텍스트만 추출하는 방식이었다면, 조합 기능 도입 후 그냥 가져다 쓰면 에러가 날 수 있습니다.
특히 비동기 병렬 함수 호출을 쓸 때 id 필드가 중요합니다. API가 함수 호출 요청을 내릴 때 부여한 ID와, 개발자가 함수 응답을 돌려줄 때 넣는 ID가 정확히 일치해야 합니다. 여러 도구가 동시에 호출될 때 어떤 응답이 어떤 요청에 해당하는지 추적하는 유일한 수단이기 때문입니다.
AUTO 모드가 안 되는 게 실제로 어떤 영향인가
함수 호출을 모델에 맡기고 싶다면 조합 기능과 함께 못 씁니다
실제로 어떤 의미냐면, 조합 기능을 켠 상태에서 모델이 알아서 함수를 부를지 말지 결정하도록 AUTO로 놔두는 것이 안 됩니다. VALIDATED 모드가 강제 적용되는데, 이는 사전 검증된 함수 선언만 허용하는 방식입니다. 복잡한 에이전트 아키텍처에서 모델의 자율 판단에 맡기는 패턴을 쓰고 있었다면, 조합 기능 도입 후 동작 방식이 달라질 수 있습니다.
⚠️ 또 한 가지 주의할 점은, 내장도구들이 위치 정보와 현재 시각을 참조한다는 것입니다. 공식 문서에 “built-in tools like google_search rely on location and current time information, so if your system_instruction or function_declaration.description has conflicting location and time information, the tool combination feature might not work well”이라고 나와 있습니다. 시스템 프롬프트에 특정 도시나 날짜를 고정해두는 패턴을 쓴다면 Google Search 결과가 의도와 다르게 나올 수 있습니다.
Google Maps 조합은 Gemini 3 이상에서만 됩니다
어느 모델을 쓰느냐에 따라 쓸 수 있는 도구 조합이 다릅니다
이번 업데이트에서 Google Maps 그라운딩이 Gemini 3 패밀리로 확대됐다는 내용도 있습니다. “Gemini 3 model of choice”라는 표현이 공식 블로그에 쓰였고, Maps 지원 범위가 이전보다 넓어졌습니다. 그런데 역으로 생각하면, Gemini 2.5 계열 이하 모델에서 Maps를 조합 기능으로 쓰려 할 때 지원 범위가 다릅니다. (출처: Google AI for Developers Blog, 2026.03.18)
| 도구 | 실행 위치 | 컨텍스트 순환 |
|---|---|---|
| Google Search | 서버 측 | ✅ 지원 |
| Google Maps | 서버 측 | ✅ 지원 (Gemini 3~) |
| URL Context | 서버 측 | ✅ 지원 |
| File Search | 서버 측 | ✅ 지원 |
| Code Execution | 서버 측 | ✅ 자체 내장 |
| Computer Use | 클라이언트 측 | ✅ 자체 내장 |
| 커스텀 함수 | 클라이언트 측 | ✅ 자체 내장 |
공식 문서는 생성형 콘텐츠 API(generateContent) 사용도 가능하지만, 복잡한 에이전트 워크플로우에는 새로 나온 Interactions API를 권장한다고 밝혔습니다. 서버 측 상태 관리와 통합 추론 트레이스(unified reasoning traces)를 지원하기 때문입니다. 기존에 generateContent로 구성한 에이전트를 그대로 쓸 수는 있지만, 장기적으로는 Interactions API로의 전환을 고려해볼 타이밍입니다.
자주 나오는 질문 5가지
Q1. 무료 티어에서도 도구 조합 기능을 쓸 수 있나요?
▾
Q2. LangChain이나 LangGraph를 쓰는데 별도 설정이 필요한가요?
▾
include_server_side_tool_invocations 플래그와 thought_signature 필드를 히스토리에 그대로 유지하는 부분은 대부분의 프레임워크 래퍼가 자동으로 처리하지 않습니다. 사용하는 LangChain 버전이 Gemini API의 이번 업데이트를 반영했는지 확인이 필요합니다. 공식 문서는 직접 Gen AI SDK를 활용하거나 Interactions API를 사용하는 것을 권장하고 있습니다.
Q3. Google Search 비용이 이중으로 청구되지 않는다는 게 정확히 무슨 뜻인가요?
▾
Q4. 이전에 내장도구와 함수호출을 조합하면 에러가 나던 문제는 완전히 해결된 건가요?
▾
include_server_side_tool_invocations=True를 명시하지 않으면 여전히 에러가 날 수 있습니다. 플래그를 켜지 않은 상태로 기존 코드에 내장도구와 함수 선언을 함께 넣으면, 이전과 동일하게 400 에러를 만날 수 있습니다. 3월 18일 업데이트는 조합 자체를 허용하되, 반드시 이 플래그를 통해 명시적으로 활성화하는 방식을 택했습니다.
Q5. Gemini 2.5 Flash에서도 이 기능을 쓸 수 있나요?
▾
gemini-3-flash-preview를 기준으로 작성돼 있습니다. Google Maps 그라운딩의 Gemini 3 패밀리 확대는 이번 업데이트의 주요 내용이므로, Gemini 2.5 계열에서 Maps를 조합 기능으로 쓰는 경우 지원 범위가 다를 수 있습니다. Search·URL Context 등 다른 내장도구와 함수 선언의 조합은 Gemini 2.5 이상에서도 플래그 활성화 조건 하에 가능하지만, Google이 공식 문서에서 별도 범위를 명시하지 않은 모델은 직접 테스트해보는 것이 안전합니다.
마치며 — 편리해진 만큼 꼼꼼히 봐야 할 것
다만 세 가지는 짚고 넘어가야 합니다. 첫째, include_server_side_tool_invocations=True 플래그와 thought_signature 유지는 이 기능을 쓰는 이상 선택이 아닙니다. 둘째, toolCall/toolResponse 파트가 히스토리에 쌓이면서 입력 토큰이 늘어나는 구조는 장기 멀티스텝 에이전트에서 예상보다 높은 비용으로 이어질 수 있습니다. 셋째, AUTO 모드가 지원되지 않아 모델 자율 판단 패턴을 쓰던 경우에는 동작 방식 재검토가 필요합니다.
6개월 넘게 개발자들이 기다리고, 잠깐 작동했다가 막혔다가, 이제 공식 지원이 된 기능입니다. “됩니다”라는 한 줄에 묻히기 쉬운 제약들을 공식 문서에서 직접 확인했습니다.
본 포스팅 참고 자료
- Google AI for Developers Blog — Gemini API Tooling Updates (2026.03.18)
https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tooling-updates/ - Gemini API 공식 문서 — Combine Tools and Function Calling (2026.03.18)
https://ai.google.dev/gemini-api/docs/tool-combination - Gemini API 출시 노트 (2026.03.18 업데이트 포함)
https://ai.google.dev/gemini-api/docs/changelog?hl=ko - Gemini Developer API 요금 페이지 (2026.03 기준)
https://ai.google.dev/gemini-api/docs/pricing - Google AI Developer Forum — Tool combination 에러 스레드 (2026.02.16)
discuss.ai.google.dev
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini API는 지속적으로 업데이트되며, 요금·모델명·지원 범위 등은 공식 페이지에서 최신 내용을 확인하시기 바랍니다. 본 글에 포함된 가격 정보는 2026년 3월 18일 공식 요금 페이지 기준이며, 환율 변동에 따라 실제 청구 금액은 다를 수 있습니다.
댓글 남기기