도구 호출 (Tool Calling / 함수 호출)

에이전트를 만들다 보면 모델이 단순히 답변만 하는 게 아니라 실제로 API를 호출하거나 실시간 데이터를 가져와야 하는 순간이 오죠. 그때 쓰는 게 바로 도구 호출(tool calling), 함수 호출(function calling)이라고도 불리는 기능이에요. Fireworks는 OpenAI 호환 도구 명세를 지원해서, 도구를 JSON Schema로 정의해 두면 모델이 사용자 입력에 맞는 도구를 스스로 골라 호출해요.

출처: https://docs.fireworks.ai/guides/function-calling

동작 방식

도구 호출은 네 단계로 흘러가요. ① JSON Schema 형식으로 도구를 정의하고, ② 모델이 질의를 분석해 도구를 호출할지 결정하고, ③ 필요하면 구조화된 도구 호출을 반환하고, ④ 우리가 도구를 실행해 결과를 다시 보내 최종 응답을 받는 식이에요.

도구 정의

도구는 JSON Schema 형식으로 정의해요. 각 도구에는 식별자인 name, 함수가 무엇을 하는지 설명하는 description, 파라미터를 담는 parameters가 필요해요. 모델이 적절한 도구와 인자를 고르는 데 이 설명을 의존하므로, 설명은 자세하고 명확하게 쓰는 게 좋아요.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="accounts/fireworks/models/kimi-k2-instruct-0905",
    messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
    tools=tools,
    temperature=0.1
)
print(response.choices[0].message.tool_calls)

도구 호출 품질을 올리려면 낮은 온도(0.0~0.3)를 쓰는 게 좋아요. 그러면 환각으로 생긴 파라미터 값이 줄고 더 결정적인 도구 선택이 나와요.

JSON Schema의 파라미터 타입은 string, number, integer, object, array, boolean, null을 지원해요. 여기에 enum으로 값을 제한하거나, 파라미터를 required로 표시하거나, $defs/definitions와 $ref로 하위 스키마를 재사용할 수 있어요. 순환 참조(연결 리스트, 트리, 상호 재귀 타입)도 포함해서요.

도구 선택 제어 (tool_choice)

tool_choice 파라미터로 모델이 도구를 어떻게 쓸지 정할 수 있어요.

auto (기본): 모델이 도구를 호출할지 직접 답할지 스스로 결정
none: 어떤 도구도 호출하지 않음
required: 최소 하나의 도구를 반드시 호출
특정 함수 지정: 특정 함수만 호출하도록 강제

# 특정 도구 강제 호출
response = client.chat.completions.create(
    model="accounts/fireworks/models/kimi-k2-instruct-0905",
    messages=[{"role": "user", "content": "What's the weather?"}],
    tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
    temperature=0.1
)

일부 모델은 한 번에 여러 도구를 호출하는 병렬 도구 호출을 지원해요. 이 기능에 기대기 전에 해당 모델이 지원하는지 먼저 확인해 보세요.

스트리밍과 도구 호출

도구 호출은 스트리밍 응답에서도 동작해요. 인자가 모델이 생성하는 대로 조각조각 전달되기 때문에, 스트리밍 청크의 delta.tool_calls를 누적해서 완성된 인자로 조립해야 해요.

문제 해결 팁

도구 설명이 명확하고 상세한지 확인하고, 사용자 질의가 도구를 필요로 한다는 걸 분명히 하세요.
tool_choice="required"를 쓰면 도구 사용을 강제할 수 있어요.
모델이 도구 호출을 지원하는지 supportsTools 필드로 확인해 보세요.
도구 호출 인자를 파싱하기 전에 항상 검증하고, 프로덕션에서는 부분적·비정상 JSON을 우아하게 처리하는 try-catch 같은 보호 장치를 두세요.
parameters(또는 response_format)가 해결할 수 없는 $ref를 만나면 400 에러가 나요. 외부 URI $ref는 지원되지 않고, 문서 내부 JSON Pointer(#/...)만 가능해요. 그런 경우 참조할 하위 스키마를 문서 안에 인라인하거나 $defs로 끌어올려야 해요.

더 알아보기

구조화 출력: 일관된 JSON 스키마 강제
텍스트 모델: 채팅 완성과 기타 API 알아보기
배포: 전용 GPU에 모델 배포
API 레퍼런스: 채팅 완성 API 전체 문서