도구 호출은 언어 모델이 바깥세상에 작용하는 방법입니다. 모델이 코드에 무언가를 조회하거나, 쿼리를 실행하거나, 파일을 수정해 달라고 요청한 뒤 그 결과를 활용합니다.
작동 방식
OpenAI 가이드는 앱과 모델 사이의 루프를 이렇게 설명합니다.
- 도구를 보냅니다. 요청에 함수 목록을 이름, 설명, 인자용 JSON Schema와 함께 담습니다.
- 도구 호출을 받습니다. 모델에 도구가 필요하면 최종 답변 대신 함수 이름과 JSON 인자를 반환합니다.
- 실행합니다. 코드가 함수를 실행합니다. OpenAI 가이드는 이 단계를 “the application side”(번역: 애플리케이션 쪽)에 둡니다. 모델이 직접 코드를 실행하는 일은 없습니다.
- 결과를 돌려줍니다. 해당 호출 ID와 함께 보냅니다.
- 답변을 받습니다. 또는 다른 도구 호출을 받습니다. 필요한 만큼 반복합니다.
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를 빠뜨리는 것. 이것이 없으면 모델이 결과와 호출을 짝지을 수 없습니다.