Converse API를 사용하여 도구 직접 호출

모델이 도구를 사용하여 메시지에 대한 응답을 완성하도록 하려면 메시지와 하나 이상의 도구에 대한 정의를 모델에 전송합니다. 모델이 도구 중 하나가 응답을 생성하는 데 도움이 될 수 있다고 판단하면 해당 도구를 사용하고 도구 결과를 모델로 다시 보내라는 요청을 반환합니다. 그런 다음 모델은 결과를 사용하여 원본 메시지에 대한 응답을 생성합니다.

다음 단계에서는 Converse API를 통해 도구를 사용하는 방법을 보여줍니다. 예제 코드는 Converse API 도구 사용 예제 항목을 참조하세요.

1단계: 메시지 및 도구 정의 전송

메시지 및 도구 정의를 전송하려면 Converse 또는 ConverseStream(스트리밍 응답용) 작업을 사용합니다.

도구의 정의는 toolConfig(ToolConfiguration) 요청 파라미터에서 Converse 작업에 전달하는 JSON 스키마입니다. 스키마에 대한 자세한 내용은 JSON schema를 참조하세요. 다음은 라디오 방송국에서 재생되는 가장 인기 있는 노래를 가져오는 도구의 예제 스키마입니다.

{
    "tools": [
        {
            "toolSpec": {
                "name": "top_song",
                "description": "Get the most popular song played on a radio station.",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "sign": {
                                "type": "string",
                                "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                            }
                        },
                        "required": [
                            "sign"
                        ]
                    }
                }
            }
        }
    ]
}

동일한 요청에서 messages(Message) 요청 파라미터의 사용자 메시지도 전달합니다.

[
    {
        "role": "user",
        "content": [
            {
                "text": "What is the most popular song on WZPZ?"
            }
        ]
    }
]

Anthropic Claude 3 모델을 사용하는 경우 toolConfig 요청 파라미터에 toolChoice(ToolChoice) 필드를 지정하여 도구 사용을 강제할 수 있습니다. 도구를 강제로 사용하는 것은 개발 과정에서 도구를 테스트하는 데 유용합니다. 다음 예제에서는 top_song이라는 도구를 강제로 사용하는 방법을 보여줍니다.

{"tool" : {"name" : "top_song"}}

전달할 수 있는 다른 파라미터에 대한 자세한 내용은 Converse API 작업과 대화 수행 섹션을 참조하세요.

2단계: 모델에서 도구 요청 가져오기

메시지 및 도구 정의로 Converse 작업을 간접 호출하면 모델은 도구 정의를 사용하여 도구에서 메시지에 응답해야 하는지 여부를 결정합니다. 예를 들어, 채팅 앱 사용자가 WZPZ에서 가장 인기 있는 노래는 무엇인가요?라는 메시지를 전송하는 경우 모델은 메시지를 top_song 도구 정의의 스키마와 일치시키고 도구가 응답을 생성하는 데 도움이 될 수 있다고 결정합니다.

모델이 응답을 생성하는 데 도구가 필요하다고 결정하면 모델은 stopReason 응답 필드를 tool_use로 설정합니다. 또한 응답은 모델이 실행하려는 도구(top_song)와 도구로 쿼리하려는 라디오 방송국(WZPZ)을 식별합니다. 요청된 도구에 대한 정보는 output(ConverseOutput) 필드에서 모델이 반환하는 메시지에 있습니다. 구체적으로는 toolUse(ToolUseBlock) 필드입니다. toolUseId 필드를 사용하여 이후의 직접 호출에서 도구 요청을 식별합니다.

다음 예제는 1단계: 메시지 및 도구 정의 전송에서 설명한 메시지를 전달할 때 Converse의 응답을 보여줍니다.

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

3단계: 모델에 대한 도구 요청

모델 응답의 toolUse 필드에서 name 필드를 사용하여 도구의 이름을 식별합니다. 그런 다음 도구 구현을 직접 호출하고 input 필드에서 입력 파라미터를 전달합니다.

다음으로 toolResult(ToolResultBlock) 콘텐츠 블록이 포함된 사용자 메시지를 구성합니다. 콘텐츠 블록에 도구의 응답과 이전 단계에서 받은 도구 요청의 ID를 포함합니다.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "json": {
                            "song": "Elemental Hotel",
                            "artist": "8 Storey Hike"
                        }
                    }
                ]
            }
        }
    ]
}

존재하지 않는 라디오 방송국에 대한 요청과 같은 오류가 도구에 발생하는 경우, toolResult 필드의 모델에 오류 정보를 전송할 수 있습니다. 오류를 표시하려면 status 필드에 error를 지정합니다. 다음 예제 오류는 도구가 라디오 방송국을 찾을 수 없는 경우에 발생합니다.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "text": "Station WZPA not found."
                    }
                ],
                "status": "error"
            }
        }
    ]
}

4단계: 모델 응답 가져오기

이전 단계에서 생성한 사용자 메시지를 Converse에 대한 직접 호출에 포함시켜 모델과의 대화를 계속합니다. 그러면 모델은 사용자가 메시지의 toolResult 필드에 제공한 정보로 원본 메시지(WZPZ에서 가장 인기 있는 노래는 무엇인가요?)에 답변하는 응답을 생성합니다.

{
     "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
                }
            ]
        }
    },
    "stopReason": "end_turn"