도구 사용 및 함수 호출

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

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

반복 흐름

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

도구 정의(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"
  }]
}

OpenAI 형식

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

도구 사용 비용

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