Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Penggunaan alat (panggilan fungsi) dengan Amazon Nova
**catatan**
Dokumentasi ini untuk Amazon Nova Versi 1. Untuk informasi tentang penggunaan alat dengan Amazon Nova 2, kunjungi [Menggunakan alat (panggilan fungsi)](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html).
Alat adalah cara untuk menyediakan fungsionalitas eksternal ke Amazon Nova seperti panggilan API atau fungsi kode. Bagian ini akan membahas bagaimana Anda dapat mendefinisikan dan mengintegrasikan dengan alat saat bekerja dengan model Amazon Nova.
Penggunaan alat melibatkan tiga langkah tingkat tinggi:
+ **Kueri pengguna** - Anda menentukan alat yang dapat digunakan Amazon Nova dengan menyediakan skema JSON yang menjelaskan fungsionalitas dan persyaratan input setiap alat.
+ **Pemilihan Alat** - Ketika pengguna mengirim pesan, Amazon Nova akan menganalisisnya untuk menentukan apakah alat diperlukan untuk menghasilkan respons. Ini disebut sebagai pilihan `Auto` alat. Lihat [Memilih alat](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html) untuk informasi selengkapnya. Jika Amazon Nova mengidentifikasi alat yang sesuai, itu akan “memanggil alat” dan mengembalikan nama alat dan parameter yang akan digunakan.
Anda, sebagai pengembang, bertanggung jawab untuk mengeksekusi alat berdasarkan permintaan model. Ini berarti Anda perlu menulis kode yang memanggil fungsionalitas alat dan memproses parameter input yang disediakan oleh model.
**catatan**
Seperti semua tanggapan LLM, Amazon Nova dapat berhalusinasi panggilan alat. Adalah tanggung jawab Anda, pengembang, untuk memvalidasi bahwa alat itu ada, input diformat dengan benar, dan izin yang sesuai sudah ada.
+ **Hasil Pengembalian** - Setelah menjalankan alat, Anda harus mengirim hasilnya kembali ke Amazon Nova dalam format terstruktur. Format yang valid termasuk JSON atau kombinasi teks dan gambar. Ini memungkinkan Amazon Nova untuk memasukkan output alat ke dalam respons akhir kepada pengguna.
Jika ada kesalahan selama eksekusi alat, Anda dapat menunjukkan ini dalam respons alat ke Amazon Nova, memungkinkan Amazon Nova untuk menyesuaikan responsnya.
Pertimbangkan contoh sederhana alat kalkulator:
------
#### [ User query ]
Langkah pertama dalam alur kerja pemanggilan alat adalah kueri pengguna ke Amazon Nova untuk hasil persamaan matematika - 10 kali 5. Kueri ini dikirim sebagai prompt ke Amazon Nova bersama dengan spesifikasi alat yang mewakili kalkulator.
```
user_query = "10*5"
messages = [{
"role": "user",
"content": [{"text": user_query}]
}]
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator", # Name of the tool
"description": "A calculator tool that can execute a math equation", # Concise description of the tool
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": { # The name of the parameter
"type": "string", # parameter type: string/int/etc
"description": "The full equation to evaluate" # Helpful description of the parameter
}
},
"required": [ # List of all required parameters
"equation"
]
}
}
}
}
]
}
```
------
#### [ Tool selection ]
Amazon Nova menggunakan konteks alat bersama dengan prompt pengguna untuk menentukan alat yang diperlukan untuk digunakan dan konfigurasi yang diperlukan. Ini dikembalikan sebagai bagian dari respons API.
```
{
"toolUse": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"name": "calculator",
"input": {
"equation": "10*5"
}
}
}
```
Aplikasi ini bertanggung jawab untuk mengeksekusi alat dan menyimpan hasilnya.
```
def calculator(equation: str):
return eval(equation)
tool_result = calculator("10*5")
```
------
#### [ Return results ]
Untuk mengembalikan hasil alat ke Amazon Nova, hasil alat disertakan dalam permintaan API baru. Perhatikan bahwa ID penggunaan alat konsisten dengan yang dikembalikan dari Amazon Nova pada respons sebelumnya.
```
{
"toolResult": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"content": [
{
"json": {
"result": "50"
}
}
],
"status": "success"
}
}
```
+ Amazon Nova akan menggunakan konteks lengkap pesan, termasuk kueri pengguna awal, penggunaan alat, dan hasil alat untuk menentukan respons akhir terhadap pengguna. Dalam hal ini, Amazon Nova akan menanggapi pengguna bahwa “10 kali 5 adalah 50".
------
Amazon Nova memungkinkan penggunaan alat di Invoke dan Converse API, namun, untuk keluasan fitur lengkap, kami sarankan menggunakan [Converse API dan akan menggunakan contoh dengan API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html) ini untuk bergerak maju.
**Topics**
+ [Mendefinisikan alat](tool-use-definition.md)
+ [Memanggil alat](tool-use-invocation.md)
+ [Memilih alat](tool-choice.md)
+ [Mengembalikan hasil alat](tool-use-results.md)
+ [Menggunakan alat bawaan](tool-built-in.md)
+ [Melaporkan kesalahan](tool-use-error.md)
+ [Referensi tambahan](#tool-use-resources)
# Mendefinisikan alat
Langkah penting dalam alur kerja pemanggilan alat adalah mendefinisikan alat. Definisi alat harus mencakup semua konteks yang diperlukan untuk memandu model kapan tepat untuk memanggil alat.
Untuk menentukan alat, buat konfigurasi alat dan teruskan dengan pesan pengguna ke API. Skema [konfigurasi alat](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html) mengharapkan serangkaian alat dan secara opsional merupakan parameter pilihan alat.
**catatan**
Amazon Nova mendukung`auto`,`any`, dan `tool` opsi untuk`toolChoice`. Untuk informasi selengkapnya, lihat [ToolChoice](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html)di dokumentasi Amazon Bedrock API dan [Gunakan alat untuk menyelesaikan respons model Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html).
Berikut adalah contoh cara mendefinisikan alat:
```
tool_config = {
"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"
]
}
}
}
}
],
}
```
Nama, deskripsi, dan skema masukan harus eksplisit dengan fungsionalitas alat yang tepat. Pastikan setiap pembeda utama kapan menggunakan alat tercermin dalam konfigurasi alat.
**catatan**
Model pemahaman Amazon Nova saat ini hanya mendukung sebagian JsonSchema fungsionalitas saat digunakan untuk mendefinisikan API [ToolInputSchema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolInputSchema.html)in Converse.
Skema tingkat atas harus bertipe [Object](https://json-schema.org/understanding-json-schema/reference/object).
Hanya tiga bidang yang didukung di tingkat atas Object - type (harus disetel ke 'object') [https://json-schema.org/understanding-json-schema/reference/object#properties](https://json-schema.org/understanding-json-schema/reference/object#properties), dan [https://json-schema.org/understanding-json-schema/reference/object#required](https://json-schema.org/understanding-json-schema/reference/object#required).
Untuk pemanggilan alat, kami sarankan mengatur suhu ke 0 untuk mengaktifkan decoding serakah.
Berikut adalah contoh memanggil alat dengan Converse API:
```
import json
import boto3
client = boto3.client("bedrock-runtime", region_name="us-east-1")
input_text = "What is the most popular song on WZPZ?"
messages = [{
"role": "user",
"content": [{"text": input_text}]
}]
inf_params = {"maxTokens": 1000, "temperature": 0}
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
messages.append(response["output"]["message"])
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(response, indent=2))
# Print the tool content for easy readability.
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print("\n[Tool Response]")
print(tool)
```
# Memanggil alat
Jika Amazon Nova memutuskan untuk memanggil alat, blok penggunaan alat akan dikembalikan sebagai bagian dari pesan asisten dan alasan berhenti adalah “tool\$1use”. Blok alat akan berisi nama alat dan inputnya.
**catatan**
Untuk meningkatkan akurasi panggilan alat, perilaku default model Amazon Nova adalah menggunakan chain-of-thought alasan untuk pemanggilan alat. Proses berpikir akan tersedia untuk Anda dalam pesan asisten dan akan dimuat dalam tag. Dimungkinkan untuk memiliki beberapa panggilan alat dan blok berpikir dalam respons sehingga aplikasi Anda harus mempertimbangkan hal ini.
Jika pilihan alat dikonfigurasi ke `any` atau`tool`, ini akan mengesampingkan chain-of-thought perilaku dan respons hanya akan berisi panggilan alat yang diperlukan.
```
{
"toolUse":
{
"toolUseId": "tooluse_20Z9zl0BQWSXjFuLKdTJcA",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
```
Untuk benar-benar memanggil alat, nama alat dan argumen dapat diekstraksi dari pesan dan aplikasi kemudian dapat memanggilnya.
Berikut adalah contoh bagaimana Anda dapat memproses panggilan alat.
```
def get_top_song(sign):
print(f"Getting the top song at {sign}")
return ("Espresso", "Sabrina Carpenter")
stop_reason = response["stopReason"]
tool, song, artist = None, None, None
if stop_reason == "tool_use":
thought_process = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(thought_process)
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
if tool["name"] == "top_song":
song, artist = get_top_song(tool["input"]["sign"])
```
Penting untuk mengingat keamanan saat Anda mendefinisikan dan menggunakan alat. LLMs seperti Amazon Nova tidak memiliki akses ke detail sesi sehingga izin harus divalidasi bila perlu sebelum menjalankan alat. Andalkan detail pengguna dari sesi Anda alih-alih menambah prompt dan memungkinkan Amazon Nova untuk menyuntikkannya ke dalam panggilan alat.
# Memilih alat
Model Amazon Nova mendukung fungsionalitas *pilihan alat*. Pilihan alat memungkinkan Anda, sebagai pengembang, untuk mengontrol cara di mana alat dipanggil. Ada tiga opsi parameter yang didukung untuk pilihan alat:`tool`,`any`, dan`auto`.
+ **Alat** - Alat yang ditentukan akan dipanggil sekali.
+ **Apa saja** - Salah satu alat yang disediakan akan dipanggil setidaknya sekali.
+ **Otomatis** - Model akan memutuskan apakah akan memanggil alat dan beberapa alat akan dipanggil jika diperlukan.
------
#### [ Tool ]
Menggunakan `tool` sebagai pilihan alat memungkinkan Anda untuk mengontrol alat khusus yang dipanggil model. Contoh di bawah ini menyoroti hal ini dengan kasus penggunaan keluaran terstruktur di mana respons diperlukan untuk diformat secara konsisten.
```
tool_config = {
"toolChoice": {
"tool": { "name" : "extract_recipe"}
},
"tools": [
{
"toolSpec": {
"name": "extract_recipe",
"description": "Extract recipe for cooking instructions",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the recipe"
},
"description": {
"type": "string",
"description": "Brief description of the dish"
},
"ingredients": {
"type": "array",
"items": {
"type": "string",
"description": "Name of ingredient"
}
}
},
"required": ["name", "description", "ingredients"]
}
}
}
}
]
}
```
------
#### [ Any ]
Menggunakan `any` sebagai pilihan alat memungkinkan Anda untuk memastikan bahwa setidaknya satu alat dipanggil setiap kali. Sementara keputusan alat mana yang akan dipanggil diserahkan kepada model, akan selalu ada alat yang dikembalikan. Contoh di bawah ini menyoroti penggunaan pilihan alat apa saja untuk kasus penggunaan titik akhir pemilihan API. Ini adalah salah satu contoh ketika sangat membantu untuk meminta model mengembalikan alat tertentu.
```
tool_config = {
"toolChoice": {
"any": {}
},
"tools": [
{
"toolSpec": {
"name": "get_all_products",
"description": "API to retrieve multiple products with filtering and pagination options",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sort_by": {
"type": "string",
"description": "Field to sort results by. One of: price, name, created_date, popularity",
"default": "created_date"
},
"sort_order": {
"type": "string",
"description": "Order of sorting (ascending or descending). One of: asc, desc",
"default": "desc"
},
},
"required": []
}
}
}
},
{
"toolSpec": {
"name": "get_products_by_id",
"description": "API to retrieve retail products based on search criteria",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Unique identifier of the product"
},
},
"required": ["product_id"]
}
}
}
}
]
}
```
------
#### [ Auto ]
Menggunakan `auto` sebagai pilihan alat adalah fungsionalitas default dari dukungan alat dan memungkinkan model untuk memutuskan kapan harus memanggil alat dan berapa banyak alat untuk dipanggil. Ini adalah perilaku jika Anda tidak menyertakan pilihan alat dalam permintaan Anda.
**catatan**
Perilaku default panggilan alat Amazon Nova digunakan chain-of-thought untuk pemilihan alat. Saat menggunakan perilaku default atau pilihan alat`auto`, juga akan ada output proses pemikiran dalam tag.
Contoh berikut menyoroti kasus penggunaan chatbot di mana Anda mungkin ingin mengizinkan model untuk mencari di internet untuk informasi terbaru atau untuk merespons langsung ke pengguna. Pilihan alat ini memberikan fleksibilitas dan akan menyerahkan penalaran pada model.
```
tool_config = {
"toolChoice": {
"auto": {}
},
"tools": [
{
"toolSpec": {
"name": "search",
"description": "API that provides access to the internet",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Query to search by",
},
},
"required": ["query"]
}
}
}
}
]
}
```
------
**catatan**
Saat mengatur parameter pilihan alat, Anda mungkin masih melihat teks keluaran model atau melakukan panggilan alat berurutan setelah pemilihan alat asli. Kami menyarankan Anda mengatur urutan berhenti di sini untuk membatasi output hanya ke alat:
```
“stopSequences”: [“”]
```
Untuk informasi selengkapnya, lihat [InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_InferenceConfiguration.html)di panduan Amazon Bedrock API.
# Mengembalikan hasil alat
Setelah alat dipanggil oleh aplikasi, langkah terakhir adalah memberikan hasil alat ke model. Ini dilakukan dengan mengembalikan hasil alat dengan ID panggilan alat dan konten respons. Konten ini mengikuti [ToolResultBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html)skema:
```
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
```
Isi `ToolResultBlock` harus berupa JSON tunggal atau campuran teks dan gambar.
Bidang status dapat digunakan untuk menunjukkan kepada model status eksekusi alat. Jika eksekusi alat gagal, Anda dapat menunjukkan kegagalan, dan Amazon Nova akan mencoba memodifikasi panggilan alat aslinya.
Lihat [ToolResultContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultContentBlock.html)dokumentasi untuk detail lebih lanjut tentang skema.
Berikut adalah contoh cara menggunakan Converse API untuk mengembalikan hasil alat:
```
messages.append({
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
]
})
inf_params = {"maxTokens": 1000, "temperature": 0}
# Send the tool result to the model.
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
print(response['output']['message'])
```
Untuk detail selengkapnya tentang cara memanfaatkan alat, lihat dokumentasi [Amazon Bedrock Tool Use](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html) atau kunjungi [alat gunakan sampel](https://github.com/aws-samples/amazon-nova-samples/blob/main/multimodal-understanding/repeatable-patterns/10-tool-calling-with-converse/10_tool_calling_with_converse.ipynb) di repositori sampel Amazon Nova.
# Menggunakan alat bawaan
Alat bawaan adalah alat yang dikelola sepenuhnya yang tersedia di luar kotak, tanpa perlu implementasi khusus. Ini dapat diaktifkan di Converse API dengan sakelar sederhana.
## Penerjemah kode
Code Interpreter memungkinkan Nova untuk menjalankan kode Python dengan aman di lingkungan kotak pasir yang terisolasi. Hal ini memungkinkan menulis dan mengeksekusi kode, menganalisis data, membuat visualisasi, dan memecahkan masalah matematika. Misalnya, Code Interpreter dapat digunakan untuk:
+ Menghasilkan laporan keuangan berdasarkan data yang diunggah
+ Analisis statistik lengkap atau simulasi algoritma
+ Jalankan skrip migrasi database di lingkungan yang terisolasi
+ Jalankan pengujian unit untuk kode baru yang dihasilkan
Berikut adalah contoh cara mengaktifkan Code Interpreter dengan Converse API:
```
{
"messages": [
{
"role": "user",
"content": [{"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82")}]
}
],
"toolConfig": {
"tools": [
{
"systemTool": {
"name": "nova_code_interpreter"
}
}
]
},
```
Dalam hal ini, model akan menentukan bahwa permintaan memerlukan komputasi sehingga menghasilkan kode Python yang diperlukan dan memanggil alat interpreter kode.
```
{
"toolUse": {
"input": {
"code": "'''Calculate the average of the given numbers.'''\nnumbers = [10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82]\nsum_numbers = sum(numbers)\ncount = len(numbers)\naverage = sum_numbers / count\n(sum_numbers, count, average)"
},
"name": "nova_code_interpreter",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "server_tool_use"
}
},
```
Interpreter menjalankan kode ini dalam kotak pasir dan menangkap hasilnya, output dalam skema standar:
```
{
"stdOut": String,
"stdErr": String,
"exitCode": int,
"isError": boolean
}
```
Dalam hal ini, Anda akan menerima kembali:
```
{
"toolResult": {
"content": [
{
"text": "{\"stdOut\":\"(1212, 12, 101.0)\",\"stdErr\":\"\",\"exitCode\":0,\"isError\":false}"
}
],
"status": "success",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "nova_code_interpreter_result"
}
}
```
## Protokol Konteks Model
Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan pengembang untuk membangun koneksi dua arah yang aman antara sumber data mereka dan alat yang didukung AI. Alih-alih menulis adaptor khusus untuk setiap API atau layanan, Anda dapat menjalankan server MCP dan membiarkan Nova menemukan alatnya secara otomatis melalui jembatan klien. Setelah terhubung, Nova memperlakukan alat-alat ini seperti integrasi eksternal lainnya: ia memutuskan kapan harus memanggil mereka, mengirim parameter yang diperlukan, dan memasukkan hasilnya ke dalam responsnya.
# Melaporkan kesalahan
Ada beberapa contoh di mana parameter yang dipilih oleh Amazon Nova dapat menyebabkan kesalahan eksternal. Ini dapat bermanfaat kemudian untuk mengkomunikasikan ini kembali ke Amazon Nova sehingga permintaan dapat dimodifikasi dan dicoba lagi. Untuk memberi tahu tentang kesalahan, tetap mengembalikan hasil alat tetapi ubah status untuk melaporkan kesalahan dan membagikan pesan pengecualian.
Berikut adalah contoh yang melaporkan pesan status kesalahan:
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occured on field: sample.field"}],
"status": "error"
}
}
]
}
```
## Referensi tambahan
1. [Gunakan alat untuk menyelesaikan respons model](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)
1. [Membangun agen AI dengan Amazon Nova](agents.md)
1. [Pemahaman teks mendorong praktik terbaik](prompting-text-understanding.md)
1. [Pemecahan masalah panggilan alat](prompting-tool-troubleshooting.md)