Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Konfigurasi alat
<a name="sonic-tool-configuration"></a>

Amazon Nova 2 Sonic mendukung penggunaan alat (juga dikenal sebagai pemanggilan fungsi), memungkinkan model untuk meminta informasi atau tindakan eksternal selama percakapan, seperti panggilan API, kueri basis data, atau fungsi kode khusus. Ini memungkinkan asisten suara Anda untuk mengambil tindakan, mengambil informasi, dan berintegrasi dengan layanan eksternal berdasarkan permintaan pengguna.

 Nova 2 Sonic memiliki fitur panggilan alat asinkron, memungkinkan AI untuk terus berbicara secara alami sementara alat berjalan di latar belakang lain - menciptakan pengalaman pengguna yang lebih lancar dan responsif.

Berikut ini adalah langkah-langkah sederhana tentang cara menggunakan alat:

1. Tentukan alat: tentukan alat yang tersedia dengan parameternya di acara PromptStart

1. Pengguna berbicara: pengguna membuat permintaan yang membutuhkan alat (seperti, “Bagaimana cuaca di Seattle?”)

1. Pemanggilan alat: Nova 2 Sonic mengenali kebutuhan dan mengirimkan acara ToolUse

1. Jalankan rool: Aplikasi Anda mengeksekusi alat dan mengembalikan hasil

1. Generasi Respons: Nova 2 Sonic menggabungkan hasilnya ke dalam respons yang diucapkan

Diagram berikut menggambarkan cara kerja penggunaan alat:

![](http://docs.aws.amazon.com/id_id/nova/latest/nova2-userguide/images/How-tool-use-works_5.png)


## Mendefinisikan alat
<a name="sonic-tool-defining"></a>

Alat didefinisikan menggunakan skema JSON yang menjelaskan tujuan, parameter, dan input yang diharapkan.

Berikut ini adalah komponen dan penjelasan definisi alat:
+ Nama: Pengidentifikasi unik untuk alat (gunakan snake\_case)
+ Deskripsi: Penjelasan yang jelas tentang apa yang dilakukan alat; membantu AI memutuskan kapan menggunakannya
+ InputSchema: Skema JSON yang mendefinisikan parameter yang diterima alat
+ Properti: Parameter individu dengan jenis dan deskripsi
+ Wajib: Array nama parameter yang harus disediakan

### Contoh definisi alat
<a name="w2aac25c13c23c15b9b1"></a>

Berikut adalah definisi alat cuaca sederhana

```
{
  "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"]
      }
    }
  }
}
```

### Mengkonfigurasi Alat di PromptStart
<a name="w2aac25c13c23c15b9b3"></a>

Konfigurasi alat diteruskan ke Nova 2 Sonic dalam `promptStart` acara bersama dengan pengaturan output audio dan teks:

```
{
    "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": {}
                }
            }
        }
    }
}
```

## Parameter Pilihan Alat
<a name="sonic-tool-choice-parameters"></a>

Nova 2 Sonic mendukung tiga parameter pilihan alat untuk mengontrol kapan dan alat mana yang digunakan. Tentukan parameter ToolChoice dalam konfigurasi alat Anda:
+ Otomatis (default): Model memutuskan apakah ada alat yang diperlukan dan dapat memanggil beberapa alat jika diperlukan. Memberikan fleksibilitas maksimum.
+ Apa saja: Memastikan setidaknya satu alat yang tersedia dipanggil di awal respons, dengan model memilih yang paling tepat. Berguna ketika Anda memiliki banyak basis pengetahuan atau alat dan ingin menjamin satu digunakan.
+ Alat: Memaksa alat bernama tertentu untuk dipanggil tepat sekali di awal respons. Misalnya, jika Anda menentukan alat basis pengetahuan, model akan menanyakannya sebelum merespons, terlepas dari apakah menurut alat tersebut diperlukan.

**Contoh Pilihan Alat**

Otomatis (default)

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

Apa saja:

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

Alat Khusus:

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

## Menerima dan memproses acara penggunaan alat
<a name="sonic-tool-receiving"></a>

Ketika Amazon Nova 2 Sonic menentukan bahwa alat diperlukan, ia mengirimkan `toolUse` acara yang berisi:

1. `toolUseID`: pengidentifikasi unik untuk pemanggilan alat ini

1. ToolName: nama alat untuk mengeksekusi

1. Konten: String JSON yang berisi parameter yang diekstrak dari permintaan pengguna

1. SessionId: pengidentifikasi sesi saat ini

1. Peran: atur ke “ALAT” untuk acara penggunaan alat

Contoh acara penggunaan alat

```
{
    "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>"
        }
    }
}
```

Langkah-langkah pemrosesan

1. Terima acara ToolUse dari Nova 2 Sonic

1. Ekstrak nama alat dan parameter dari acara

1. Jalankan logika alat Anda (panggilan API, kueri basis data, dan sebagainya)

1. Kembalikan hasil menggunakan acara ToolResult

Contoh ToolResult Acara

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

## Praktik terbaik
<a name="sonic-tool-best-practices"></a>
+ Deskripsi yang jelas: Tulis deskripsi alat terperinci untuk membantu Nova 2 Sonic memahami kapan harus menggunakan setiap alat.
+ Validasi parameter: Selalu validasi parameter alat sebelum eksekusi untuk mencegah kesalahan. Tentukan parameter alat menggunakan skema JSON yang tepat dengan tipe data terstruktur (seperti enum, angka, atau boolean) daripada string terbuka bila memungkinkan.
+ Penanganan kesalahan: Kembalikan pesan kesalahan yang berarti dalam peristiwa ToolResult saat alat gagal.
+ Eksekusi asinkron: Manfaatkan panggilan alat asinkron untuk mempertahankan alur percakapan.
+ Penamaan alat: Gunakan nama deskriptif dan berorientasi tindakan (seperti get\_weather, search\_database, send\_email).