실습문제와 해답

from google.genai import types

from config import MODEL, get_client

client = get_client()

get_order_status_decl = types.FunctionDeclaration(
    name="get_order_status",
    description="하루마켓 주문번호로 주문의 현재 상태(결제/배송준비/배송중/배송완료 등)와 "
                "택배사·송장번호를 조회한다.",
    parameters_json_schema={
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "하루마켓 주문번호. 'HR'로 시작하는 문자열",
            }
        },
        "required": ["order_id"],
    },
)
tool = types.Tool(function_declarations=[get_order_status_decl])

questions = [
    "주문번호 HR20260701023 지금 어디까지 왔나요?",
    "안녕하세요, 반갑습니다.",
    "제 주문 어디까지 왔나요?",
]
for q in questions:
    response = client.models.generate_content(
        model=MODEL,
        contents=q,
        config=types.GenerateContentConfig(
            tools=[tool],
            automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
        ),
    )
    print(f"\n질문: {q}")
    if response.function_calls:
        fc = response.function_calls[0]
        print(f"  도구 호출 요청: {fc.name}({dict(fc.args)})")
    else:
        print(f"  도구 호출 없음. 바로 답변: {response.text.strip()}")

$ python ex05_when_tool.py

실행 결과 (문장은 실행마다 다릅니다)

질문: 주문번호 HR20260701023 지금 어디까지 왔나요?
  도구 호출 요청: get_order_status({'order_id': 'HR20260701023'})

질문: 안녕하세요, 반갑습니다.
  도구 호출 없음. 바로 답변: 안녕하세요! 하루마켓 고객센터입니다. 오늘 어떤 도움이 필요하신가요? 주문 조회, 배송 확인, 상품 문의 등 무엇이든 편하게 말씀해 주세요!

질문: 제 주문 어디까지 왔나요?
  도구 호출 없음. 바로 답변: 주문하신 상품의 배송 상태를 확인하기 위해 **하루마켓 주문번호**(예: `HR`로 시작하는 번호)를 알려주세요!

해설 — 도구를 줬을 때 그것을 부를지는 모델이 질문을 보고 정합니다. 이 교재를 준비하며 세 번 실행했을 때 세 번 모두 같은 결정이었습니다.

• 1번은 주문번호가 있는 조회 질문이어서 도구를 요청했습니다.
• 2번은 도구가 필요 없는 인사여서 바로 답했습니다.
• 3번은 조회 질문이지만 필수 인자인 order_id를 채울 값이 없습니다. 모델은 번호를 지어내 넣지 않고 고객에게 주문번호를 되물었습니다. 선언의 "required": ["order_id"]와 "'HR'로 시작하는 문자열"이라는 설명이 한 일입니다.

한 가지 더 봅니다. 시스템 프롬프트를 주지 않았는데도 2번의 답이 "하루마켓 고객센터입니다"로 시작합니다. 도구 설명에 적힌 "하루마켓"을 읽은 것입니다. 도구 선언이 모델에게 프롬프트로 전달된다는 것을 여기서도 확인할 수 있습니다.

코드에서는 이 세 경우를 if response.function_calls: 한 줄로 갈랐습니다. 도구 요청이 있으면 실행으로, 없으면 답변 출력으로 갑니다.

from google.genai import types

from config import MODEL, get_client

client = get_client()

get_order_status_decl = types.FunctionDeclaration(
    name="get_order_status",
    description="하루마켓 주문번호로 주문의 현재 상태(결제/배송준비/배송중/배송완료 등)와 "
                "택배사·송장번호를 조회한다.",
    parameters_json_schema={
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "하루마켓 주문번호. 'HR'로 시작하는 문자열",
            }
        },
        "required": ["order_id"],
    },
)
# 새로 추가한 두 번째 도구의 선언
check_stock_decl = types.FunctionDeclaration(
    name="check_stock",
    description="하루마켓 상품 이름으로 현재 재고 수량을 조회한다.",
    parameters_json_schema={
        "type": "object",
        "properties": {
            "product_name": {
                "type": "string",
                "description": "상품 이름. 예: '스테인리스 텀블러'",
            }
        },
        "required": ["product_name"],
    },
)
tool = types.Tool(function_declarations=[get_order_status_decl, check_stock_decl])


def get_order_status(order_id: str) -> dict:
    return {"order_id": order_id, "status": "배송중", "courier": "CJ대한통운"}   # 가짜 값


def check_stock(product_name: str) -> dict:
    return {"product_name": product_name, "stock": 12}                        # 가짜 값


# 모델이 요청한 이름으로 실제 함수를 찾는 표
FUNCTIONS = {"get_order_status": get_order_status, "check_stock": check_stock}

for question in ["주문번호 HR20260701023 지금 어디까지 왔나요?",
                 "스테인리스 텀블러 재고 있나요?"]:
    print(f"\n질문: {question}")
    user_content = types.Content(role="user", parts=[types.Part.from_text(text=question)])
    response = client.models.generate_content(
        model=MODEL,
        contents=[user_content],
        config=types.GenerateContentConfig(
            tools=[tool],
            automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
        ),
    )
    fc = response.function_calls[0]
    print(f"  모델의 결정: {fc.name}({dict(fc.args)})")

    result = FUNCTIONS[fc.name](**fc.args)          # 이름으로 함수를 찾아 실행
    print(f"  함수 실행 결과: {result}")

    final = client.models.generate_content(
        model=MODEL,
        contents=[
            user_content,
            response.candidates[0].content,
            types.Content(role="user", parts=[
                types.Part.from_function_response(name=fc.name, response={"result": result})]),
        ],
        config=types.GenerateContentConfig(tools=[tool]),
    )
    print(f"  최종 답변: {final.text.strip()}")

$ python ex05_two_tools.py

실행 결과 (문장은 실행마다 다릅니다)

질문: 주문번호 HR20260701023 지금 어디까지 왔나요?
  모델의 결정: get_order_status({'order_id': 'HR20260701023'})
  함수 실행 결과: {'order_id': 'HR20260701023', 'status': '배송중', 'courier': 'CJ대한통운'}
  최종 답변: 주문번호 **HR20260701023** 상품은 현재 **배송중**입니다. (택배사: CJ대한통운)

질문: 스테인리스 텀블러 재고 있나요?
  모델의 결정: check_stock({'product_name': '스테인리스 텀블러'})
  함수 실행 결과: {'product_name': '스테인리스 텀블러', 'stock': 12}
  최종 답변: 네, '스테인리스 텀블러'는 현재 **12개** 남아있습니다!

해설 — 도구가 둘이 되자 모델의 결정에 "어느 도구인가" 가 더해졌습니다. 주문번호가 있는 질문에는 get_order_status를, 상품 재고를 묻는 질문에는 check_stock을 요청했습니다. 이 교재를 준비하며 세 번 실행했을 때 세 번 모두 같았습니다.

• 고르는 근거는 선언의 이름과 설명입니다. 질문을 도구로 나누는 if 문은 우리 코드에 없습니다.
• 인자도 선언대로 채웠습니다. 둘째 질문에서 문장 속의 "스테인리스 텀블러"를 product_name에 넣었습니다.
• 실행은 여전히 우리 코드가 합니다. FUNCTIONS[fc.name](**fc.args)가 모델이 요청한 이름으로 함수를 찾아 실행하는 줄입니다. 도구가 늘어도 이 한 줄은 그대로입니다.

왕복의 네 단계(선언, 결정, 실행, 반환)는 도구가 하나일 때와 같습니다. 달라진 것은 선언이 두 개라는 점과, 이름으로 함수를 찾는 표 하나입니다. 도구가 더 늘었을 때 모델이 알맞게 고르는지 숫자로 확인하는 방법은 7장에서 다룹니다.

(나)가 더 안전합니다.

(가)에서 환불이 실행되지 않는 것은 모델이 지시를 따르는 동안만입니다. 프롬프트의 금지는 모델에게 하는 부탁이고, Q12처럼 지시를 무시하라는 입력이 들어오면 흔들릴 수 있습니다. 모델이 한 번이라도 refund_order를 요청하고 우리 코드가 그것을 그대로 실행하면 실제로 돈이 나갑니다.

(나)에서는 모델이 무엇을 하려 하든 요청할 도구가 없습니다. 모델이 낼 수 있는 function call은 우리가 준 목록 안의 것뿐입니다. 안전이 모델의 판단이 아니라 구조에 달려 있습니다.

(나)로도 막지 못하는 것. 도구가 없어도 모델은 말은 할 수 있습니다. "전액 환불 처리되었습니다"라는 문장을 쓰는 데는 도구가 필요 없습니다. 실제로 환불은 일어나지 않았지만 고객은 그 말을 믿습니다. 그래서 도구 목록으로 실행을 막는 것과 별개로, 답변 문장에 대한 규칙이 따로 필요합니다. 3장의 시스템 프롬프트가 그 시작이고, 금지할 행동을 프롬프트에 명시하는 방법은 10장에서 다룹니다.

정리하면 이렇습니다.