Gemini 3 Flash Preview 기준
공식 문서 직접 확인
Gemini API 도구 조합, 한 번에 된다는 말이 반만 맞는 이유
Google이 드디어 내장 도구(Google Search·Maps)와 커스텀 함수를 단일 API 호출에서 조합하는 기능을 출시했습니다. 개발자들이 가장 많이 요청하던 기능이라고 구글이 직접 밝혔는데, 막상 써보면 조건이 하나 틀리면 바로 막힙니다.
이번 업데이트에서 실제로 달라진 것
2026년 3월 17일, 구글이 Gemini API에 세 가지 기능을 한꺼번에 공개했습니다. 구글 공식 블로그(blog.google, 2026.03.17)에서 직접 확인한 내용입니다.
첫째, 내장 도구(Google Search, Google Maps, URL 컨텍스트)와 커스텀 함수를 단일 요청에 담을 수 있게 됐습니다. 지금까지는 내장 도구를 쓸 때와 함수 호출을 쓸 때를 따로 오케스트레이션해야 했습니다. 검색으로 실시간 데이터를 가져온 다음 그 결과를 백엔드 함수에 넘기는 흐름을 하나의 API 호출로 처리할 수 있습니다.
둘째, 컨텍스트 순환(Context Circulation) 기능이 추가됐습니다. 멀티스텝 워크플로에서 A 도구의 출력이 자동으로 B 도구의 입력이 됩니다. 기존에는 턴마다 컨텍스트를 수동으로 이어 붙여야 했는데, 이제 `include_server_side_tool_invocations: true` 플래그 하나로 서버가 그 이력을 보존합니다.
셋째, Google Maps 그라운딩이 Gemini 3 모델 전체로 확장됐습니다. 2억 5천만 개 이상의 장소 데이터를 모델이 직접 참조할 수 있게 됩니다. (출처: Gemini API 공식 문서)
💡 공식 발표문과 실제 문서 제한사항을 같이 놓고 보니 “한 번에 다 된다”는 제목이 정확히 반쪽짜리라는 게 보였습니다. 기능은 열렸지만 모드 제한과 비용 구조가 생각과 다릅니다.
작동 구조 — thought_signature를 빠뜨리면 바로 오류
도구 조합이 작동하는 방식을 이해하려면 세 가지 응답 파트를 알아야 합니다. 공식 문서(ai.google.dev, 2026.03.21 최종 업데이트)에 딱 이렇게 나옵니다.
| 파트 종류 | 역할 | 주의사항 |
|---|---|---|
| toolCall / toolResponse | 내장 도구 호출 기록 | 서버 측 자동 처리, 그대로 반환 필수 |
| functionCall / functionResponse | 커스텀 함수 호출·응답 | 클라이언트가 직접 id 매핑 필요 |
| thought_signature | 암호화된 컨텍스트 | 모든 파트에 존재. 하나라도 빠지면 오류 발생 |
여기서 많이 놓치는 부분이 `thought_signature`입니다. 각 응답 파트마다 암호화된 컨텍스트 값이 붙어 있는데, 다음 턴에 요청할 때 이 값을 그대로 전부 돌려보내야 합니다. 공식 문서는 “사고 서명 없이는 컨텍스트를 재구성할 수 없다”고 명시하고 있습니다.
실수하기 쉬운 패턴은 응답에서 텍스트만 파싱해서 다음 요청에 넣는 방식입니다. 기존 Gemini 2.5 기반 코드를 Gemini 3로 올리면서 파트 전체를 history에 넣지 않으면 즉시 오류가 납니다. 이건 공식 문서에 나와 있는 내용이지만, 기존에 작성된 한국어 블로그 글 대부분이 이 부분을 다루지 않았습니다.
💡 기존 함수 호출 코드에 내장 도구만 추가하면 될 것 같지만, history 직렬화 방식을 바꾸지 않으면 두 번째 턴부터 무너집니다. 새로 추가된 필드를 포함한 전체 파트를 넘겨야 합니다.
Maps 그라운딩, 무료인 줄 알았는데
Google Maps 그라운딩은 무료 등급에서 하루 1,500건까지만 무료입니다. 이걸 넘으면 1,000건당 $25가 청구됩니다. (출처: Gemini API 공식 문서 — 가격 및 비율 제한 항목)
직접 계산해보면 이렇습니다. 일 1,500건을 초과한다고 가정할 때, 하루 3,000건 요청 시 초과분 1,500건에 대해 $37.5가 발생합니다. 월로 환산하면 약 $1,125입니다. 여행 플래너 앱처럼 위치 쿼리가 잦은 서비스에서는 비용이 예상보다 빠르게 올라갑니다.
반면 Google Search 그라운딩은 무료 등급에서 월 5,000건이 기준이고, 유료는 1,000건당 $14입니다. (출처: Gemini API 가격 페이지) Maps 쪽이 Search보다 단가가 비쌉니다. 위치 기반 쿼리라고 해서 자동으로 Maps를 켜는 게 아니라, 지리적 의도가 명확한 경우에만 선택적으로 활성화하는 게 비용 관리에 유리합니다.
| 도구 | 무료 한도 | 초과 요금 |
|---|---|---|
| Google Search | 월 5,000건 | $14 / 1,000건 |
| Google Maps | 일 1,500건 | $25 / 1,000건 |
Search는 월 기준, Maps는 일 기준이라는 점도 다릅니다. Maps 쪽 무료 한도가 더 촘촘합니다.
AUTO 모드가 안 된다는 게 실제로 의미하는 것
“도구 조합 기능을 켜면 AUTO 모드가 지원되지 않고 VALIDATED 모드로 강제 전환된다.” 공식 문서 Limitations 항목에 이렇게 나와 있습니다. 그런데 AUTO와 VALIDATED의 차이를 모르면 이게 왜 문제인지 와닿지 않습니다.
AUTO 모드는 모델이 도구를 언제 쓸지 스스로 판단합니다. VALIDATED 모드는 모델이 도구 사용 계획을 먼저 반환하고, 개발자가 그것을 검토한 뒤 실행을 승인하는 방식입니다. 보안이나 사람 개입이 필요한 워크플로에서는 오히려 좋지만, 완전 자동화를 목표로 하는 에이전트 시나리오에서는 개발자가 매 턴마다 개입 로직을 직접 구현해야 한다는 뜻입니다.
즉, “도구 조합으로 에이전트가 알아서 다 해준다”는 기대는 현재 구조에서는 반만 맞습니다. 모델이 어떤 도구를 어떤 순서로 쓸지는 자율적으로 결정하지만, AUTO 모드가 막혀 있기 때문에 완전 자율 실행 파이프라인을 구성하려면 추가 구현이 필요합니다.
💡 도구 조합 기능의 가장 큰 가치는 오케스트레이션 레이어를 직접 짜지 않아도 된다는 것인데, AUTO 모드 제한이 있어서 완전한 오케스트레이션 제거는 아직 한 단계 남아 있습니다.
Vercel AI SDK 사용자는 3월 18일 이후에도 못 쓴다
구글 공식 Python·JavaScript·Go SDK와 REST API는 `include_server_side_tool_invocations: true` 플래그로 이번 기능을 바로 쓸 수 있습니다. 그런데 Vercel AI SDK(`@ai-sdk/google`)를 쓰는 경우는 다릅니다.
Vercel AI SDK의 GitHub 이슈(vercel/ai #11695, 2026.01.09 등록)에는 Gemini 3 모델에서 provider-defined 도구(google.tools.googleSearch())와 일반 function tool을 조합하려 하면 다음 오류가 납니다.
AI SDK Warning: The feature "combination of function and provider-defined tools" is not supported.
이슈가 2026년 1월에 등록됐고 3월 현재까지 해결책이 없습니다. `useSearchGrounding: true` 방식도 Gemini 3에서는 작동하지 않습니다. Vercel AI SDK를 통해 Gemini 3 기반 에이전트를 구성 중이라면, 이번 구글 공식 발표가 자신의 환경에는 바로 적용되지 않을 수 있습니다. 구글 공식 SDK나 REST API 직접 호출로 전환해야 이 기능을 활용할 수 있습니다.
도구 조합을 쓸 만한 실제 시나리오와 쓰면 안 되는 경우
공식 문서와 실제 제한사항을 교차해서 보면 이 기능이 잘 맞는 구조와 안 맞는 구조가 나뉩니다.
지금 당장 쓰기 좋은 경우
실시간 웹 검색 결과를 내부 API(재고 조회, 예약 시스템 등)로 후처리해야 하는 워크플로가 대표적입니다. 예를 들어 “오늘 날씨가 어때?” → Google Search로 현재 날씨 수집 → 내부 venue booking API로 호출하는 흐름이 단일 요청에서 처리됩니다. 대화 기록 관리 오버헤드가 줄어들고 엔드 투 엔드 지연도 줄어듭니다.
여행 일정 생성처럼 위치 데이터가 중요한 경우에도 Maps 그라운딩과 커스텀 함수 조합이 효과적입니다. 구글은 공식 문서에서 Maps 그라운딩으로 주변 레스토랑을 검색하고, 자체 예약 API를 함께 호출하는 예시를 직접 보여주고 있습니다.
지금 쓰면 문제가 생길 수 있는 경우
완전 무인 자동화 에이전트를 구성하려는 경우입니다. AUTO 모드 미지원으로 인해 각 턴마다 개발자 측에서 실행 제어 로직이 필요합니다. 또한 Maps 그라운딩을 쓸 때는 지리적 의도가 없는 일반 쿼리에서도 도구가 활성화되면 불필요한 비용이 발생합니다. 공식 문서에서 “명확한 지리적 컨텍스트가 있는 경우에만 활성화하라”고 권장하는 이유가 여기에 있습니다.
📊 Interactions API와의 관계
구글은 이번 도구 조합 기능을 쓸 때 `generateContent` API 대신 Interactions API를 권장합니다. 서버 사이드 상태 관리와 통합된 추론 추적이 Interactions API에서 더 잘 지원되기 때문입니다. 이미 generateContent로 구성한 코드가 있다면 구조 전환 비용이 발생할 수 있습니다.
Q&A
Q1. Gemini 2.5 Pro에서도 도구 조합이 가능한가요?
가능합니다. 공식 문서의 지원 모델 표를 보면 Gemini 2.5 Pro와 Gemini 2.5 Flash에서도 Maps 그라운딩이 지원됩니다. 다만 이번 3월 업데이트는 Gemini 3 모델 계열에 초점을 맞춘 발표였고, Gemini 3 Flash Preview 모델 ID(`gemini-3-flash-preview`)가 예시 코드에 사용됩니다.
Q2. include_server_side_tool_invocations 플래그를 안 켜도 도구가 작동하나요?
플래그 없이도 내장 도구나 함수 호출 각각은 작동합니다. 하지만 둘을 동시에 조합하거나 컨텍스트 순환을 쓰려면 반드시 이 플래그를 true로 설정해야 합니다. 공식 문서에 “도구 컨텍스트 순환을 사용 설정하려면 include_server_side_tool_invocations 플래그를 true로 설정해야 합니다”라고 직접 명시돼 있습니다.
Q3. Maps 그라운딩을 쓸 때 중국, 북한 등 일부 국가에서 배포하면 어떻게 되나요?
구글 공식 문서에 ‘제한 지역’ 목록이 명시돼 있습니다. 중국, 북한, 이란, 쿠바, 시리아, 베트남, 크리미아, 도네츠크·루한스크 인민공화국이 포함됩니다. 이 지역에서 Maps 그라운딩을 포함한 애플리케이션을 배포하거나 마케팅해서는 안 되며, 이 목록은 업데이트될 수 있다고 공식 문서에 나와 있습니다.
Q4. 코드 실행 도구(Code Execution)도 이번 도구 조합에 포함되나요?
포함됩니다. 코드 실행은 서버 측 도구로 분류되어 컨텍스트 순환을 지원합니다. 다만 functionCall·functionResponse 대신 executableCode와 codeExecutionResult 파트를 사용합니다. Computer Use는 클라이언트 측 도구로, 자체 내장 컨텍스트 순환 솔루션이 따로 있습니다.
Q5. Google AI Studio에서 무료로 도구 조합을 테스트해볼 수 있나요?
가능합니다. Google AI Studio에서는 API 키 발급 후 Gemini API의 무료 등급에서 도구 조합 기능을 실험할 수 있습니다. Maps 그라운딩은 무료 등급에서 일 1,500건까지 무료입니다. 다만 AI Studio 자체 인터페이스보다는 Python·JavaScript SDK나 REST API로 직접 요청을 구성해야 `include_server_side_tool_invocations` 플래그를 제어할 수 있습니다.
마치며
솔직히 말하면, 이번 Gemini API 도구 조합 기능은 개발자들이 오랫동안 요청했던 것이고 방향도 맞습니다. Google Search와 Maps, 커스텀 함수를 한 호출에서 처리할 수 있다는 건 에이전트 아키텍처를 훨씬 단순하게 만들어줍니다.
다만 세 가지는 기억해야 합니다. `thought_signature`를 포함한 전체 파트를 history에 그대로 넘겨야 두 번째 턴부터 작동하고, AUTO 모드가 막혀 있어서 완전 자율 실행은 아직 한 단계 남아 있습니다. Maps 그라운딩을 필요하지 않은 쿼리에까지 켜두면 1,000건당 $25라는 단가가 생각보다 빠르게 누적됩니다.
Vercel AI SDK 사용자라면 아직 이 기능을 바로 쓸 수 없습니다. 구글 공식 SDK나 REST API로 전환하거나 해당 이슈의 해결을 기다려야 합니다. 기능이 열렸다는 소식은 맞지만, 본인 환경과 도구 스택을 먼저 확인하는 게 순서입니다.
본 포스팅 참고 자료
- 구글 공식 블로그 — Gemini API tooling updates: context circulation, tool combos and Maps grounding for Gemini 3
https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tooling-updates/ - Gemini API 공식 문서 — 기본 제공 도구와 함수 호출 결합 (2026.03.21 최종 업데이트)
https://ai.google.dev/gemini-api/docs/tool-combination?hl=ko - Gemini API 공식 문서 — Google 지도를 사용한 그라운딩
https://ai.google.dev/gemini-api/docs/maps-grounding?hl=ko - Gemini API 가격 페이지
https://ai.google.dev/gemini-api/docs/pricing?hl=ko - Vercel AI SDK GitHub 이슈 — Gemini 3 도구 조합 미지원
https://github.com/vercel/ai/issues/11695
※ 본 포스팅은 2026년 3월 23일 기준 공식 문서를 참고해 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 특히 Gemini API의 요금 구조, 지원 모델, 제한사항은 구글의 업데이트에 따라 달라질 수 있으니 항상 공식 문서를 병행해서 확인하시기 바랍니다.
댓글 남기기