Panggil alat dengan Converse API

Untuk membiarkan model menggunakan alat untuk menyelesaikan respons pesan, Anda mengirim pesan dan definisi untuk satu atau beberapa alat ke model. Jika model menentukan bahwa salah satu alat dapat membantu menghasilkan respons, ia mengembalikan permintaan bagi Anda untuk menggunakan alat dan mengirim hasil alat kembali ke model. Model kemudian menggunakan hasil untuk menghasilkan respons terhadap pesan asli.

Langkah-langkah berikut menunjukkan cara menggunakan alat dengan ConverseAPI. Untuk kode sampel, lihat Contoh penggunaan API alat Converse.

Langkah 1: Kirim pesan dan definisi alat

Untuk mengirim pesan dan definisi alat, Anda menggunakan operasi Converse atau ConverseStream(untuk respons streaming).

catatan

Meta memiliki rekomendasi khusus untuk membuat prompt yang menggunakan alat Llama 3.1 (atau yang lebih baru) model. Untuk informasi selengkapnya, lihat pemanggilan alat JSON berbasis di Meta dokumentasi.

Definisi alat adalah JSON skema yang Anda teruskan dalam parameter permintaan toolConfig (ToolConfiguration) ke Converse operasi. Untuk informasi tentang skema, lihat JSONskema. Berikut ini adalah contoh skema untuk alat yang mendapatkan lagu paling populer diputar di stasiun radio.

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

Dalam permintaan yang sama, Anda juga meneruskan pesan pengguna di parameter permintaan messages (Pesan).

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

Jika Anda menggunakan Anthropic Claude 3 model, Anda dapat memaksa penggunaan alat dengan menentukan toolChoice (ToolChoice) bidang dalam parameter toolConfig permintaan. Memaksa penggunaan alat berguna untuk menguji alat Anda selama pengembangan. Contoh berikut menunjukkan cara memaksa penggunaan alat yang disebut top_song.

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

Untuk informasi tentang parameter lain yang dapat Anda lewati, lihatLakukan percakapan dengan Converse.

Langkah 2: Dapatkan permintaan alat dari model

Saat Anda menjalankan Converse operasi dengan pesan dan definisi alat, model menggunakan definisi alat untuk menentukan apakah alat tersebut diperlukan untuk menjawab pesan. Misalnya, jika pengguna aplikasi obrolan Anda mengirim pesan Lagu apa yang paling populerWZPZ? , model mencocokkan pesan dengan skema dalam definisi alat top_song dan menentukan bahwa alat tersebut dapat membantu menghasilkan respons.

Ketika model memutuskan bahwa ia membutuhkan alat untuk menghasilkan respons, model menetapkan bidang stopReason respons ketool_use. Respons juga mengidentifikasi alat (top_song) yang model ingin Anda jalankan dan stasiun radio (WZPZ) yang ingin Anda kueri dengan alat tersebut. Informasi tentang alat yang diminta ada dalam pesan yang dikembalikan model di bidang output (ConverseOutput). Secara khusus, bidang toolUse (ToolUseBlock). Anda menggunakan toolUseId bidang untuk mengidentifikasi permintaan alat dalam panggilan selanjutnya.

Contoh berikut menunjukkan respons dari Converse saat Anda meneruskan pesan yang dibahas diLangkah 1: Kirim pesan dan definisi alat.

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

Langkah 3: Buat permintaan alat untuk model

Dari toolUse bidang dalam respons model, gunakan name bidang untuk mengidentifikasi nama alat. Kemudian panggil implementasi alat Anda dan berikan parameter input dari input lapangan.

Selanjutnya, buat pesan pengguna yang menyertakan blok konten toolResult (ToolResultBlock). Di blok konten, sertakan respons dari alat dan ID untuk permintaan alat yang Anda dapatkan di langkah sebelumnya.

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

Jika terjadi kesalahan pada alat, seperti permintaan untuk stasiun radio yang tidak ada, Anda dapat mengirim informasi kesalahan ke model di toolResult lapangan. Untuk menunjukkan kesalahan, tentukan error di status bidang. Contoh kesalahan berikut adalah ketika alat tidak dapat menemukan stasiun radio.

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

Langkah 4: Dapatkan respons model

Lanjutkan percakapan dengan model dengan menyertakan pesan pengguna yang Anda buat di langkah sebelumnya dalam panggilan keConverse. Model kemudian menghasilkan respons yang menjawab pesan asli (Lagu apa yang paling populerWZPZ? ) dengan informasi yang Anda berikan di toolResult bidang pesan.

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