컨버스로 툴에 전화하기 API

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

다음 단계는 API Converse와 함께 도구를 사용하는 방법을 보여줍니다. 예제 코드는 컨버스 API 툴 사용 예제 항목을 참조하세요.

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

메시지 및 도구 정의를 보내려면 Converse or ConverseStream(스트리밍 응답의 경우) 작업을 사용합니다.

참고

Meta 다음과 같은 도구를 사용하는 프롬프트를 만들기 위한 구체적인 권장 사항이 있습니다.Llama 3.1 (이상) 모델. 자세한 내용은 의 JSON기반 도구 호출을 참조하십시오.Meta .

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

{
    "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 (메시지) 요청 파라미터에 사용자 메시지도 전달합니다.

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

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

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

전달할 수 있는 다른 매개변수에 대한 자세한 내용은 을 참조하십시오. 컨버스와 대화를 나누세요

2단계: 모델로부터 도구 요청 받기

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

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

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

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_hbTgdi0CSLq_hM4P8csZJA",
                        "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 필드에 있는 모델에 오류 정보를 보낼 수 있습니다. 오류를 나타내려면 error status 필드에 지정하십시오. 다음 예제 오류는 도구가 라디오 방송국을 찾을 수 없는 경우에 대한 것입니다.

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

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

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

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