Rubric Labs
Gemini API의 interactions API에 함수 선언을 넘기면 모델이 직접 함수를 실행하는 대신 호출할 함수 이름과 인자를 반환해요. 앱이 그 결과를 받아 실행한 뒤 다시 모델에 넘기는 4단계 흐름으로 외부 시스템과 연동할 수 있어요.
← 실무 팁 목록
연동/통합· medium···

Gemini API function calling: interactions API로 외부 함수 연결하기

Gemini API의 interactions API에 함수 선언을 넘기면 모델이 직접 함수를 실행하는 대신 호출할 함수 이름과 인자를 반환해요. 앱이 그 결과를 받아 실행한 뒤 다시 모델에 넘기는 4단계 흐름으로 외부 시스템과 연동할 수 있어요.

Gemini API function calling: interactions API로 외부 함수 연결하기

Gemini API의 function calling은 모델이 외부 함수를 직접 실행하지 않는다. 모델은 어떤 함수를 어떤 인자로 불러야 하는지 판단해 구조화된 응답을 돌려줄 뿐이고, 실제 실행은 앱 코드가 담당한다. 이 구조 덕분에 사내 데이터베이스 조회, 사내 시스템 API 호출, 외부 서비스 연동을 자연어 인터페이스로 감쌀 수 있다.

4단계 흐름

공식 문서는 function calling을 네 단계로 설명한다.

  1. 함수 선언 정의 — 함수 이름, 파라미터 스키마, 설명을 JSON 객체로 작성한다.
  2. 모델 호출 — 사용자 입력과 함수 선언을 함께 interactions.create에 넘긴다.
  3. 함수 실행 — 모델이 반환한 function_call 스텝에서 이름과 인자를 꺼내 앱에서 직접 실행한다.
  4. 결과 반환 — 실행 결과를 function_result 타입으로 다시 모델에 넘겨 최종 응답을 받는다.

함수 선언 작성법

함수 선언은 type, name, description, parameters 네 필드로 구성된다. parameters는 JSON Schema 형식이며 required 배열로 필수 파라미터를 지정한다. 아래는 예시 코드다.

# 예시 코드
import os
from google import genai

client = genai.Client()  # GOOGLE_API_KEY 환경변수를 자동으로 읽는다

schedule_meeting_function = {
    "type": "function",
    "name": "schedule_meeting",
    "description": "Schedules a meeting with specified attendees at a given time and date.",
    "parameters": {
        "type": "object",
        "properties": {
            "attendees": {"type": "array", "items": {"type": "string"}},
            "date": {"type": "string", "description": "Date (e.g., '2024-07-29')"},
            "time": {"type": "string", "description": "Time (e.g., '15:00')"},
            "topic": {"type": "string", "description": "The meeting topic."},
        },
        "required": ["attendees", "date", "time", "topic"],
    },
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about Q3 planning.",
    tools=[{"type": "function", **schedule_meeting_function}],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")

자격증명은 환경변수 GOOGLE_API_KEY로 관리한다. 코드에 키를 직접 쓰지 않는다.

병렬 호출과 순차 호출

독립적인 함수 여러 개를 한 번에 호출해야 할 때는 병렬 function calling을 쓴다. tools 배열에 함수 선언을 여러 개 넣고 generation_config에 tool_choice: "any"를 지정하면 모델이 한 턴에 여러 function_call 스텝을 반환한다.

순서가 중요한 경우, 예를 들어 위치를 먼저 조회한 뒤 그 결과로 날씨를 가져오는 흐름은 compositional function calling으로 처리한다. 모델이 첫 번째 함수 결과를 받은 뒤 두 번째 함수를 호출하는 식으로 자동으로 연쇄한다.

tool_choice로 호출 방식 제어

generation_config의 tool_choice 필드로 모델의 함수 호출 방식을 제어할 수 있다.

  • auto: 모델이 함수 호출 여부를 스스로 판단한다(기본값).
  • any: 항상 함수를 호출하도록 강제한다.
  • none: 함수 호출을 금지한다.
  • validated: 함수 스키마 준수를 보장한다.

특정 함수만 허용하려면 allowed_tools.tools 배열에 함수 이름을 명시한다.

stateless 모드

대화 히스토리를 서버에 저장하지 않으려면 store=false를 지정한다. 이 경우 이전 턴의 user_input 스텝, 모델이 반환한 모든 스텝, function_result 스텝을 다음 요청의 input 배열에 그대로 담아야 한다. 히스토리 관리 책임이 앱 쪽으로 넘어오므로, 멀티턴 대화를 구현할 때 누락 없이 전달하는지 확인해야 한다.

한계

모델은 함수를 직접 실행하지 않는다. 반환된 인자가 실제로 유효한지, 실행 결과가 정확한지는 앱이 검증해야 한다. 함수 선언의 description이 불명확하면 모델이 엉뚱한 함수를 선택하거나 잘못된 인자를 채울 수 있으므로, 설명을 구체적으로 작성하는 것이 중요하다.

참고 출처