View a markdown version of this page

도구 구성 - Amazon Nova
도구 정의도구 선택 파라미터도구 사용 이벤트 수신 및 처리모범 사례

도구 구성

Amazon Nova 2 Sonic은 도구 사용(함수 직접 호출이라고도 함)을 지원하므로 모델은 API 직접 호출, 데이터베이스 쿼리 또는 사용자 지정 코드 함수와 같이 대화 중에 외부 정보 또는 작업을 요청할 수 있습니다. 이를 통해 음성 어시스턴트는 사용자 요청을 기반으로 작업을 수행하고, 정보를 검색하며, 외부 서비스와 통합할 수 있습니다.

Nova 2 Sonic은 비동기식 도구를 직접 호출하여 도구가 백그라운드에서 실행되는 동안 AI가 자연적으로 계속 대화함으로써 보다 유동적이고 응답성이 뛰어난 사용자 환경을 구축하도록 지원합니다.

다음은 도구 사용 방법에 대한 단순화된 단계입니다.

  1. 도구 정의: promptStart 이벤트에서 해당 파라미터를 사용하여 사용 가능한 도구 지정

  2. 사용자 발화: 사용자가 도구를 요구하는 요청(예: '시애틀 날씨는 어떤가요?')

  3. 도구 간접 호출: Nova 2 Sonic은 필요성을 인식하고 toolUse 이벤트를 전송함

  4. 역할 실행: 애플리케이션이 도구를 실행하고 결과를 반환함

  5. 응답 생성: Nova 2 Sonic은 결과를 음성 응답에 통합함

다음 다이어그램에서는 도구 사용의 작동 방식을 보여줍니다.

도구 정의

도구는 용도, 파라미터 및 예상 입력을 설명하는 JSON 스키마를 사용하여 정의됩니다.

다음은 도구 정의 구성 요소 및 설명입니다.

  • Name: 도구의 고유 식별자(snake_case 사용)

  • Description: 도구가 수행하는 작업에 대한 명확한 설명, AI가 도구 사용 시점을 결정하는 데 도움이 됨

  • InputSchema: 도구가 허용하는 파라미터를 정의하는 JSON 스키마

  • Properties: 유형 및 설명을 포함하는 개별 파라미터

  • Required: 제공해야 하는 파라미터 이름 배열

다음은 단순한 날씨 도구 정의입니다.

{
  "toolSpec": {
    "name": "get_weather",
    "description": "Get current weather information for a specific location",
    "inputSchema": {
      "json": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or zip code"
          },
          "units": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "Temperature units"
          }
        },
        "required": ["location"]
      }
    }
  }
}

도구 구성은 오디오 및 텍스트 출력 설정과 함께 promptStart 이벤트에서 Nova 2 Sonic으로 전달됩니다.

{
    "event": {
        "promptStart": {
            "promptName": "<prompt-id>",
            "textOutputConfiguration": {
                "mediaType": "text/plain"
            },
            "audioOutputConfiguration": {
                "mediaType": "audio/lpcm",
                "sampleRateHertz": 16000,
                "sampleSizeBits": 16,
                "channelCount": 1,
                "voiceId": "matthew",
                "encoding": "base64",
                "audioType": "SPEECH"
            },
            "toolUseOutputConfiguration": {
                "mediaType": "application/json"
            },
            "toolConfiguration": {
                "tools": [
                    {
                        "toolSpec": {
                            "name": "get_weather",
                            "description": "Get current weather information for a specific location",
                            "inputSchema": {
                                "json": {
                                    "type": "object",
                                    "properties": {
                                        "location": {
                                            "type": "string",
                                            "description": "City name or zip code"
                                        },
                                        "units": {
                                            "type": "string",
                                            "enum": ["celsius", "fahrenheit"],
                                            "description": "Temperature units"
                                        }
                                    },
                                    "required": ["location"]
                                }
                            }
                        }
                    }
                ],
                "toolChoice": {
                    "auto": {}
                }
            }
        }
    }
}

도구 선택 파라미터

Nova 2 Sonic은 도구의 사용 시점과 사용할 도구를 제어하기 위해 세 가지 도구 선택 파라미터를 지원합니다. 도구 구성에서 toolChoice 파라미터를 지정합니다.

  • Auto(기본값): 모델은 도구가 필요한지를 결정하고 필요한 경우 여러 도구를 직접 호출할 수 있습니다. 유연성을 극대화합니다.

  • Any: 모델이 가장 적절한 도구를 선택할 수 있도록 응답 시작 위치에서 사용 가능한 도구 중 하나 이상이 직접 호출되도록 합니다. 지식 베이스나 도구가 여러 개 있고 이 중 하나가 사용되도록 보장하려는 경우에 유용합니다.

  • Tool: 응답 시작 시 명명된 특정 도구를 정확히 한 번 강제로 직접 호출합니다. 예를 들어 지식 베이스 도구를 지정하면 모델이 해당 도구가 필요하다고 판단하는지에 관계없이 응답 전에 이를 쿼리합니다.

도구 선택 예제

Auto(기본값)

"toolChoice": { 
    "auto": {} 
}

임의:

"toolChoice": {
    "any": {}
}

특정 도구:

"toolChoice": {
    "tool": {
        "name": "get_weather"
    }
}

도구 사용 이벤트 수신 및 처리

Amazon Nova 2 Sonic에서 도구가 필요하다고 판단하면 다음이 포함된 toolUse 이벤트를 전송합니다.

  1. toolUseID: 이 도구의 간접 호출에 대한 고유 식별자

  2. ToolName: 실행할 도구 이름

  3. 콘텐츠: 사용자의 요청에서 추출된 파라미터를 포함하는 JSON 문자열

  4. SessionID: 현재 세션 식별자

  5. Role: 도구 사용 이벤트에 대해 'TOOL'로 설정

도구 사용 이벤트 예제

{
    "event": {
        "toolUse": {
            "completionId": "<completion-id>",
            "content": "{\"location\": \"Seattle\", \"units\": \"fahrenheit\"}",
            "contentId": "<content-id>",
            "promptName": "<prompt-id>",
            "role": "TOOL",
            "sessionId": "<session-id>",
            "toolName": "get_weather",
            "toolUseId": "<tool-use-id>"
        }
    }
}

처리 단계

  1. Nova 2 Sonic에서 toolUse 이벤트 수신

  2. 이벤트에서 도구 이름 및 파라미터 추출

  3. 도구 로직 실행(API 직접 호출, 데이터베이스 쿼리 등)

  4. toolResult 이벤트를 사용하여 결과 반환

ToolResult 이벤트 예제

{
    "event": {
        "toolResult": {
            "promptName": "<prompt-id>",
            "contentName": "<content-id>",
            "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"humidity\": 45}"
        }
    }
}

모범 사례

  • 명확한 설명: Nova 2 Sonic이 각 도구를 언제 사용해야 하는지 이해하는 데 도움이 되는 자세한 도구 설명을 작성합니다.

  • 파라미터 검증: 오류를 방지하기 위해 실행 전에 항상 도구 파라미터를 검증합니다. 가능하면 서술형 문자열 대신 정형 데이터 유형(예: 열거형, 숫자 또는 부울)이 있는 적절한 JSON 스키마를 사용하여 도구 파라미터를 정의합니다.

  • 오류 처리: 도구가 실패하면 toolResult 이벤트에서 의미 있는 오류 메시지를 반환합니다.

  • 비동기식 실행: 비동기식 도구 직접 호출을 활용하여 대화 흐름을 유지 관리합니다.

  • 도구 이름 지정: 설명이 포함된 작업 중심의 이름(예: get_weather, search_database, send_email)을 사용합니다.