도구 사용 예시
다양한 도구 사용 패턴과 기술을 보여주는 몇 가지 코드 예제가 있습니다. 간결성을 위해 도구는 간단한 도구이며, 최상의 성능을 보장하기 위해 이상적인 것보다 도구 설명이 짧습니다. 자세한 내용은 도구 지정을 참조하세요.
단일 도구
이 예제는 get_weather
도구를 사용하는 기본적인 단일 도구 상황을 보여줍니다.
Claude는 다음과 유사한 응답을 반환합니다:
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-3-opus-20240229",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "<thinking>get_weather 함수를 호출해야 하고, 사용자는 SF를 원하는데, 이는 아마도 San Francisco, CA일 것입니다.</thinking>"
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "San Francisco, CA", "unit": "celsius"}
}
]
}
그런 다음 제공된 입력으로 get_weather
함수를 실행하고 새로운 user
메시지에서 결과를 반환해야 합니다:
이것은 날씨 데이터를 통합한 Claude의 최종 응답을 출력합니다:
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-3-opus-20240229",
"stop_reason": "stop_sequence",
"role": "assistant",
"content": [
{
"type": "text",
"text": "현재 샌프란시스코의 날씨는 섭씨 15도(화씨 59도)입니다. 만의 도시에서는 서늘한 날씨입니다!"
}
]
}
누락된 정보
사용자의 프롬프트에 도구의 모든 필수 매개변수를 채우기에 충분한 정보가 포함되어 있지 않은 경우, Claude 3 Opus는 매개변수가 누락되었음을 인식하고 요청할 가능성이 훨씬 높습니다. Claude 3 Sonnet은 도구 요청을 출력하기 전에 생각하라는 메시지가 표시될 때 특히 요청할 수 있습니다. 그러나 합리적인 값을 추론하기 위해 최선을 다할 수도 있습니다.
예를 들어, 위의 get_weather
도구를 사용하여 위치를 지정하지 않고 Claude에게 “날씨가 어떤가요?”라고 묻는 경우, 특히 Claude 3 Sonnet은 도구 입력을 추측할 수 있습니다:
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "New York, NY", "unit": "fahrenheit"}
}
이 동작은 보장되지 않으며, 특히 모호한 프롬프트와 Claude 3 Opus보다 지능이 낮은 모델의 경우에는 더욱 그렇습니다. Claude 3 Opus에 필요한 매개변수를 채울 만한 충분한 컨텍스트가 없는 경우, 도구 호출을 하는 대신 명확한 질문으로 응답할 가능성이 훨씬 더 높습니다.
여러 도구
단일 요청에서 Claude에게 선택할 수 있는 여러 도구를 제공할 수 있습니다. 다음은 get_weather
와 get_time
도구를 모두 사용하고 둘 다 요청하는 사용자 쿼리의 예입니다.
이 경우 Claude는 사용자의 질문에 완전히 답하기 위해 get_weather
와 get_time
이라는 두 개의 별도 도구를 한 번에 하나씩 사용하려고 할 가능성이 높습니다. 그러나 특히 서로 의존하지 않는 경우에는 두 개의 tool_use
블록을 한 번에 출력하기도 합니다. 각 도구를 실행하고 단일 user
메시지 내에서 별도의 tool_result
블록에 결과를 반환해야 합니다.
순차적 도구
일부 작업은 한 도구의 출력을 다른 도구의 입력으로 사용하여 여러 도구를 순차적으로 호출해야 할 수 있습니다. 이런 경우 Claude는 한 번에 하나의 도구를 호출합니다. 모든 도구를 한 번에 호출하라는 메시지가 표시되면 Claude는 업스트림에 있는 도구의 도구 결과에 의존하는 다운스트림에 있는 도구의 매개변수를 추측할 가능성이 높습니다.
다음은 get_location
도구를 사용하여 사용자의 위치를 가져온 다음 해당 위치를 get_weather
도구에 전달하는 예입니다:
이 경우 Claude는 먼저 get_location
도구를 호출하여 사용자의 위치를 가져옵니다. tool_result
에서 위치를 반환한 후 Claude는 해당 위치로 get_weather
를 호출하여 최종 답변을 얻습니다.
전체 대화는 다음과 같을 수 있습니다:
역할 | 내용 |
---|---|
사용자 | 내가 있는 곳의 날씨는 어떤가요? |
어시스턴트 | <thinking>이 질문에 답하려면 먼저 get_location 도구를 사용하여 사용자의 위치를 확인해야 합니다. 그런 다음 해당 위치를 get_weather 도구에 전달하여 현재 날씨를 찾을 수 있습니다.</thinking>[get_location에 대한 도구 사용] |
사용자 | [일치하는 ID와 San Francisco, CA 결과가 있는 get_location에 대한 도구 결과] |
어시스턴트 | [다음 입력으로 get_weather에 대한 도구 사용]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” } |
사용자 | [일치하는 ID와 “화씨 59도(섭씨 15도), 대체로 흐림”이라는 결과가 있는 get_weather에 대한 도구 결과] |
어시스턴트 | 현재 샌프란시스코에 있는 귀하의 위치를 기준으로 현재 날씨는 화씨 59도(섭씨 15도)이며 대체로 흐립니다. 도시에서는 꽤 서늘하고 흐린 날씨입니다. 외출할 때는 가벼운 재킷을 가져가는 것이 좋습니다. |
이 예제는 Claude가 여러 출처에서 데이터를 수집해야 하는 질문에 답하기 위해 여러 도구 호출을 연결하는 방법을 보여줍니다. 주요 단계는 다음과 같습니다:
- Claude는 먼저 날씨 질문에 답하려면 사용자의 위치가 필요하다는 것을 깨닫고
get_location
도구를 호출합니다. - 사용자(즉, 클라이언트 코드)는 실제
get_location
함수를 실행하고tool_result
블록에서 “San Francisco, CA” 결과를 반환합니다. - 이제 위치를 알게 된 Claude는
location
매개변수로 “San Francisco, CA”를 전달하여get_weather
도구를 호출합니다(unit
은 필수 매개변수가 아니므로unit
매개변수도 추측합니다). - 사용자는 다시 제공된 인수로 실제
get_weather
함수를 실행하고 다른tool_result
블록에서 날씨 데이터를 반환합니다. - 마지막으로 Claude는 날씨 데이터를 원래 질문에 대한 자연어 응답에 통합합니다.
사고 연쇄 도구 사용
기본적으로 Claude 3 Opus는 도구가 필요한지, 어떤 도구를 사용할지, 적절한 매개변수는 무엇인지 가장 잘 판단하기 위해 도구 사용 쿼리에 답하기 전에 생각하도록 프롬프트됩니다. Claude 3 Sonnet과 Claude 3 Haiku는 가능한 한 많은 도구를 사용하도록 프롬프트되며 불필요한 도구를 호출하거나 누락된 매개변수를 추론할 가능성이 더 높습니다. Sonnet 또는 Haiku가 도구 호출을 하기 전에 사용자 쿼리를 더 잘 평가하도록 프롬프트하려면 다음 프롬프트를 사용할 수 있습니다:
사고 연쇄 프롬프트
관련 도구(사용 가능한 경우)를 사용하여 사용자의 요청에 답하세요. 도구를 호출하기 전에 \<thinking>\</thinking> 태그 내에서 분석을 수행하세요. 먼저 제공된 도구 중 사용자의 요청에 답하는 데 관련된 도구가 무엇인지 생각해 보세요. 둘째, 관련 도구의 필수 매개변수를 하나씩 살펴보고 사용자가 직접 제공했거나 값을 추론할 수 있는 충분한 정보를 제공했는지 확인하세요. 매개변수를 추론할 수 있는지 결정할 때는 특정 값을 지원하는지 모든 컨텍스트를 신중하게 고려하세요. 모든 필수 매개변수가 있거나 합리적으로 추론할 수 있는 경우 생각 태그를 닫고 도구 호출을 진행하세요. 그러나 필수 매개변수 중 하나의 값이 누락된 경우 함수를 호출하지 마세요(누락된 매개변수에 대한 필러도 사용하지 마세요). 대신 사용자에게 누락된 매개변수를 제공하도록 요청하세요. 제공되지 않은 경우 선택적 매개변수에 대한 추가 정보를 요청하지 마세요.
JSON 모드
도구를 실행하거나 함수를 통해 출력을 실행할 의도가 없더라도 도구를 사용하여 Claude가 스키마를 따르는 JSON 출력을 생성하도록 할 수 있습니다.
이런 식으로 도구를 사용할 때:
- 일반적으로 단일 도구를 제공하려고 합니다
tool_choice
를 설정하여(도구 사용 강제 참조) 모델이 해당 도구를 명시적으로 사용하도록 지시해야 합니다- 모델이
input
을 도구에 전달할 것이므로 도구의 이름과 설명은 모델의 관점에서 작성되어야 합니다.
다음은 특정 형식을 따르는 이미지를 설명하기 위해 record_summary
도구를 사용합니다.