BroadRouter
시작하기

도구 호출(tool calling)

업데이트

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

다른 이름: 함수 호출, 툴 호출, 도구 사용, 툴 사용, function calling, tool use, tools, tool_calls

도구 호출은 언어 모델이 바깥세상에 작용하는 방법입니다. 모델이 코드에 무언가를 조회하거나, 쿼리를 실행하거나, 파일을 수정해 달라고 요청한 뒤 그 결과를 활용합니다.

작동 방식

OpenAI 가이드는 앱과 모델 사이의 루프를 이렇게 설명합니다.

  1. 도구를 보냅니다. 요청에 함수 목록을 이름, 설명, 인자용 JSON Schema와 함께 담습니다.
  2. 도구 호출을 받습니다. 모델에 도구가 필요하면 최종 답변 대신 함수 이름과 JSON 인자를 반환합니다.
  3. 실행합니다. 코드가 함수를 실행합니다. OpenAI 가이드는 이 단계를 “the application side”(번역: 애플리케이션 쪽)에 둡니다. 모델이 직접 코드를 실행하는 일은 없습니다.
  4. 결과를 돌려줍니다. 해당 호출 ID와 함께 보냅니다.
  5. 답변을 받습니다. 또는 다른 도구 호출을 받습니다. 필요한 만큼 반복합니다.

Chat Completions 형식에서 도구 정의는 다음과 같습니다.

{
  "type": "function",
  "function": {
    "name": "get_order_status",
    "description": "Look up an order by ID",
    "parameters": {
      "type": "object",
      "properties": { "order_id": { "type": "string" } },
      "required": ["order_id"]
    }
  }
}

이 예시는 주문 ID로 주문을 조회하는 함수 get_order_status를 정의하며, 문자열 인자 order_id를 필수로 받습니다.

응답에는 finish_reason: "tool_calls"와 tool_calls 목록이 들어 있습니다. 각 항목에는 id, 함수 이름, JSON 문자열로 된 arguments가 있습니다. role: "tool", 같은 tool_call_id, 결과를 담은 메시지를 추가한 뒤 API를 다시 호출합니다.

왜 중요한가

  • 에이전트. 코딩 에이전트, 고객 지원 봇, 데이터 어시스턴트는 대부분 도구 호출의 루프입니다.
  • 비용. 왕복할 때마다 새 요청이 생기고, 대화 내용, 도구 정의, 도구 결과가 입력 토큰으로 다시 전송됩니다. 도구 루프가 길수록 캐시된 입력과 도구 순서를 일정하게 유지하는 것이 중요해집니다.
  • 안전. 인자는 모델이 만듭니다. 데이터를 바꾸거나 돈을 쓰는 작업을 실행하기 전에 반드시 검증하세요.

함수는 필요 없고 응답만 스키마에 맞으면 되는 경우에는 구조화된 출력이 더 간단한 도구입니다.

BroadNet Inference에서는

BroadNet 문서는 GLM 5.3과 Qwen3.8 27B에 도구 호출을 표기하며, 두 모델 모두 구조화된 출력과 추론도 지원합니다. DeepSeek V4.1 Flash와 BroadNet Gemma 4 VL 26B에는 도구 지원이 명시되어 있지 않습니다. 배포할 모델에서 직접 도구 루프를 테스트하세요.

표기된 두 모델은 답하기 전에 추론하고, 추론도 max_tokens에 포함되므로 여유를 남기지 않으면 도구 호출이 잘릴 수 있습니다. 추론 토큰을 참고하세요. 자체 도구 형식을 쓰는 에이전트 도구는 Cline 가이드와 Vercel AI SDK 가이드를 참고하세요.

흔한 실수

  • arguments를 객체로 파싱하는 것. JSON 문자열로 오므로 디코딩하고 오류를 처리하세요.
  • tool_call_id를 빠뜨리는 것. 이것이 없으면 모델이 결과와 호출을 짝지을 수 없습니다.

자주 묻는 질문

모델이 제 함수를 실행하나요?

아닙니다. 모델은 함수 이름과 인자만 반환합니다. 실행 여부는 코드가 판단하고, 코드가 실행한 뒤 결과를 tool 메시지로 돌려보냅니다.

모델이 여러 도구를 한 번에 호출할 수 있나요?

많은 API가 병렬 도구 호출을 허용해, 응답 하나의 tool_calls에 여러 항목을 담아 반환합니다. 코드는 각각을 실행하고 tool_call_id마다 결과를 하나씩 돌려줍니다.

BroadNet의 어떤 모델이 도구 호출을 지원하나요?

BroadNet 문서는 GLM 5.3과 Qwen3.8 27B에 도구를 표기합니다. DeepSeek V4.1 Flash와 BroadNet Gemma 4 VL 26B에는 도구 지원이 명시되어 있지 않으므로, 그 모델에서 쓰려면 먼저 테스트하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기