Function Calling

Classic/VPC 환경에서 이용 가능합니다.

외부 함수나 API를 호출해 동적으로 정보를 가져오거나 작업을 수행할 수 있는 Function calling 기능이 지원되는 v3 Chat Completions에 대해 설명합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

messages

messages에 대한 설명은 다음과 같습니다.

tools

tools에 대한 설명은 다음과 같습니다.

toolCalls

toolCalls에 대한 설명은 다음과 같습니다.

응답

응답 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

toolCalls

toolCalls에 대한 설명은 다음과 같습니다.

동작 방식

요청과 응답을 포함한 Function calling의 동작 방식은 다음과 같습니다.

Step 1. 입력 및 함수 정의 전달

질의 내용을 입력하고 함수 정의를 전달합니다. 요청 예시는 다음과 같습니다.

• cURL

  curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}'
  --header 'Content-Type: application/json' \
  --data '{
    "messages" : [ {
      "content" : "오늘 서울 날씨 알려줘",
      "role" : "user"
    } ],
    "tools" : [ {
      "function" : {
        "description" : "날씨를 알려줄 수 있는 도구",
        "name" : "get_weather",
        "parameters" : {
          "properties" : {
            "location" : {
              "description" : "서울, 대전, 부산 등의 도시 이름",
              "type" : "string"
            },
            "unit" : {
              "enum" : [ "celsius", "fahrenheit" ],
              "type" : "string"
            },
            "date" : {
              "description" : "2023-08-01 같은 형태의 날짜 문자열. 날씨를 알고 싶은 날짜",
              "type" : "string"
            }
          },
          "required" : [ "location" ],
          "type" : "object"
        }
      }
    }],
    "toolChoice" : "auto"
  }'
  

• Python

  import requests
  
  API_KEY = "YOUR_API_KEY"
  REQUEST_ID = "YOUR_REQUEST_ID"
  
  url = "https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}"
  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "X-NCP-CLOVASTUDIO-REQUEST-ID": REQUEST_ID,
      "Content-Type": "application/json"
  }
  
  data = {
      "messages": [
          {
              "content": "내일 서울 날씨 어때?",
              "role": "user"
          }
      ],
      "tools": [
          {
              "type": "function",
              "function": {
                  "description": "날씨를 알려줄 수 있는 도구",
                  "name": "get_weather",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "location": {
                              "description": "서울, 대전, 부산 등의 도시 이름",
                              "type": "string"
                          },
                          "unit": {
                              "type": "string",
                              "enum": ["celsius", "fahrenheit"]
                          },
                          "date": {
                              "description": "2025-03-21 같은 형태의 날짜 문자열. 날씨를 알고 싶은 날짜",
                              "type": "string"
                          }
                      },
                      "required": ["location"]
                  }
              }
          }
      ],
      "toolChoice": "auto"
  }
  
  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(result)
  

Step 2. 호출할 함수 및 인수 반환

호출할 함수와 인수 정보가 반환됩니다. 응답 예시는 다음과 같습니다.

{
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "message": {
            "role": "assistant",
            "content": "",
            "toolCalls": [
                {
                    "id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
                    "type": "function",
                    "function": {
                        "name": "get_weather",
                        "arguments": {
                            "location": "서울",
                            "unit": "celsius",
                            "date": "2025-04-10"
                        }
                    }
                }
            ]
        },
        "finishReason": "tool_calls",
        "created": 1744218663,
        "seed": 1354242582,
        "usage": {
            "promptTokens": 134,
            "completionTokens": 48,
            "totalTokens": 315
        }
    }
}

Step 3. 응답 결과 기반으로 실제 함수 호출

Step 2.의 응답 결과를 기반으로 실제 함수를 호출합니다. 요청 예시는 다음과 같습니다.

• cURL

  # <예시> 다음과 같은 API를 호출한다고 가정합니다.
  # GET https://weather.example.com?location=서울&unit=celsius&date=2025-04-10
  
  curl --request GET 'https://weather.example.com?location=서울&unit=celsius&date=2025-04-10' 
  

• Python

  """
  <예시> 다음과 같은 함수를 구성했다고 가정합니다.
  def get_weather(location, unit="celsius", date=None):
      response = requests.get(f"https://weather.example.com?location={location}&unit={unit}&date={date}")
      data = response.json()
      return data
  """
  
  tool_call = result["result"]["message"]["toolCalls"][0]
  function_name = tool_call["function"]["name"]
  arguments = tool_call["function"]["arguments"]
  
  if function_name == "get_weather":
      function_result = get_weather(**arguments) 
  

응답 예시는 다음과 같습니다.

{ "location": "서울", "temperature": "17도", "condition": "맑음" }

Step 4. 함수 실행 결과 전달

함수 실행 결과를 전달합니다. 요청 예시는 다음과 같습니다.

• cURL

  curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}'
  --header 'Content-Type: application/json' \
    --data '{
      "messages": [
        {
          "role": "user",
          "content": "내일 서울 날씨 어때?"
        },
        {
          "role": "assistant",
          "content": "",
          "toolCalls": [
            {
              "id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
              "type": "function",
              "function": {
                "name": "get_weather",
                "arguments": {
                  "location": "서울",
                  "unit": "celsius",
                  "date": "2025-04-10"
                }
              }
            }
          ]
        },
        {
          "role": "tool",
          "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo",
          "content": "{ \"location\": \"서울\", \"temperature\": \"17도\", \"condition\": \"맑음\" }"
        }
      ],
      "seed": 0,
      "topP": 0.8,
      "topK": 0,
      "maxTokens": 1024,
      "temperature": 0,
      "repeatPenalty": 1.1,
      "stopBefore": []
    }'
  
  

• Python

  url = "https://https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}"
  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "X-NCP-CLOVASTUDIO-REQUEST-ID": REQUEST_ID,
      "Content-Type": "application/json"
  }
  
  data = {
      "messages": [
          {
              "role": "user",
              "content": "내일 서울 날씨 어때?"
          },
          {
              "role": "assistant",
              "content": "",
              "toolCalls": [
                  {
                      "id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
                      "type": "function",
                      "function": {
                          "name": "get_weather",
                          "arguments": {
                              "location": "서울",
                              "unit": "celsius",
                              "date": "2025-04-10"
                          }
                      }
                  }
              ]
          },
          {
              "role": "tool",
              "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo",
              "content": str(function_result)
          }
      ],
      "seed": 0,
      "topP": 0.8,
      "topK": 0,
      "maxTokens": 1024,
      "temperature": 0,
      "repeatPenalty": 1.1,
      "stopBefore": []
  }
  
  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(result)
  

Step 5. 최종 텍스트 응답 반환

최종 반환된 응답 결과의 텍스트를 확인합니다.

{
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "message": {
            "role": "assistant",
            "content": "내일 서울의 날씨는 맑을 예정이며, 기온은 17도로 예상됩니다. 따뜻한 봄날씨가 될 것 같으니 외출하기에 좋은 날이 될 것 같아요!"
        },
        "finishReason": "stop",
        "created": 1744218776,
        "seed": 2744409319,
        "usage": {
            "promptTokens": 88,
            "completionTokens": 37,
            "totalTokens": 125
        }
    }
}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

• 클라이언트 공통 오류 문제(4xx)
• 서버 공통 오류 문제(5xx)