gemini-3-flash-preview 기준
Gemini API 도구 조합, 비용 함정 3가지 먼저 보세요
2026년 3월 18일, 구글이 드디어 Gemini API에서 내장 도구(Google 검색, Google Maps, 파일 검색 등)와 커스텀 함수 호출을 단일 API 호출 안에서 동시에 쓸 수 있는 기능을 정식 출시했습니다. 개발자들이 수개월간 요청하던 기능이 현실이 된 건데, 막상 공식 문서를 뜯어보면 기대와 다른 지점이 세 군데 있습니다. 비용이 더 나오는 구조, AUTO 모드 비활성화, thought_signature 오류까지 — 미리 알고 써야 하는 것들을 짚어봤습니다.
도구 조합 기능, 뭐가 달라졌나
지금까지 Gemini API에서 Google 검색 같은 내장 도구를 쓰면서 동시에 커스텀 함수 호출도 활성화하려면 별도로 요청을 나눠야 했습니다. 검색 결과를 한 번 받아서, 그 결과를 들고 다시 함수 호출 요청을 보내는 식이었죠. 오케스트레이션 레이어가 그 사이를 수동으로 연결했어야 합니다.
이번 업데이트로 단일 API 호출 안에서 내장 도구와 커스텀 함수를 동시에 선언할 수 있게 됐습니다. 구글 공식 블로그에는 “에이전트 아키텍처를 단순화하고 엔드투엔드 레이턴시를 줄인다”고 나와 있습니다. (출처: Google Blog, gemini-api-tooling-updates, 2026.03.17)
조합 가능한 도구는 Google 검색, Google Maps, URL 컨텍스트, 파일 검색, 코드 실행, 커스텀 함수 총 6종입니다. 이 중 Computer Use와 커스텀 함수는 클라이언트 사이드 도구이고, 나머지 4개는 서버 사이드 도구입니다. 서버 사이드 도구끼리는 구글이 직접 실행하고, 결과를 toolCall/toolResponse 형태로 돌려줍니다. 핵심은 이 부분이 토큰 과금 대상이 된다는 것입니다.
비용 구조: 중간 단계가 전부 청구됩니다
💡 공식 가격 문서와 도구 조합 문서를 같이 놓고 보니 이런 차이가 보였습니다. 조합 기능을 켜면 Google 검색 쿼리가 발생하는 것 외에도, 중간 도구 처리 결과가 전부 다음 턴의 prompt_token_count에 쌓입니다.
공식 문서에는 이렇게 나옵니다: “toolCall과 toolResponse 파트는 요청 시 prompt_token_count에 포함됩니다. 이 중간 도구 단계는 이제 사용자에게 노출되고 반환되므로 대화 기록의 일부가 됩니다.” (출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
쉽게 따라해볼 수 있는 계산을 해보면 — 질문 1개에 Google 검색이 붙고 커스텀 함수 1개가 실행되면, Turn 2 요청에는 원래 사용자 프롬프트 + toolCall 파트 + toolResponse 파트 + functionCall 파트가 모두 들어갑니다. 이 중간 컨텍스트가 수백 토큰이 넘을 수 있습니다.
| 모델 | 입력 단가 (200k 이하) | Google 검색 추가 비용 | Google Maps 추가 비용 |
|---|---|---|---|
| Gemini 3.1 Pro Preview | $2.00 / 1M토큰 | 월 5,000건 무료 후 $14 / 1,000쿼리 | 월 5,000건 무료 후 $14 / 1,000쿼리 |
| Gemini 3 Flash Preview | $0.50 / 1M토큰 | 월 5,000건 무료 후 $14 / 1,000쿼리 | 월 5,000건 무료 후 $14 / 1,000쿼리 |
| Gemini 2.5 Flash | $0.30 / 1M토큰 | 월 1,500 RPD 무료 후 $35 / 1,000쿼리 | 월 1,500 RPD 무료 후 $25 / 1,000쿼리 |
(출처: ai.google.dev/gemini-api/docs/pricing, 2026.03.22 기준) — 도구 조합을 쓸수록 중간 컨텍스트가 쌓여 토큰 청구가 복리로 늘어납니다.
AUTO 모드가 꺼지는 이유
일반 함수 호출에서는 tool_config에 mode: AUTO를 쓸 수 있습니다. 모델이 알아서 도구를 쓸지 말지 판단하는 모드입니다. 직접 써보면 편하고 대부분의 예제도 AUTO가 기본값입니다.
그런데 include_server_side_tool_invocations: true를 설정하면 AUTO 모드를 쓸 수 없습니다. 공식 문서에 “조합 플래그가 활성화된 경우 AUTO 모드는 지원되지 않으며 기본적으로 VALIDATED 모드로 작동합니다”라고 명시돼 있습니다. (출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18) 이 말은 모델이 스스로 도구 사용 여부를 결정하는 자율성이 줄어든다는 뜻입니다.
💡 조합 기능을 켜면 자동으로 도구를 호출하는 편의성이 제한됩니다. 에이전트 설계 시 이 제약을 먼저 반영해야 흐름이 맞습니다.
실무적으로는 allowed_function_names를 명시적으로 지정해서 VALIDATED 모드를 제어하거나, 복잡한 멀티 에이전트 흐름이라면 구글이 공식 문서에서 권장하는 Interactions API로 이전하는 편이 낫습니다.
thought_signature 오류, 이미 실사용에서 터졌습니다
공식 문서 제목 유형이 아닌 실제 개발자 커뮤니티에서 가장 많이 터진 문제가 이겁니다. Gemini 3 계열에서 도구 호출을 사용할 때 thought_signature가 모든 파트에 포함돼 있어야 합니다. 공식 문서에는 이렇게 나옵니다: “thought_signature는 각 파트에 내장된 실제 암호화된 컨텍스트입니다. thought_signature 없이는 컨텍스트를 재구성할 수 없고, 모든 파트에서 반환하지 않으면 모델이 오류를 냅니다.” (출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
⚠️ 실제 오류 메시지
"Function call is missing a thought_signature in functionCall parts. This is required for tools to work correctly... Additional data, function call `default_api:get_latest_news_summary`, position 2."
(출처: BerriAI/litellm GitHub Issues #16893, LiteLLM v1.80.0 기준)
LiteLLM은 스트리밍 모드에서 thought_signature를 보존하지 못해 400 오류가 났고, n8n의 AI Agent 노드, Flowise에서도 같은 문제가 보고됐습니다. (출처: github.com/FlowiseAI/Flowise/issues/5860, 2026.02.27) — 이미 쓰고 있는 프레임워크가 thought_signature를 처리하는지 먼저 확인해야 합니다.
대응 방법은 단순합니다. 모델 응답에서 받은 파트 전체를, 필드 하나도 빠짐없이 다음 턴 요청에 그대로 넣으면 됩니다. 공식 문서 표현으로는 “모든 파트를 그 안의 모든 필드와 함께 반환해야 컨텍스트가 유지된다”고 나와 있습니다. 직접 따라 하려면 response.candidates[0].content 객체 전체를 history에 넣으면 됩니다.
조합이 안 되는 경우가 따로 있습니다
도구 조합이 정식 출시됐다고 해서 모든 조합이 되는 건 아닙니다. 이 기능이 이번에 정식화된 배경 자체가, 2026년 2월에 파일 검색과 함수 호출을 같이 쓰던 개발자들이 갑자기 막히는 경험을 하고 나서입니다.
당시 구글 개발자 포럼에서 한 개발자는 이렇게 썼습니다: “2월 9일까지 되던 fileSearch + functionDeclarations 조합이 갑자기 ‘Tool use with function calling is unsupported’ 오류를 냅니다. 구현을 바꾼 게 없습니다.” (출처: discuss.ai.google.dev, 2026.02.16) 구글 팀이 이후 이를 해결하고 이번 공식 출시로 이어진 겁니다.
조합 지원 여부 한눈에 보기
| 도구 | 실행 위치 | 도구 조합 지원 |
|---|---|---|
| Google 검색 | 서버 사이드 | ✅ 지원 |
| Google Maps | 서버 사이드 | ✅ 지원 |
| URL 컨텍스트 | 서버 사이드 | ✅ 지원 |
| 파일 검색 | 서버 사이드 | ✅ 지원 |
| 코드 실행 | 서버 사이드 | ✅ 지원 (executableCode 방식) |
| Computer Use | 클라이언트 사이드 | ✅ 지원 (functionCall 방식) |
| 커스텀 함수 | 클라이언트 사이드 | ✅ 지원 (functionCall 방식) |
(출처: ai.google.dev/gemini-api/docs/tool-combination, 2026.03.18)
공식 지원 목록은 모두 됩니다. 다만 시스템 지시문이나 함수 선언 설명에 위치·시간 정보가 들어가 있으면 Google 검색의 실시간 정보와 충돌해서 조합 기능이 제대로 작동하지 않을 수 있다고 문서에 나와 있습니다. 이유는 공식 문서에서 별도로 밝히지 않았습니다.
Interactions API 쪽이 더 낫다고 말하는 이유
💡 도구 조합 문서 하단과 도구 개요 문서를 같이 읽어보면, 구글이 도구 조합을 쓸 때도 generateContent API보다 Interactions API를 권장한다는 것이 보입니다.
구글 공식 도구 개요 문서에는 이렇게 나와 있습니다: “이 기능들은 generateContent API에서도 지원되지만, 서버 사이드 상태 관리와 통합 추론 트레이스를 활용하려면 새로운 Interactions API 사용을 권장한다.” (출처: ai.google.dev/gemini-api/docs/tools, 2026.03.21)
지금 도구 조합을 generateContent로 쓰면 클라이언트가 컨텍스트를 직접 관리해야 합니다. thought_signature 포함 여부, id 매핑, 히스토리 조합을 전부 직접 처리해야 한다는 뜻입니다. Interactions API는 이 컨텍스트 관리를 서버가 맡아줍니다.
아직 Interactions API가 v1beta 상태라 프로덕션 전환을 바로 권하기는 어렵습니다. 다만 새로 에이전트를 설계하는 상황이라면, 지금부터 Interactions API 기준으로 구조를 잡아두는 게 나중에 마이그레이션 비용을 줄입니다.
Q&A
마치며
Gemini API 도구 조합은 확실히 에이전트 개발 흐름을 단순하게 만드는 기능입니다. 오케스트레이션 레이어를 직접 짜야 했던 수고가 줄어드는 건 사실이고, 개발자 요청이 수개월 만에 정식 지원으로 이어진 것도 긍정적입니다.
다만 세 가지는 먼저 확인하고 써야 합니다. 중간 컨텍스트가 전부 토큰에 포함되는 비용 구조, AUTO 모드가 VALIDATED 모드로 강제 전환되는 제약, 그리고 thought_signature를 빠짐없이 반환해야 하는 처리 규칙입니다. 이 세 가지를 모르고 프로덕션에 붙이면 비용이 예상보다 나오거나, 서드파티 프레임워크에서 오류가 납니다.
새 에이전트를 설계할 예정이라면 Interactions API의 진행 상황도 함께 보는 게 좋습니다. 지금은 v1beta지만, 구글이 도구 조합 문서에서 직접 이쪽으로 유도하고 있는 건 방향이 바뀌고 있다는 신호입니다.
본 포스팅 참고 자료
- Combine built-in tools and function calling — Gemini API 공식 문서 (2026.03.18)
- Gemini API tooling updates: context circulation, tool combos — Google Blog (2026.03.17)
- Gemini API 도구 및 에이전트 개요 (2026.03.21 기준)
- Gemini Developer API 가격 책정 (2026.03.22 기준)
- Gemini 개발자 포럼: fileSearch + functionDeclarations 오류 스레드 (2026.02.16)
- LiteLLM GitHub Issues #16893: thought_signature 스트리밍 오류 (2025.11)
본 포스팅은 2026년 3월 23일 기준으로 작성됐습니다. Gemini API 정책, 가격, 기능 범위 및 UI는 구글의 업데이트에 따라 변경될 수 있습니다.
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있으므로 실제 사용 전에 공식 문서를 반드시 확인하세요.
댓글 남기기