OpenAI Function Calling 가이드

Function Calling(FC)은 에이전트 구축의 기반입니다: 모델은 절대 함수를 실행하지 않으며, 오직 “어떤 함수를 어떤 인자로 호출할지”만 출력합니다. 실행은 사용자 자신의 코드에서 이루어지며, 사용자는 그 결과를 다시 보내고 모델은 최종 답변을 생성합니다. 이 페이지는 공식 OpenAI 문서(developers.openai.com/api/docs/guides/function-calling, 2026년 6월 기준)를 바탕으로 합니다. 두 엔드포인트의 예시는 그대로 복사해 붙여넣을 수 있습니다.

전체 호출 루프

도구 정의

함수 이름, 설명, 매개변수 JSON Schema를 요청과 함께 보냅니다

모델이 호출을 반환합니다

모델이 호출하기로 결정하면 함수 이름과 JSON 인수를 반환합니다

로컬에서 실행

코드는 인수를 파싱한 뒤 실제로 함수를 실행합니다(DB를 조회하거나 외부 API를 호출하는 등)

결과를 다시 보냅니다

두 번째 요청에서 대화와 함께 결과를 보내면 모델이 이를 바탕으로 응답합니다

두 엔드포인트 간 핵심 형식 차이

같은 기능이지만 /v1/chat/completions와 /v1/responses의 필드 형식이 다릅니다 — 가장 흔한 통합 함정입니다:

	Chat Completions	Responses
도구 정의	중첩형: `{"type": "function", "function": {name, parameters, ...}}`	평면형: `{"type": "function", "name": ..., "parameters": ...}`
호출 출력	`message.tool_calls[]` (`id` 포함)	최상위 출력 항목: `{"type": "function_call", "call_id", "name", "arguments"}`
결과 반환	`{"role": "tool", "tool_call_id": ..., "content": ...}`	`{"type": "function_call_output", "call_id": ..., "output": ...}`
엄격 모드	`"strict": true`를 명시적으로 설정	서버는 가능한 경우 스키마를 strict로 정규화합니다

두 형식은 섞어 사용할 수 없습니다. Chat Completions의 중첩된 function: {...} 정의를 /v1/responses로 보내는 것(또는 그 반대)이 SDK의 “invalid parameter” 오류를 일으키는 가장 흔한 원인입니다.

Full Example: Chat Completions

완전한 define → call → execute → return 루프를 통한 날씨 조회 예시입니다:

import json
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. Beijing"}
            },
            "required": ["city"],
            "additionalProperties": False
        },
        "strict": True
    }
}]

messages = [{"role": "user", "content": "What's the weather in Beijing?"}]

# 1st request: the model decides to call the function
r1 = client.chat.completions.create(
    model="gpt-5.4", messages=messages, tools=tools
)
tool_call = r1.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)

# Execute locally (fake data standing in for a real lookup)
weather = {"city": args["city"], "temp": "26°C", "condition": "sunny"}

# 2nd request: return the result; the model writes the final answer
messages.append(r1.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(weather)
})

r2 = client.chat.completions.create(
    model="gpt-5.4", messages=messages, tools=tools
)
print(r2.choices[0].message.content)

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.apiyi.com/v1'
});

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get current weather for a city',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'City name, e.g. Beijing' }
      },
      required: ['city'],
      additionalProperties: false
    },
    strict: true
  }
}];

const messages = [{ role: 'user', content: "What's the weather in Beijing?" }];

const r1 = await openai.chat.completions.create({
  model: 'gpt-5.4', messages, tools
});
const toolCall = r1.choices[0].message.tool_calls[0];
const args = JSON.parse(toolCall.function.arguments);

const weather = { city: args.city, temp: '26°C', condition: 'sunny' };

messages.push(r1.choices[0].message);
messages.push({
  role: 'tool',
  tool_call_id: toolCall.id,
  content: JSON.stringify(weather)
});

const r2 = await openai.chat.completions.create({
  model: 'gpt-5.4', messages, tools
});
console.log(r2.choices[0].message.content);

curl https://api.apiyi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "What is the weather in Beijing?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"],
          "additionalProperties": false
        },
        "strict": true
      }
    }]
  }'

전체 예시: 응답

세 가지 차이점에 주목하십시오: 도구 정의는 평면 구조이며, 호출은 최상위 function_call 항목으로 돌아오고, 결과는 function_call_output로 반환됩니다. previous_response_id를 사용하면 두 번째 요청에서 전체 기록을 다시 보낼 필요가 없습니다:

import json
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

tools = [{
    "type": "function",          # flat definition — no nested "function" field
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name, e.g. Beijing"}
        },
        "required": ["city"],
        "additionalProperties": False
    }
}]

# 1st request
r1 = client.responses.create(
    model="gpt-5.4",
    input="What's the weather in Beijing?",
    tools=tools
)

# Find the function_call item in the output array
call = next(item for item in r1.output if item.type == "function_call")
args = json.loads(call.arguments)

weather = {"city": args["city"], "temp": "26°C", "condition": "sunny"}

# 2nd request: chain with previous_response_id, return only the function result
r2 = client.responses.create(
    model="gpt-5.4",
    previous_response_id=r1.id,
    input=[{
        "type": "function_call_output",
        "call_id": call.call_id,
        "output": json.dumps(weather)
    }],
    tools=tools
)
print(r2.output_text)

strict 모드 (구조화된 출력)

strict: true는 모델의 인수가 JSON Schema를 정확히 준수하도록 보장합니다 — 환각된 필드나 누락된 필드는 없습니다. 세 가지 요구사항이 있습니다:

스키마에는 "additionalProperties": false가 포함되어야 합니다
모든 필드는 required에 나타나야 합니다(옵셔널성은 "type": ["string", "null"]로 표현합니다)
지원되는 JSON Schema 하위 집합만 사용할 수 있습니다(원시 타입, enum, 배열, 중첩 객체, …)

// ✅ Valid strict schema
{
  "type": "object",
  "properties": {
    "city": {"type": "string"},
    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
    "date": {"type": ["string", "null"], "description": "Optional, defaults to today"}
  },
  "required": ["city", "unit", "date"],
  "additionalProperties": false
}

// ❌ Invalid: missing additionalProperties, date not in required
{
  "type": "object",
  "properties": {
    "city": {"type": "string"},
    "date": {"type": "string"}
  },
  "required": ["city"]
}

strict mode는 parallel function calls와 호환되지 않습니다: strict 스키마 보장이 필요할 때는 parallel_tool_calls: false도 설정합니다.

parallel_tool_calls and tool_choice

병렬 호출

parallel_tool_calls은 기본값으로 켜져 있습니다: 모델은 한 번의 턴에서 여러 함수를 요청할 수 있습니다(예: 베이징과 상하이의 날씨를 동시에 요청). 각 함수를 실행한 뒤, 다음 요청 전에 모든 결과를 반환해야 합니다 — 각 결과는 반드시 해당 call_id(응답) 또는 tool_call_id(채팅)과 짝을 이루어야 합니다.

tool_choice 전략

값	동작
`"auto"` (기본값)	모델이 무엇을 호출할지와 호출 여부를 결정합니다
`"required"`	최소 하나의 함수를 호출해야 합니다
`{"type": "function", "name": "get_weather"}`	특정 함수를 강제로 호출합니다
`"none"`	호출 없음 — 텍스트만 사용합니다

allowed_tools 하위 집합

이번 턴에 도구는 많지만 그중 일부만 노출하고 싶다면, allowed_tools 형식의 tool_choice를 사용하여 호출 가능한 하위 집합을 제한하십시오 — 이렇게 해도 도구 목록 자체는 수정되지 않으므로, 캐싱을 위한 안정적인 접두사가 깨지지 않습니다:

tool_choice={
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [{"type": "function", "name": "get_weather"}]
}

스트리밍에서 함수 호출

Chat Completions: 인덱스로 조립

함수 인자는 조각 형태로 스트리밍됩니다. arguments 문자열을 index별로 누적한 다음, 스트림이 끝난 뒤 json.loads합니다:

stream = client.chat.completions.create(
    model="gpt-5.4", messages=messages, tools=tools, stream=True
)

calls = {}  # index -> {name, arguments}
for chunk in stream:
    delta = chunk.choices[0].delta if chunk.choices else None
    if delta and delta.tool_calls:
        for tc in delta.tool_calls:
            entry = calls.setdefault(tc.index, {"name": "", "arguments": ""})
            if tc.function.name:
                entry["name"] = tc.function.name
            if tc.function.arguments:
                entry["arguments"] += tc.function.arguments

print(calls)  # arguments are complete JSON only after the stream ends

Responses: 의미 기반 이벤트를 수신

response.function_call_arguments.delta 이벤트는 인자 증분을 전달하며, response.function_call_arguments.done는 완전한 인자를 제공합니다 — 인덱스를 수동으로 조립할 필요가 없습니다.

모범 사례와 함정

좋은 도구 정의를 작성하는 방법입니다:

이름과 설명은 모델을 위해 작성합니다: “언제 호출해야 하는지”를 명확히 적으십시오. 예: "Get real-time weather; call only when the user explicitly asks about weather"
enum으로 매개변수를 좁히십시오: 값이 열거 가능하면 자유 형식 문자열을 사용하지 마십시오. 대부분의 환각된 인수를 제거합니다.
도구 정의는 프롬프트 앞부분에 두고 안정적으로 유지하십시오: 도구는 캐시 접두사에 참여합니다. 정의가 안정적이면 입력 비용이 90% 절감됩니다(Cache Billing 참조)
에이전트 루프에 상한을 두십시오: 최대 라운드 수를 설정하여 모델이 호출 → 반환 → 호출을 반복하면서 비용을 소모하지 못하게 하십시오

흔한 함정입니다:

증상	해결 방법
`arguments`가 유효한 JSON이 아닙니다	`strict: true`을 켜십시오 — 근본적으로 해결합니다
모델이 존재하지 않는 함수를 호출합니다	`tool_choice`로 더 엄격하게 제한하고, 설명이 오해를 유발하는지 확인하십시오
병렬 호출 후 `call_id` 불일치	각 결과는 해당 `call_id` / `tool_call_id`와 일대일로 짝지어져야 합니다 — 하나라도 짝이 없으면 요청이 실패합니다
혼합 형식으로 인한 매개변수 오류	위의 차이 표를 확인하고, 정의 형태(중첩/평면)를 엔드포인트에 맞추십시오

모델 지원 및 선택

전체 gpt-5 시리즈는 함수 호출을 지원합니다. 시나리오별로 보면 다음과 같습니다.

시나리오	권장 모델	이유
일상적인 에이전트 / 도구 사용	`gpt-5.4` ($2.50 / $15.00 per 1M)	기능과 비용의 균형이 가장 좋습니다
고빈도 경량 라우팅	`gpt-5.4-mini` ($0.75 / $4.50 per 1M)	저렴하며 단순 분배에 충분합니다
복잡한 다단계 추론 에이전트	`gpt-5.5` ($5.00 / $30.00 per 1M)	긴 계획 체인에서 더 안정적입니다

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

OpenAI Function Calling 가이드

전체 호출 루프

두 엔드포인트 간 핵심 형식 차이

Full Example: Chat Completions

전체 예시: 응답

strict 모드 (구조화된 출력)

parallel_tool_calls and tool_choice

병렬 호출

tool_choice 전략

allowed_tools 하위 집합

스트리밍에서 함수 호출

Chat Completions: 인덱스로 조립

Responses: 의미 기반 이벤트를 수신

모범 사례와 함정

모델 지원 및 선택

관련 링크

​전체 호출 루프

​두 엔드포인트 간 핵심 형식 차이

​Full Example: Chat Completions

​전체 예시: 응답

​strict 모드 (구조화된 출력)

​parallel_tool_calls and tool_choice

​병렬 호출

​tool_choice 전략

​allowed_tools 하위 집합

​스트리밍에서 함수 호출

​Chat Completions: 인덱스로 조립

​Responses: 의미 기반 이벤트를 수신

​모범 사례와 함정

​모델 지원 및 선택

​관련 링크

전체 호출 루프

두 엔드포인트 간 핵심 형식 차이

Full Example: Chat Completions

전체 예시: 응답

strict 모드 (구조화된 출력)

parallel_tool_calls and tool_choice

병렬 호출

tool_choice 전략

allowed_tools 하위 집합

스트리밍에서 함수 호출

Chat Completions: 인덱스로 조립

Responses: 의미 기반 이벤트를 수신

모범 사례와 함정

모델 지원 및 선택

관련 링크