도구 호출은 모델이 내 코드에 함수 실행을 요청하게 해 줍니다. tool_choice는 그 호출이 선택인지, 필수인지, 꺼져 있는지를 정합니다.
작동 방식
tools(함수 이름, 설명, JSON Schema 파라미터)를 보내고, 필요하면 tool_choice도 함께 보냅니다.
| OpenAI 값 | 의미 | Anthropic 대응 값 |
|---|---|---|
"auto" |
모델이 메시지나 하나 이상의 호출을 선택. 도구를 보내면 기본값 | {"type": "auto"} |
"required" |
“The model must call one or more tools”(번역: 모델은 도구를 하나 이상 호출해야 함) | {"type": "any"} |
{"type": "function", "function": {"name": "get_weather"}} |
해당 도구 하나를 강제 | {"type": "tool", "name": "get_weather"} |
"none" |
도구 호출 없음. 도구가 없으면 기본값 | {"type": "none"} |
OpenAI의 함수 호출 가이드는 전체 도구 목록은 그대로 두면서 호출을 일부 도구로 제한하는 allowed-tools 옵션도 설명하며, 프롬프트 캐싱을 위해 이 방식을 권합니다.
{"model": "broadnet/glm-5.3",
"messages": [{"role": "user", "content": "Weather in Riyadh?"}],
"tools": [{"type": "function", "function": {"name": "get_weather",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}},
"required": ["city"]}}}],
"tool_choice": {"type": "function", "function": {"name": "get_weather"}}}
Anthropic 문서에 따르면 any나 tool을 쓰면 API가 답변을 미리 채우기(prefill) 때문에 모델은 호출 전에 텍스트를 쓰지 않으며, 일부 Claude 모델은 도구 사용 강제를 거부하고 400 오류를 반환합니다.
왜 중요한가
- 안정적인 파이프라인. 반드시 호출로 끝나야 하는 추출 단계에 수다스러운 텍스트 답변이 와서는 안 됩니다. 호출을 강제하면 그 분기 자체가 사라집니다.
- 안전한 턴. 마지막 요약 턴에
none을 지정하면 같은 도구 목록을 유지하면서도 모델이 도구 호출을 한 번 더 시작하지 못하게 막을 수 있습니다. - 캐싱. Anthropic은
tool_choice를 바꾸면 캐시된 메시지 블록이 무효화된다고 말하므로, 가능하면 턴 사이에 일정하게 유지하세요.
BroadNet Inference에서는
BroadNet의 API 레퍼런스는 GLM 5.3과 Qwen3.8 27B의 도구 호출만 문서화하며, tool_choice는 다루지 않습니다. 사용할 값은 모두 테스트하세요. required나 함수 이름을 보내고 답변에 tool_calls가 들어 있는지 확인하면 됩니다. 강제가 제대로 동작하지 않으면 auto와 명확한 지시를 함께 쓰고 결과를 검증하거나, 같은 모델에서 구조화된 출력을 쓰세요. 오픈 모델 도구 호출 글에 검증 후 재시도하는 루프가 있습니다.
흔한 실수
- 에이전트 루프의 모든 턴에서 도구를 강제해서 최종 답변을 영영 못 내게 만드는 것.
required가 특정 도구를 뜻한다고 가정하는 것. 어떤 도구든 상관없다는 뜻입니다.