Function calling

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

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

요청

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

메서드	URI
POST	/v3/chat-completions/{modelName}

참고

HyperCLOVA X Function calling은 Chat Completions v3, 오픈AI 호환 API에서만 사용할 수 있으며, 튜닝 모델의 경우에는 지원하지 않습니다.

요청 헤더

CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA Studio 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

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

필드	타입	필수 여부	설명
`modelName`	Enum	Required	모델 이름 <예시> `HCX-005`

요청 바디

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

필드	타입	필수 여부	설명
`messages`	Array	Required	대화 메시지: messages
`topP`	Double	Optional	생성 토큰 후보군을 누적 확률을 기반으로 샘플링 0.00 ＜ `topP` ≤ 1.00 (기본값: 0.8) 최종 텍스트 응답 반환 시에만 적용 (대화 메시지의 `role`이 `tool`인 경우)
`topK`	Integer	Optional	생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 0 ≤ `topK` ≤ 128 (기본값: 0) 최종 텍스트 응답 반환 시에만 적용 (대화 메시지의 `role`이 `tool`인 경우)
`maxTokens`	Integer	Optional	최대 생성 토큰 수 1024≤ `maxTokens` ≤ 모델 최대값 `maxCompletionTokens`와 동시 사용 불가
`maxCompletionTokens`	Integer	Optional	최대 생성 토큰 수 (추론 모델) 1024≤ `maxCompletionTokens` ≤ 모델 최대값 `maxTokens`와 동시 사용 불가
`temperature`	Double	Optional	생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) 0.00 ≤ `temperature` ≤ 1.00 (기본값: 0.5) 최종 텍스트 응답 반환 시에만 적용 (대화 메시지의 `role`이 `tool`인 경우)
`repetitionPenalty`	Double	Optional	같은 토큰을 생성하는 것에 대한 패널티 정도 0.0 ＜ `repetitionPenalty` ≤ 2.0 (기본값: 1.1) 설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소 1.0~1.1에서 0.05 단위로 미세 조정 권장 최종 텍스트 응답 반환 시에만 적용 (대화 메시지의 `role`이 `tool`인 경우)
`stop`	Array	Optional	토큰 생성 중단 문자 [](기본값) 최종 텍스트 응답 반환 시에만 적용 (대화 메시지의 `role`이 `tool`인 경우)
`thinking`	Object	Optional	추론 모델 설정 정보
`thinking.effort`	String	Optional	추론 여부 및 사고 과정 깊이 설정 `none` (유효 값) Function calling과 동시 사용 불가
`tools`	Array	Optional	`Function calling` 사용 가능 도구 목록: tools
`toolChoice`	String \| Object	Optional	`Function calling` 도구 호출 동작 방식 `auto` : 모델이 도구 자동 호출 (String) `none` : 모델이 도구 호출 없이 일반 답변 생성 (String) 모델이 특정 도구 강제 호출 (Object)
`toolChoice.type`	String	Optional	`Function calling` 모델이 호출할 도구 유형
`toolChoice.function`	Object	Optional	`Function calling` 모델이 호출할 도구 `function` (유효 값)
`toolChoice.function.name`	String	Optional	`Function calling` 모델이 호출할 도구 이름

`messages`

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

필드	타입	필수 여부	설명
`role`	Enum	Required	대화 메시지 역할 `system` \| `user` \| `assistant` \| `tool` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 사용자의 발화 또는 질문에 대한 답변 `tool`: assistant(모델)가 호출한 함수의 실행 결과
`content`	String	Required	대화 메시지 내용 텍스트 입력(String)
`toolCalls`	Array	Conditional	assistant의 호출 도구 정보 `role`이 `tool`인 경우, assistant의 toolCalls 요청과 같이 입력
`toolCallId`	String	Conditional	도구 아이디 `role`이 `tool`인 경우, 필수 입력 assistant의 toolCalls 요청과 연결하는 용도

`tools`

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

필드	타입	필수 여부	설명
`type`	String	Required	도구 유형 `function`(유효 값)
`function`	Object	Required	호출 `function` 정보
`function.name`	String	Required	`function` 이름
`function.description`	String	Required	`function` 설명
`function.parameters`	Object	Optional	`function` 사용 시 전달되는 매개변수 `properties`, `required` 입력: 동작 방식 참조 형식: JSON Schema reference 참조

`toolCalls`

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

필드	타입	필수 여부	설명
`id`	String	-	도구 식별자
`type`	String	-	도구 유형 `function`(유효 값)
`function`	Object	-	호출 `function` 정보
`function.name`	String	-	`function` 이름
`function.arguments`	Object	-	`function` 사용 시 전달되는 매개변수

참고

일부 필드 입력 시 다음 내용을 확인해 주십시오.

role: system인 대화 메시지는 요청당 1개만 포함할 수 있습니다.
Fuction calling은 추론 또는 이미지 해석과 동시에 요청할 수 없습니다.
Function calling은 결괏값 생성 시 사용하는 최대 토큰 수(maxTokens 또는 maxCompletionTokens)를 1024 이상으로 설정해 주십시오.

응답

응답 형식을 설명합니다.

응답 헤더

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

헤더	필수 여부	설명
`Content-Type`	-	응답 데이터의 형식 `application/json`

응답 바디

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태 참조
`result`	Object	-	응답 결과
`result.created`	Integer	-	응답 날짜 Unix timestamp miliseconds 형식
`result.usage`	Object	-	토큰 사용량
`result.usage.completionTokens`	Integer	-	생성 토큰 수
`result.usage.promptTokens`	Integer	-	입력(프롬프트) 토큰 수
`result.usage.totalTokens`	Integer	-	전체 토큰 수 생성 토큰 수+입력 토큰 수
`result.message`	Object	-	대화 메시지
`result.message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`result.message.content`	String	-	대화 메시지 내용
`result.message.toolCalls`	Array	-	toolCalls
`result.finishReason`	String	-	토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) `length` \| `stop`\| `tool_calls` `length`: 길이 제한 `stop`: 답변 생성 중 `stop`에 지정한 문자 출현 `tool_calls`: 모델이 정상적으로 도구 호출 완료
`result.seed`	Integer	-	입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)

`toolCalls`

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

필드	타입	필수 여부	설명
`id`	String	-	도구 식별자
`type`	String	-	도구 유형 `function`(유효 값)
`function`	Object	-	호출 `function` 정보
`function.name`	String	-	`function` 이름
`function.arguments`	Object	-	`function` 사용 시 전달되는 매개변수

응답 스트림

생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.

응답 헤더

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

헤더	필수 여부	설명
`Accept`	-	응답 데이터의 형식 `text/event-stream`

응답 바디

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

StreamingChatCompletionsTokenEvent

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

필드	타입	필수 여부	설명
`created`	Integer	-	응답 시간 타임스탬프
`usage`	Object	-	토큰 사용량
`usage.promptTokens`	Integer	-	입력(프롬프트) 토큰 수
`usage.completionTokens`	Integer	-	생성 토큰 수
`message`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `user` \| `assistant` `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`message.toolCalls`	Array	-	toolCalls
`finishReason`	String	-	토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) `length` \| `stop` `length`: 길이 제한 `stop`: 답변 생성 중 `stop`에 지정한 문자 출현

`toolCalls`

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

필드	타입	필수 여부	설명
`id`	String	-	도구 식별자
`type`	String	-	도구 유형 `function`(유효값)
`function`	Object	-	호출 `function` 정보
`function.name`	String	-	`function` 이름
`function.partialJson`	String	-	`function` 에 전달할 JSON 인자를 구성하는 문자열의 일부

StreamingChatCompletionsResultEvent

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

필드	타입	필수 여부	설명
`created`	Integer	-	응답 시간 타임스탬프
`usage`	Object	-	토큰 사용량
`usage.promptTokens`	Integer	-	입력(프롬프트) 토큰 수
`usage.completionTokens`	Integer	-	생성 토큰 수
`usage.totalTokens`	Integer	-	전체 토큰 수 생성 토큰 수+입력 토큰 수
`message`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `user` \| `assistant` `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`message.toolCalls`	Array	-	toolCalls
`finishReason`	String	-	토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) `length` \| `stop` `length`: 길이 제한 `stop`: 답변 생성 중 `stop`에 지정한 문자 출현 `tool_calls`: 모델이 정상적으로 도구 호출 완료

ErrorEvent

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태 참조
`status.code`	Object	-	응답 상태 코드 CLOVA Studio 문제 해결 참조
`status.message`	Object	-	응답 상태 메시지 CLOVA Studio 문제 해결 참조

SignalEvent

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

필드	타입	필수 여부	설명
`data`	String	-	전달할 시그널 데이터 정보

응답 예시

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

성공

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

id:ef40438b-d49a-4fff-9335-a19e5abfcff1
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"id":"call_zumbHGLfLwV3xn0Rn2gSPqfz","type":"function","function":{"name":"get_weather"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

id:75cae060-e19b-4a82-9106-81b784dcde51
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"{\""}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

id:d29c7e43-d8ed-43f1-8265-6e5fa91b4b65
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"location"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

id:700f5c00-07b3-4bcc-892d-00913d22ad9f
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"\":"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

id:0c3e3439-699d-400a-af23-29a09eab28f3
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":" \""}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

id:b7506691-ffb0-4e23-a068-ce50013920de
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"서울"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

id:7c26e5c8-d75e-4e33-8185-1877c9c2c8d7
event:token
data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"\","}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null}

...

id:f32289bd-0b94-4733-9df2-9f1a3eee48a6
event:result
data:{"message":{"role":"assistant","content":"","toolCalls":[{"id":"call_zumbHGLfLwV3xn0Rn2gSPqfz","type":"function","function":{"name":"get_weather","arguments":{"location":"서울","unit":"celsius","date":"2025-06-13"}}}]},"finishReason":"tool_calls","created":1749810707,"seed":1775609431,"usage":{"promptTokens":9,"completionTokens":47,"totalTokens":56}}

실패

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

동작 방식

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

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

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

cURL

curl --location --request POST 'https://clovastudio.stream.ntruss.com/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.ntruss.com/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.ntruss.com/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://clovastudio.stream.ntruss.com/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
        }
    }
}