자동 호출과 특수 도구

자동 함수 호출 — Python에서만

Python SDK는 전체 도구 호출 반복을 자동으로 실행할 수 있어. tools=[...]에 일반 callable을 전달하면 SDK가 형식 힌트와 docstring을 살펴 선언을 만들고 호출·응답 반복을 내부에서 처리해. Python에서만 가능해. TypeScript에서는 직접 반복을 만들어야 해.

모델에 바로 줄 수 있는 내장 도구 두 가지

Google이 자기 인프라에서 실행해 주는 도구가 두 개 있어:

코드 실행(ToolCodeExecution) — 모델이 Python을 작성하면 Google이 서버에서 실행하고 출력을 돌려줘. 수학, 파싱, 그래프 작성에 유용해.
Google Search(GoogleSearch) — 모델이 검색을 수행하고 결과를 읽어. 최신 사건을 근거에 연결할 때 써.

Google 인프라 안에서 실행되므로 디스패처를 따로 작성할 필요가 없어.

도구 조합하기

같은 호출에 사용자 정의 함수 선언과 내장 도구를 함께 넣을 수 있어. 모델이 사용자의 의도에 맞는 도구를 골라.

Code

자동 호출 — SDK가 반복 처리·python

from google import genai
from google.genai import types

client = genai.Client()

def set_light_values(brightness: int, color_temp: str) -> dict:
    """Sets brightness (0-100) and color_temp (daylight/cool/warm)."""
    return {'brightness': brightness, 'colorTemperature': color_temp}

def get_weather(location: str) -> dict:
    """Get current weather for a location."""
    return {'location': location, 'temp_c': 22, 'conditions': 'clear'}

# SDK introspects type hints + docstring, runs the entire tool loop.
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Set the lights warm and 30%, then tell me the weather in Seoul.',
    config=types.GenerateContentConfig(
        tools=[set_light_values, get_weather],
    ),
)
print(response.text)
# Both tools were called by the SDK; you got the final natural-language reply.

# Disable auto-calling and go back to manual loop:
config = types.GenerateContentConfig(
    tools=[set_light_values],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
)

코드 실행·python

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What is the sum of the first 50 prime numbers?',
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution())],
    ),
)
print(response.text)
# The model wrote and ran Python server-side, then explained the answer.

Google Search 그라운딩·python

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Who won the 2024 European Championship in football, and what was the final score?',
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)
print(response.text)
# Grounded answer with citations available in response.candidates[0].grounding_metadata.

사용자 정의 도구와 내장 도구 섞기·python

config = types.GenerateContentConfig(
    tools=[
        set_light_values,                                           # custom
        get_weather,                                                # custom
        types.Tool(code_execution=types.ToolCodeExecution()),       # built-in
        types.Tool(google_search=types.GoogleSearch()),             # built-in
    ],
)
# The model picks whichever tool fits each step of the conversation.

Exercise

2줄짜리 프로그램으로 get_weather(location)와 convert_celsius_to_fahrenheit(c) 두 함수를 작성해. 자동 호출을 켜고 둘 다 generate_content에 전달한 뒤 "서울 날씨 어때? 온도는 화씨로 바꿔 줘."라고 물어. SDK가 도구 호출을 자동으로 이어 붙였는지 확인해. 그다음 자동 호출을 끄고 앞 레슨의 반복으로 같은 일을 직접 처리해 차이를 느껴 봐.