Source: https://aiprimetech.io/ko/docs/api-reference/tool-use/

[홈](/ko/) / [문서](/ko/docs/) / 도구 사용 및 함수 호출 

# 도구 사용 및 함수 호출 

모델이 함수를 호출하도록 설정하세요 — 요청 루프, 두 가지 형식, 토큰을 낭비하는 실수. 

 페이지 복사 [ Markdown으로 보기](/ko/docs/api-reference/tool-use.md) [ ChatGPT에 질문](https://chatgpt.com/?q=Read%20https%3A//aiprimetech.io/docs/api-reference/tool-use.md%20and%20answer%20questions%20about%20it.%20Start%20with%20a%20short%20summary.) [ Claude에서 질문](https://claude.ai/new?q=Read%20https%3A//aiprimetech.io/docs/api-reference/tool-use.md%20and%20answer%20questions%20about%20it.%20Start%20with%20a%20short%20summary.)   

도구 사용을 통해 모델은 사용자에게 함수 실행을 요청한 뒤 그 결과를 바탕으로 계속 진행할 수 있습니다. 모든 코딩 에이전트는 이 메커니즘을 기반으로 작동합니다. 

## 반복 흐름 
- 다음을 보냅니다: messages 그리고 tools 사용 가능한 도구를 설명하는 내용을 함께 보냅니다.
- 모델은 다음으로 응답합니다: stop_reason: tool_use 및 tool_use 도구 이름과 인수를 지정하는 블록입니다.
- 사용자가 이를 실행합니다. 게이트웨이는 사용자 코드를 실행하지 않습니다.
- 전체 기록과 함께 다음을 다시 보냅니다: tool_result 블록입니다.
- 모델은 최종 답변을 생성하거나 다른 도구를 요청합니다. 

## 도구 정의(Messages 형식) 

```
Copy{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city. Use when the user asks about weather.",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string", "description": "City name"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Paris?"}]
}
```

## 결과 반환 

```
Copy{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC...",
    "content": "18C, light rain"
  }]
}
```

tool_result 역할이 다음과 같은 메시지에 들어갑니다: user및 tool_use_id 모델 요청의 id와 정확히 일치해야 합니다. id가 일치하지 않으면 잘못된 요청으로 거부됩니다. 

## OpenAI 형식 

이 /v1/chat/completions 엔드포인트는 OpenAI의 tools / tool_calls 형식을 대신 사용하며, 결과는 다음 역할의 메시지로 반환됩니다: tool. 

## 도구 사용 비용 
- 정의는 매 턴마다 다시 전송됩니다. 장황한 도구 스키마 스무 개만으로도 대화가 시작되기 전에 입력 토큰의 대부분을 차지할 수 있습니다.
- 결과는 컨텍스트가 됩니다. 도구가 JSON 데이터 200개 행을 반환하면, 그 전체가 다음 요청과 그 이후의 모든 요청에 포함됩니다.
- 매 왕복 호출마다 요금이 청구됩니다. 도구 다섯 개를 사용하는 작업에는 최소 여섯 번의 요청이 필요합니다.
- 도구 출력 길이에 상한을 두고 반환 전에 요약하세요. 결과를 모델에 실제로 필요한 내용으로 잘라내는 것은 대부분의 에이전트 루프에서 가장 효과가 큰 개선입니다. 

도구 스키마는 턴이 바뀌어도 일정하므로 시스템 프롬프트와 함께 [프롬프트 캐싱](/ko/docs/guides/prompt-caching/) 적용하기에 적합한 대상입니다. 

[Messages API기본 참조 문서](/ko/docs/api-reference/messages/)[비용 관리에이전트 토큰이 사용되는 곳](/ko/docs/guides/cost-control/)[MCP 서버Claude Code용 사전 구성 도구](/ko/docs/guides/mcp-servers/) 

[이전요청 속도 제한](/ko/docs/api-reference/rate-limits/)[다음비전 및 이미지 입력](/ko/docs/api-reference/vision/)