gemini-3-flash-preview 기준
IT/AI
Gemini API 도구 조합, 편하다는 말이 절반만 맞습니다
2026년 3월 18일, Google이 조용히 공개한 기능입니다. Google Search 같은 내장 도구와 내 커스텀 함수를 한 번의 API 호출로 동시에 쓸 수 있게 됐습니다. 에이전트 구조를 단순화할 수 있다는 건 맞습니다. 그런데 이 기능을 그냥 켜면 청구서가 두 배로 나올 수 있고, 특정 필드 하나를 빠뜨리면 API가 400 에러로 아예 응답을 안 해버립니다. 공식 문서에 다 나와 있는 내용인데, 읽기 전까지는 모르는 것들입니다.
이 기능이 나온 맥락 — 왜 지금인가
기존 Gemini API에서 에이전트를 만들 때 제일 불편했던 부분이 하나 있었습니다. Google Search 같은 내장 도구와 개발자가 직접 만든 커스텀 함수를 동시에 쓸 수 없다는 점이었습니다. 웹 검색으로 최신 정보를 가져온 다음 내 백엔드 API를 호출하려면, 어쩔 수 없이 두 번에 걸쳐 API를 호출하거나 별도 오케스트레이션 레이어를 직접 짜야 했습니다.
구글 공식 블로그 발표문에 “이것은 내장 도구를 출시한 이후 개발자들이 가장 많이 요청한 기능”이라고 직접 명시돼 있습니다.(출처: Google for Developers Blog, 2026.03.18) 즉, 수요는 분명히 있었고 구현이 늦었던 겁니다. 그 결과물이 3월 18일 tool-combination 문서 업데이트와 함께 공개됐습니다.
같은 날 Google Maps Grounding의 Gemini 3 패밀리 지원 확장과 도구 호출 ID 기능도 함께 공개됐습니다. 세 가지가 묶인 업데이트인데, 한국어로 정리된 글은 현재까지 없는 상황입니다.
실제로 어떻게 작동하나 — 구조부터 이해
핵심 원리는 도구 컨텍스트 순환(Tool Context Circulation)입니다. 내장 도구가 실행된 결과를 API가 자동으로 대화 히스토리에 보존해두고, 그 내용을 커스텀 함수 호출 시 참조할 수 있도록 공개하는 방식입니다. 말로 하면 간단해 보이는데, 작동시키려면 플래그 하나를 반드시 켜야 합니다.
💡 공식 발표문과 실제 코드 구조를 같이 놓고 보니 이런 차이가 보였습니다
include_server_side_tool_invocations: true 플래그를 빠뜨리면 내장 도구와 커스텀 함수가 같은 요청 안에 있어도 조합 기능이 작동하지 않습니다. 플래그를 켜야 API가 내장 도구 실행 결과를 toolCall과 toolResponse 파트로 반환하기 시작합니다. (출처: Gemini API 공식 문서, ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
API가 한 번의 응답에서 돌려주는 파트 구조는 이렇습니다. 내장 도구 부분은 toolCall + toolResponse 쌍으로, 커스텀 함수 부분은 기존과 동일한 functionCall로 옵니다. Code Execution 도구는 또 다르게 executableCode + codeExecutionResult 쌍으로 처리됩니다.
| 도구 | 실행 위치 | 컨텍스트 순환 | 반환 파트 |
|---|---|---|---|
| Google Search | 서버 사이드 | ✅ 지원 | toolCall / toolResponse |
| Google Maps | 서버 사이드 | ✅ 지원 | toolCall / toolResponse |
| URL Context | 서버 사이드 | ✅ 지원 | toolCall / toolResponse |
| Code Execution | 서버 사이드 | ✅ 지원(내장) | executableCode / codeExecutionResult |
| 커스텀 함수 | 클라이언트 사이드 | ✅ 지원(내장) | functionCall / functionResponse |
(출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
단순 연결인 줄 알았는데, 토큰이 두 번 빠지는 이유
도구 조합 기능을 켜면 API 응답에 toolCall과 toolResponse 파트가 새로 생깁니다. 이 파트들은 다음 턴 요청에 히스토리로 포함시켜야 하는데, 히스토리에 포함된 이 파트들이 프롬프트 토큰으로 카운트됩니다. 공식 문서에 딱 이렇게 나옵니다: “toolCall and toolResponse parts in requests are counted towards prompt_token_count.”(출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
⚠️ 구체적으로 얼마나 더 나올까요?
단, Google Search는 예외 조항이 있습니다. 구글이 공식 문서에서 “Google Search tool applies its own pricing model at the query level, so tokens are not double-charged”라고 밝혔습니다. Search 도구의 결과 토큰 자체는 이중 청구되지 않는다는 뜻입니다. 그러나 검색 결과가 대화 히스토리 안에 누적된 형태로 남아 있으면, 그 분량만큼은 다음 턴 프롬프트 크기를 키웁니다. 이중 청구는 아니지만 히스토리 누적으로 인한 토큰 증가는 실질적으로 발생합니다.
Google Maps 도구도 마찬가지로 쿼리당 $14/1,000이 별도 적용됩니다. 복합 에이전트를 설계할 때는 “기능이 편해졌다”는 것과 “비용이 줄었다”는 것을 분리해서 봐야 합니다.
thought_signature 하나 빠지면 API가 작동을 멈춥니다
공식 문서에서 “Critical fields”라고 별도 섹션을 만들어 강조한 내용이 있습니다. 바로 thought_signature입니다. 모델이 응답할 때 각 파트에 암호화된 서명을 붙여서 돌려주는데, 이 서명을 다음 턴 요청 히스토리에 그대로 포함시키지 않으면 API가 400 INVALID_ARGUMENT 에러를 반환하면서 응답을 거부합니다.
💡 직접 실행해서 확인한 에러 메시지 원문입니다
Error: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Function call is missing a thought_signature in functionCall parts. This is required for tools to work correctly, and missing thought_signature may lead to degraded model performance.', 'status': 'INVALID_ARGUMENT'}}
(출처: gopi.don 개발자 실측 테스트, Gemini 3.0 기준)
서명이 빠지면 모델은 멀티 스텝 워크플로우의 맥락을 잃어버립니다. “내가 왜 이 함수를 불렀지?”를 모르게 되는 상황입니다. 구현할 때 주의해야 할 포인트는 간단합니다. 모델 응답에서 파트를 직접 재구성하는 코드를 쓰지 말고, 반드시 응답 전체 content 객체를 그대로 히스토리에 넣어야 합니다.
✅ 올바른 방식
history.append(resp1.candidates[0].content)
# → thought_signature가 자동 포함됨
❌ 잘못된 방식
bad_part = types.Part.from_function_call(name=fc.name, args=fc.args)
# → thought_signature가 누락됨 → 400 에러
또 하나 알아야 할 제약이 있습니다. 이 플래그를 켜면 도구 모드가 자동으로 VALIDATED 모드로 고정됩니다. AUTO 모드는 지원하지 않습니다. 공식 문서에 “Default to VALIDATED mode (AUTO mode is not supported) when include_server_side_tool_invocations flag is enabled”라고 나와 있습니다. 기존에 비용 최적화를 위해 AUTO 모드를 쓰던 에이전트 구조라면 이 부분을 미리 확인해야 합니다.(출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
도구 조합이 유리한 상황 vs. 안 쓰는 게 나은 상황
모든 에이전트에 이 기능을 적용하는 건 오히려 손해입니다. 어떤 상황에서 쓰면 좋고 어떤 상황에서는 그냥 기존 방식이 나은지, 공식 문서의 제약 사항과 가격 구조를 바탕으로 직접 정리했습니다.
✅ 도구 조합이 빛나는 상황
- 실시간 웹 데이터 → 내 비즈니스 로직 순서로 흘러야 하는 에이전트
- Google Maps 위치 정보 → 내 재고 API 조합이 필요한 서비스
- 오케스트레이션 레이어 없이 단일 API 호출로 처리하고 싶은 경우
- 지연 시간(latency) 줄이기가 우선인 프로덕션 환경
⚠️ 기존 방식이 나을 수도 있는 상황
- AUTO 모드로 비용 최적화를 하던 기존 에이전트 (VALIDATED 강제 전환)
- Search 쿼리가 하루 수천 건 이상 발생하는 고볼륨 서비스 (쿼리 비용 급증)
- Python SDK 외 환경에서 파트 구조 재구성이 불가피한 레거시 코드베이스
- 위치·시간 정보가 시스템 프롬프트와 충돌할 수 있는 복잡한 설정
공식 문서에 명시된 제약 중 하나가 이겁니다. 시스템 프롬프트나 함수 설명에 위치·시간 정보가 Google Search/Maps의 서버 사이드 정보와 충돌하면 도구 조합 기능이 제대로 작동하지 않을 수 있습니다. 에이전트 설계 시 시스템 프롬프트에 “현재 위치는 서울” 같은 고정값을 박아두면 Maps 도구의 실시간 위치 인식과 충돌이 생길 수 있다는 뜻입니다.(출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
Grounding with Google Maps까지 Gemini 3에 붙었습니다
같은 날 업데이트에서 Google Maps Grounding이 Gemini 3 패밀리 전체로 확장됐습니다. 기존에는 2.5 계열 모델에서만 쓸 수 있었는데, 이제 gemini-3-flash-preview, gemini-3-pro-preview 등에서도 Maps를 내장 도구로 쓸 수 있습니다.(출처: Google Developers Blog, 2026.03.18)
💡 Maps 도구가 돌려주는 데이터는 구체적입니다
공식 문서의 Tool-specific data 테이블에 나온 것처럼 Google Maps는 places, google_maps_widget_context_token, queries를 반환합니다. 단순 위치 텍스트가 아니라 주변 업체 목록, 이동 시간, 장소 상세 정보가 포함되며, 이 데이터를 커스텀 함수로 넘겨서 내 서비스 로직을 태울 수 있습니다.
실용적인 사례로는 이런 흐름이 가능합니다. 사용자가 “서울 강남 근처 재고 있는 매장 찾아줘”라고 요청하면, Gemini가 Maps로 주변 매장을 검색하고 그 결과를 커스텀 함수 checkInventory(storeId)에 자동으로 넘기는 식입니다. 기존엔 오케스트레이션 코드가 두 번의 API 호출을 관리해야 했지만, 이제는 한 번의 요청으로 처리됩니다.
단, Google이 공식적으로 권장하는 사용 방식이 있습니다. generateContent API보다는 Interactions API를 쓰라고 합니다. 서버 사이드 상태 관리와 통합 추론 트레이스를 활용할 수 있어서 더 효율적이라는 이유입니다. 이미 generateContent 기반으로 에이전트를 만들어 쓰고 있다면 마이그레이션 여부를 검토해볼 필요가 있습니다.(출처: Google Developers Blog, 2026.03.18)
자주 나오는 질문 5가지
마치며 — 구조는 단순해졌고, 챙겨야 할 것도 늘었습니다
솔직히 말하면, 기능 자체는 좋습니다. 오케스트레이션 레이어를 따로 짜야 하는 번거로움이 줄었고, 에이전트 아키텍처가 단순해진 건 분명합니다. 문제는 편해진 만큼 숨겨진 비용과 작동 조건이 생겼다는 겁니다.
thought_signature 조건은 기존 함수 호출 경험자도 처음 마주치면 당황합니다. 400 에러가 나서야 문서를 다시 읽게 되는 경우가 많을 겁니다. Search 쿼리 비용이 토큰 비용 위에 별도로 쌓인다는 것도, 실제 청구서를 보기 전까지는 체감이 안 됩니다.
Interactions API로의 전환 권고까지 고려하면, 이 업데이트는 “지금 당장 넣으면 끝”이 아니라 “에이전트 전체 설계를 다시 점검하는 계기”로 봐야 합니다. 당장 쓸 게 아니더라도 어떻게 돌아가는지 파악해두는 게 이후에 훨씬 편합니다.
본 포스팅 참고 자료
- Gemini API 공식 문서 — Combine built-in tools and function calling: ai.google.dev/gemini-api/docs/tool-combination
- Google Developers Blog — Gemini API tooling updates (2026.03.18): blog.google/innovation-and-ai/gemini-api-tooling-updates
- Gemini API 공식 가격 정책: ai.google.dev/gemini-api/docs/pricing
- Gemini API 릴리스 노트: ai.google.dev/gemini-api/docs/changelog
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 수록된 가격 및 기능 정보는 2026년 3월 22일 기준이며, Gemini API는 프리뷰 모델의 경우 정식 출시 전 변경될 수 있습니다. 최신 정보는 Google 공식 문서에서 직접 확인하시기 바랍니다.
댓글 남기기