Mode 와 Call/Response 포맷

네 가지 function-calling mode

AUTO (default) — 모델이 결정: tool 호출하든가 text 답변.
ANY — 모델이 반드시 함수 하나 이상 호출. text-only 가 invalid 한 workflow 에 유용.
NONE — declared 됐어도 모델이 tool 호출 금지. tool 등록은 했지만 한 turn text-only 원할 때.
VALIDATED — ANY 같은데 strict schema 준수 enforce.

allowed_function_names 로 모델이 이 turn 에 호출 허용된 어느 tool 인지 제한 가능.

Call 포맷 — 모델이 emit 하는 거

모델이 tool 호출 결정하면 response 의 candidates[0].content.parts 가 하나 이상의 function_call part 포함. 각자:

name — 호출할 tool.
args — declared 파라미터 매칭하는 JSON 객체.
id — opaque identifier (Gemini 3+ 에 항상; 2.5 에 가끔 없음).

Response 포맷 — 너가 돌려보내는 거

Tool 실행 후 결과를 다음 user turn 에 function_response part 로 보냄:

name — 원래 호출과 매칭.
response — 결과를 {"result": ...} 로 wrap.
id — 호출의 id 가 있을 때 매칭.

Gemini vs OpenAI role

여기가 OpenAI 외우는 게 너를 다치게 하는 곳: Gemini 의 tool-result role 이 "user", "tool" 아님. 개념적으로 "user 가 tool 의 출력 제공" 말하는 거. Multiple tool result 는 같은 user turn 에 multiple part — 별도 메시지 아님.

Code

Mode 설정 + tool 제한·python

from google.genai import types

config = types.GenerateContentConfig(
    tools=[tools],  # the Tool(function_declarations=[...]) from previous lesson
    tool_config=types.ToolConfig(
        function_calling_config=types.FunctionCallingConfig(
            mode='ANY',
            allowed_function_names=['set_light_values'],  # restrict
        ),
    ),
)

Response 에서 function call 읽기·python

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Make the lights warm and 30%',
    config=config,
)

# Iterate parts — there might be multiple calls
for part in response.candidates[0].content.parts:
    if part.function_call:
        fc = part.function_call
        print(f'Tool: {fc.name}')
        print(f'Args: {dict(fc.args)}')
        print(f'ID: {fc.id}')  # may be None on 2.5

# Or use the convenience
for fc in (response.function_calls or []):
    ...

결과 돌려보내기·python

# Execute YOUR function
result = my_set_light_values(brightness=30, color_temp='warm')
# result might be: {'status': 'ok', 'brightness': 30, 'colorTemperature': 'warm'}

# Build the function-response part
response_part = types.Part.from_function_response(
    name=fc.name,
    response={'result': result},
    id=fc.id,  # match the call's id when present
)

# Append to conversation as a user turn
contents.append(response.candidates[0].content)         # model's call turn
contents.append(types.Content(role='user', parts=[response_part]))  # your result

Gemini vs OpenAI 모양 — 나란히·python

# OpenAI: separate "tool" message per result
# [
#   {role: 'assistant', tool_calls: [{id: 'c1', function: {...}}]},
#   {role: 'tool', tool_call_id: 'c1', content: '{"result": ...}'}
# ]

# Gemini: results go in a USER turn, multiple parts allowed
# [
#   {role: 'model', parts: [{function_call: {name, args, id}}]},
#   {role: 'user',  parts: [{function_response: {name, id, response: {result}}}]},
# ]

Exercise

이전 lesson 의 set_light_values tool 사용. mode=AUTO 와 prompt "What's the weather like?" 로 Flash 호출 — text 답변 관찰. 그 다음 mode=ANY 와 같은 prompt — 무슨 일 (tool 호출 강제, 이상한 args 가능) 관찰. AUTO 의 유연성과 ANY 의 엄격함 갭이 한 실험에 다 들어있음.