도구 호출 (Function Calling)

도구 호출 (Function Calling)

대화만으로는 실시간 날씨나 데이터베이스 조회 같은 작업을 처리할 수 없어요. 이럴 때 모델이 '어떤 함수를 호출할지' 결정하고, 그 함수에서 얻은 결과를 바탕으로 답변을 이어가게 만들면 에이전트의 경계가 확 넓어집니다. 이 글에서는 함수를 정의하는 방법과, 호출 결과를 다시 모델에 돌려주는 흐름을 정리할게요.

출처: 工具调用 (Function Calling) - 智谱开放平台 문서

핵심적인 역할

도구 호출은 모델이 외부 함수나 API를 실행할 수 있게 해주는 기능이에요. 요청에 **tools**로 호출 가능한 함수 목록을, **tool_choice**로 호출 전략을 지정합니다. tool_choice는 기본값이자 유일하게 지원되는 값이 auto라서, 모델이 함수를 호출할지 말지 스스로 판단해요.

응답에서 만나는 핵심 필드는 이러합니다.

  • tool_calls — 모델이 호출하기로 결정한 함수 정보
  • function.name — 호출할 함수 이름
  • function.arguments — 호출 인자 (JSON 형식 문자열)
  • id — 각 도구 호출을 식별하는 고유 ID

흐름 잡기

전체 흐름은 크게 네 단계예요. 먼저 tools로 함수(이름·설명·JSON Schema 파라미터)를 정의하고, 모델에 요청을 보내면, 모델이 tool_calls로 호출할 함수와 인자를 돌려줍니다. 그러면 우리가 실제 함수를 실행하고, 그 결과를 role: "tool" 메시지로 tool_call_id에 맞춰 다시 모델에 전달해 최종 답변을 받는 구조예요.

from zai import ZhipuAiClient

client = ZhipuAiClient(api_key='YOUR_API_KEY')

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "지정 도시의 현재 날씨를 가져옵니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "도시 이름"}
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "서울 날씨는 어때?"}],
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message
print(message.tool_calls)   # model이 호출할 함수와 인자

함수 호출을 실제로 수행할 때는 외부 API나 데이터베이스 조작에 대한 보안 검증과 권한 제어를 꼭 챙겨야 해요. 그리고 함수 정의가 복잡하거나 여러 개라면 temperature·top_p를 낮추거나 샘플링을 끄는 쪽이 성공률을 높여줍니다.

더 알아보기 (Learn more)