이 기능이 나오기 전, 개발자들이 겪던 문제

Gemini API로 에이전트를 만들 때 가장 불편했던 게 하나 있습니다. Google Search 같은 내장 도구와 내가 직접 만든 커스텀 함수를 같은 요청 안에 넣을 수 없었다는 점입니다. 공식 토론 포럼에는 “왜 OpenAI는 되는데 Gemini는 안 되냐”는 글이 꾸준히 올라왔습니다.

결과적으로 개발자들은 두 가지 방법 중 하나를 택했습니다. 첫 번째는 LangGraph 같은 오케스트레이션 프레임워크를 얹어서 내장 도구와 커스텀 함수를 단계별로 나눠 실행하는 방식. 두 번째는 그냥 내장 도구를 포기하고 커스텀 함수만 쓰는 방식입니다. 둘 다 불필요한 코드가 늘어나고, 단계 사이의 컨텍스트가 단절됩니다.

이 근본 문제를 Google이 2026년 3월 18일 공식 API 업데이트로 해결했습니다. 출처: Gemini API 출시 노트, 2026.03.18

Gemini API 도구 조합이란 정확히 무엇인가

Gemini API 도구 조합(Tool Combination)은 단일 API 요청에서 내장 도구(Google Search, Google Maps, URL Context, File Search, Code Execution)와 개발자가 선언한 커스텀 함수를 함께 실행할 수 있는 기능입니다. 출처: Gemini API 공식 가이드 — Combine built-in tools and function calling, 2026.03.18

핵심 매커니즘은 도구 컨텍스트 순환(Tool Context Circulation)입니다. 내장 도구의 실행 결과를 암호화된 형태로 모델의 컨텍스트에 보존하고, 다음 단계의 커스텀 함수가 그 결과를 참조할 수 있게 합니다. 예를 들어 Google Search로 최신 날씨 데이터를 가져온 뒤, 그 결과를 바탕으로 내 예약 함수가 자동으로 실행되는 흐름이 가능해집니다.

지원 모델은 gemini-3-flash-preview와 gemini-3-pro-preview이며, Gemini 2.5 계열은 지원하지 않습니다.

직접 써보니 이렇게 돌아갑니다 — 흐름 분해

실제 요청 흐름을 공식 가이드의 예시로 분해하면 이렇습니다. 질문은 “미국 최북단 도시가 어딘지 알아보고, 거기 날씨는 어때요?”입니다. Google Search(내장)와 getWeather(커스텀)를 동시에 쓰는 케이스입니다.

Turn 1 — 첫 번째 요청

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를 설정하지 않으면 도구 조합 기능 자체가 동작하지 않습니다. 플래그 하나가 전체 기능의 스위치 역할을 합니다.

API가 돌아오는 응답에는 세 가지 파트가 섞여 있습니다. toolCall + toolResponse(Google Search 실행 결과), functionCall(커스텀 함수 호출 요청), 그리고 암호화된 thoughtSignature입니다. 이 모든 파트를 Turn 2 요청에 그대로 실어서 보내야 합니다.

thought_signature를 빠뜨리면 생기는 일

여기서부터가 핵심입니다. 기존에 Gemini 2.5 계열로 함수 호출 코드를 짜본 분이라면, thought_signature를 반환하지 않아도 그냥 경고 없이 잘 동작했을 겁니다. Gemini 2.5에서는 선택 사항이었기 때문입니다.

Gemini 3 계열은 다릅니다. 공식 문서에 딱 이렇게 나옵니다. “When using Gemini 3 models, you must pass back thought signatures during function calling, otherwise you will get a validation error (4xx status code).” (출처: Thought Signatures 공식 문서, 2026.02.26 기준)

병렬 함수 호출에서는 첫 번째 functionCall 파트에만 thought_signature가 붙습니다. 두 번째 이후 병렬 함수에는 없습니다. 여기서 헷갈려서 “두 번째에도 넣어야 하나?”라는 고민을 하는 경우가 많은데, 넣지 않아도 됩니다.

단, 다음 턴으로 히스토리를 넘길 때는 첫 번째 functionCall과 그 thought_signature를 세트로 묶어서 그대로 돌려보내야 합니다. 응답을 파싱하면서 thought_signature만 빼고 저장하는 실수가 생기면 다음 단계에서 바로 막힙니다.

토큰 요금이 예상보다 늘어나는 이유

이 기능을 쓰면서 토큰 카운트가 기대보다 높게 나와서 당황하는 경우가 있습니다. 이유가 있습니다. 공식 문서에 이렇게 나와 있습니다. “toolCall and toolResponse parts in requests are counted towards prompt_token_count.” (출처: Gemini API Tool Combination 공식 가이드, 2026.03.18)

쉽게 말하면, 내장 도구의 실행 결과(toolCall + toolResponse)가 다음 요청의 입력 토큰으로 잡힌다는 뜻입니다. 다단계 에이전트를 짤수록 누적됩니다.

Google Search 툴은 예외적으로 토큰 이중 청구 없이 쿼리 레벨 요금제를 적용합니다. 단, “하나의 요청이 여러 검색 쿼리를 발생시킬 수 있다”는 점은 공식 문서에도 명시돼 있습니다. 복잡한 질문 하나에 내부적으로 검색이 3~4번 일어날 수 있고, 그 각각에 요금이 붙습니다.

이 기능이 작동하지 않는 조건 정리

솔직히 말하면, “드디어 내장 도구와 커스텀 함수를 같이 쓸 수 있다”는 것만 보고 바로 코드에 적용하면 막히는 경우가 꽤 됩니다. 공식 문서에 Limitations(제한 사항) 항목이 따로 있습니다. 이걸 먼저 보고 시작해야 합니다.

• Gemini 2.5 계열에서는 작동하지 않습니다. 오직 Gemini 3 모델(gemini-3-flash-preview, gemini-3-pro-preview)만 지원합니다.
• include_server_side_tool_invocations=True를 설정하면 AUTO 모드가 비활성화됩니다. 공식 문서에 “Default to VALIDATED mode (AUTO mode is not supported)”로 명시돼 있습니다.
• system_instruction에 날짜·위치 정보가 있으면 충돌할 수 있습니다. Google Search는 현재 시각과 위치를 자동으로 참조하는데, 시스템 지시문에 다른 날짜나 위치를 적으면 도구 조합 기능이 예상대로 동작하지 않을 수 있습니다.
• Computer Use는 이 기능의 영향을 받지 않습니다. Computer Use는 클라이언트 사이드 도구이며, 자체 컨텍스트 순환 방식을 씁니다.
• 기존에 gemini-3-flash-preview로 fileSearch + functionDeclarations를 함께 쓰던 코드는 2026년 2월 17일 이전에 오류를 겪었을 수 있습니다. 당시 공식 포럼에도 “지난주엔 됐는데 갑자기 안 된다”는 글이 올라온 적 있습니다. 지금은 공식 지원이 되었습니다.

주관적으로 보면, 이 기능의 가장 큰 실용적 가치는 “에이전트 파이프라인을 단순화”하는 게 아니라, 기존에 별도 스텝으로 나눠야 했던 것을 단일 컨텍스트 내에서 처리해서 중간 결과의 유실을 막는 겁니다. 에이전트 안정성 문제에 더 직접적으로 기여합니다.

자주 묻는 질문 Q&A

마치며 — 총평

Gemini API 도구 조합은 분명히 개발 생산성을 올려주는 변화입니다. 에이전트 코드에서 “내장 도구 파이프라인 → 컨텍스트 저장 → 커스텀 함수 파이프라인” 구조를 유지하던 분들은 코드를 크게 줄일 수 있습니다.

다만 기대했던 것과 달랐던 부분도 있습니다. “간단해진다”는 느낌보다는 “복잡성의 형태가 달라진다”는 게 더 맞습니다. thought_signature 관리, 파트 타입별 분기 처리, VALIDATED 모드 전환에 따른 함수 선택 로직 재점검이 필요합니다. Gemini 2.5 기반 코드를 그대로 올리면 400 에러를 만납니다.

기존에 내장 도구를 안 쓰고 커스텀 함수만 쓰던 구조라면, 아직 전환할 급한 이유가 없습니다. Google Search 실시간 그라운딩이 필요한 케이스에서 먼저 제한적으로 적용해 보고 확장하는 게 안전합니다.

본 포스팅 참고 자료

1. Google AI for Developers — Combine built-in tools and function calling (Last updated: 2026-03-18) ai.google.dev/gemini-api/docs/tool-combination
2. Google Blog — Gemini API tooling updates: context circulation, tool combos and more (2026.03.17) blog.google/…/gemini-api-tooling-updates/
3. Google AI for Developers — Thought Signatures (Last updated: 2026-02-26) ai.google.dev/gemini-api/docs/thought-signatures
4. Google AI for Developers — Gemini API Pricing (2026.03 기준) ai.google.dev/gemini-api/docs/pricing
5. Google AI for Developers — Release Notes (2026.03.18 업데이트 확인) ai.google.dev/gemini-api/docs/changelog