Tool dalam Simulasi

Banyak agent tidak hanya berbicara. Agent mencari sesuatu, mengirim permintaan ke sistem lain, atau menyimpan sesuatu. Run pengujian tidak boleh mengubah data sungguhan secara tidak sengaja, jadi Simulasi menentukan, untuk setiap pemanggilan tool, apa yang benar-benar terjadi. Dalam panduan ini Anda mempelajari apa itu pemanggilan tool, bagaimana Qlar menentukan apa yang terjadi padanya, apa arti setiap label hasil, dan cara meninjau serta mengubahnya untuk sebuah skenario. Waktu yang dibutuhkan sekitar lima belas menit.

Agent contohnya adalah Libraría, yang punya banyak tool. Agent Anda akan punya tool lain. Langkah-langkahnya sama. Jika Anda belum pernah menjalankan skenario, mulailah dari Simulasi Pertama Anda.

AI terlibat di setiap run: agent menulis jawabannya, memutuskan kapan memakai tool dan detail apa yang dikirim, dan AI menilai setiap kriteria. Semua ini bisa berbeda setiap kali, jadi skenario yang sama bisa memakai tool sedikit berbeda dari satu run ke run berikutnya. Anggap satu hasil sebagai contoh, bukan jaminan.

Apa itu pemanggilan tool?

Tool adalah sesuatu yang bisa dipakai agent Anda saat menjawab, selain pengetahuannya sendiri. Mencari sebuah buku, memeriksa tabel data, mencari dokumen, mengirim formulir, mengatur pengingat, bertanya kepada agent lain: masing-masing adalah sebuah tool. Ketika agent memutuskan memakai salah satunya di tengah jawaban, itulah pemanggilan tool.

Sebuah pemanggilan tool punya tiga bagian:

1. Panggilan. Agent memilih sebuah tool dan mengisi detail yang dibutuhkannya. Detail ini disebut argumen (arguments). Untuk pencarian buku (get_book), argumennya adalah ISBN buku itu, yaitu nomor katalognya.
2. Pekerjaan. Tool menjalankan tugasnya, biasanya dengan menghubungi sistem lain. Banyak tool menjangkau sistem itu lewat sebuah API, yaitu kumpulan alamat web yang disepakati, yang bisa diminta sebuah program untuk membaca atau mengubah data milik program lain.
3. Respons. Tool mengirim kembali sebuah jawaban, dan agent memakainya untuk menulis balasan. Respons sering ditulis dalam JSON, cara menulis data terstruktur dengan teks biasa, misalnya {"status": "on hold"}. Anda tidak perlu menulis JSON untuk memakai Simulasi. Editor mock menyediakan formulir untuk sebagian besar tool.

Risikonya ada di bagian 2. Panggilan yang hanya membaca data aman untuk diulang. Panggilan yang menulis data bisa membuat peminjaman, mengirim email, atau mengubah sebuah catatan, dan dalam pengujian Anda tidak menginginkannya. Itulah sebabnya Simulasi tidak sekadar meloloskan setiap panggilan.

Istilah penting

Sebelum memulai

• Anda memiliki peran Owner atau Contributor pada agent.
• Agent Anda punya setidaknya satu tool. Tanpa tool, tidak ada yang di halaman ini yang berlaku.
• Tool Mocks dan Tool Policy tampil di sidebar di bawah Simulation hanya jika fitur diaktifkan untuk CMS Anda. Jika Anda tidak melihatnya, tanyakan kepada orang yang mengelola CMS Anda.
• Untuk memakai Allow live… pada sebuah skenario, Anda harus menjadi Owner atau Admin organisasi. Semua hal lain di halaman ini bisa dilakukan setiap Owner dan Contributor agent, termasuk sakelar Run live di Tool Policy, yang berlaku untuk semua skenario.

Bagaimana pemanggilan tool diputuskan

Ketika agent memanggil sebuah tool selama run, Qlar mencari jawaban dalam urutan tetap. Aturan pertama yang punya jawaban menang, dan sisanya tidak ditanya.

1. Step mocks. Mock set yang dipasang pada step yang melakukan panggilan. Jika salah satu case-nya cocok dengan panggilan, responsnya dipakai.
2. Scenario mocks. Mock set yang dipasang pada seluruh skenario. Hanya ditanya jika tidak ada mock di step yang menjawab.
3. Scenario's Allow live. Skenario mengizinkan tool ini berjalan live, jadi panggilan dilakukan sungguhan.
4. This policy. Tool Policy agent: pengaturan yang membuat tool berjalan live atau tetap diblokir. Berlaku untuk setiap skenario agent.
5. Built-in default. Apa yang dilakukan tool ketika tidak ada aturan di atas yang berlaku.

Tiga hal mengikuti dari urutan ini.

• Mock selalu menang. Tool yang diatur berjalan live di Tool Policy tetap bisa di-mock pada skenario yang membutuhkan jawaban tetap.
• Mock set milik step diperiksa sebelum milik skenario. Step adalah tempat yang lebih spesifik, jadi didahulukan.
• Sebuah mock set boleh menjawab hanya sebagian panggilan. Jika tidak ada case-nya yang cocok dan set itu diatur untuk terus mencari, panggilan berlanjut ke set berikutnya, lalu ke aturan di bawahnya.

Default bawaan

Aturan terakhir bergantung pada jenis tool.

Karena default untuk kelompok ketiga ketat, run pertama pada agent dengan API sendiri sering menampilkan panggilan Blocked. Itu disengaja: jawaban yang aman adalah defaultnya sampai ada orang yang memutuskan lain.

Label hasil

Dua tempat menampilkan label hasil, dan keduanya memakai kata yang sedikit berbeda. Di sebuah hasil, label memberi tahu apa yang telah terjadi. Di sebuah skenario, panel Agent Tools memberi tahu apa yang akan terjadi.

Apa yang terjadi dalam sebuah run

Pada kartu step di sebuah hasil, Tool calls (n) mendaftar setiap panggilan. Setiap baris punya chip hasil dan chip sumber. Membaca Hasil menunjukkan letaknya.

Apa yang akan terjadi dalam sebuah skenario

Panel Agent Tools menampilkan ini sebelum Anda menjalankan.

Langkah 1: Lihat ringkasan Agent Tools

1. Di sidebar, buka Simulation lalu klik Scenarios.
2. Buka sebuah skenario, atau klik New Scenario untuk memulai yang baru.
3. Temukan Agent Tools di panel pengaturan di sisi kiri formulir. Pada layar sempit, bagian ini menjadi satu baris di bawah kartu informasi formulir, dan mengkliknya membuka lembar samping.

Di bawah Agent Tools Anda melihat bar berwarna dengan satu chip untuk setiap hasil yang berlaku, seperti Live 10, Simulated 3 atau Blocked 47 pada Libraría. Angka abu-abu di samping judul adalah jumlah tool yang dimiliki agent. Saat diciutkan, panel menampilkan satu baris, misalnya "1 will be blocked · 2 mocked · 1 live · 3 simulated". Jika tidak ada yang akan gagal, baris itu dimulai dengan "Nothing blocked".

Arti chip-nya:

Apa pun di bawah Blocked adalah hal pertama yang perlu ditangani. Bar dan hitungannya baru muncul setelah tool agent dan Tool Policy selesai dimuat. Sebelum itu, bagian ini hanya menampilkan "Loading tool catalog..." atau "Checking tool policy…", dan tombol Retry jika pemuatan gagal. Jika menampilkan "This agent has no tools with mockable policies." tidak ada yang perlu ditinjau.

Langkah 2: Tinjau semua tool

1. Di bawah Agent Tools, klik Review all tools. Anda juga bisa mengklik salah satu chip hasil untuk membuka panel yang sudah difilter ke hasil itu.
2. Panel What the agent’s tools will do terbuka. Subjudulnya menyebut agent Anda dan versi yang dipakai skenario, draft atau published version.
3. Gunakan tab di bagian atas untuk memilih cakupan. Whole scenario menampilkan apa yang didapat setiap step. Step 1, Step 2, dan seterusnya menampilkan apa yang didapat satu step itu. Pada tab step, mock set milik step itu diperiksa lebih dulu.
4. Baca baris di bawah tab, misalnya "50 action tools · 0 mocked · 47 will be blocked". Action tool adalah tool yang akan diblokir atau disimulasikan tanpa mock.
5. Klik All untuk melihat semua tool. Klik Needs attention · n untuk melihat hanya tool yang akan diblokir atau baru sebagian di-mock.
6. Ketik di Search tools… untuk mencari tool berdasarkan nama atau deskripsinya.
7. Tool dikelompokkan menurut asalnya: Custom API (API milik Anda sendiri), Plugins, MCP (tool dari server MCP), Other agents, A2A (agent yang dijalankan di tempat lain), dan Built-in. Sebuah judul bisa menambahkan nama grup API, misalnya Custom API · Finance dan Custom API · Library.

Panel terbuka seperti ini, dengan tombol All dan Needs attention diberi tanda.

Needs attention · n hanya menyisakan tool yang akan diblokir atau baru sebagian di-mock. Itulah daftar yang dikerjakan lebih dulu.

Setiap tool adalah satu baris dengan namanya, deskripsi singkat, chip hasil, dan satu baris yang menjelaskan alasannya. Misalnya, Blocked · Tool policy diikuti "Set to blocked in the tool policy.", Live · Tool policy diikuti "Set to run live in the tool policy.", dan Blocked · Not reviewed in the tool policy diikuti "Nobody has reviewed this tool in the tool policy yet, so calls are blocked." serta tautan Review in Tool Policy. Chip Draft only atau Published only tampil saat tool hanya ada di satu versi. Tool yang dimatikan di kedua versi menampilkan Disabled dan tidak bisa diubah di sini. Tautan Edit tool policy → di bagian atas membuka halaman Tool Policy di tab baru.

Langkah 3: Beri mock pada tool yang diblokir

Tool yang Blocked tidak boleh berjalan dalam pengujian, jadi step yang membutuhkannya gagal. Perbaikan yang aman adalah mock: jawaban yang sudah Anda tulis.

1. Di panel, temukan tool-nya. Pada tool yang akan diblokir, klik Mock it.
2. Editor mock set terbuka dengan tool itu sudah ditambahkan. Tambahkan sebuah case dan tulis respons yang Anda ingin diterima agent. Tool Mocks menunjukkan caranya.
3. Klik Apply. Set itu dipasang pada skenario, atau pada step jika Anda membuka panel di tab step.

Gambar menunjukkan tool yang diblokir dengan tombol Mock it diberi tanda. Di sebelahnya, Allow live… adalah pilihan lain, dibahas di langkah berikutnya.

Baris tool itu sekarang berbunyi Mocked · name, dan chip-nya di bar berpindah dari Blocked ke Mocked. Simpan skenario.

Jika Anda membuka panel di tab step, Mock it menambahkan mock set ke step itu. Jika tidak, mock set ditambahkan ke seluruh skenario.

Langkah 4: Izinkan tool berjalan live, hanya jika perlu

Kadang sebuah skenario harus membuktikan bahwa sistem sungguhan berfungsi, misalnya bahwa sistem perpustakaan Anda benar-benar menerima sebuah peminjaman dari create_loan. Untuk itu Anda bisa mengizinkan satu tool berjalan live dalam skenario ini.

1. Di panel, temukan tool-nya. Pada tool yang akan diblokir atau disimulasikan, klik Allow live….
2. Baca konfirmasinya. Isinya "Real data will change." Untuk tool eskalasi, ditambahkan bahwa supervisor akan diberi tahu. Untuk agent lain, ditambahkan bahwa agent itu dan tool-nya sendiri akan benar-benar berjalan. Jika tool di-mock untuk sebagian input, ditambahkan juga bahwa panggilan yang dijawab mock tetap di-mock dan semua panggilan lain berjalan sungguhan.
3. Konfirmasikan. Baris itu sekarang berbunyi Live, dan di bawahnya "Takes effect after you save".
4. Klik Save pada skenario. Run memakai skenario yang tersimpan, jadi Allow live yang belum Anda simpan tidak dipakai. Qlar meminta Anda menyimpan sebelum menjalankan.

Untuk membatalkannya, klik Remove pada baris yang sama, lalu simpan.

Gunakan seperlunya. Allow live melakukan panggilan sungguhan, dengan kredensial sungguhan, di setiap run skenario itu.

Langkah ini membahas kedua kemungkinan, karena yang Anda lihat bergantung pada peran Anda. Jika Anda bukan Owner atau Admin organisasi, Allow live… berwarna abu-abu dan tidak bisa dipakai. Gambar di halaman ini diambil dengan akun seperti itu, jadi konfirmasi pada butir 2 hanya dijelaskan dengan kata-kata.

Siapa yang bisa memakai Allow live…

Hanya Owner dan Admin organisasi yang bisa memakai Allow live… pada sebuah skenario. Bagi orang lain, tombolnya tetap terlihat tetapi berwarna abu-abu. Arahkan kursor ke sana untuk membaca "Only organisation Owners and Admins can allow a tool to run live", dan catatan gembok di bagian bawah panel mengulangnya.

Jika itu Anda, mintalah Owner atau Admin organisasi Anda untuk membuka skenario dan mengizinkan tool itu. Atau hindari kebutuhan itu: mock melakukan hal yang sama untuk pengujian, tanpa menyentuh sistem sungguhan, dan siapa pun dengan peran Owner atau Contributor pada agent bisa memakai Mock it.

Sakelar Run live di Tool Policy berbeda. Siapa pun dengan peran Owner atau Contributor pada agent bisa mengubahnya, dan sakelar itu berlaku untuk semua skenario agent, bukan hanya satu.

Langkah 5: Periksa hasil sebuah run

Setelah run, buka hasilnya dan lihat pemanggilan tool. Lihat Membaca Hasil untuk letaknya.

1. Buka tab Results dan klik run-nya.
2. Buka skenario dan sebuah step, lalu klik Tool calls (n).
3. Untuk setiap panggilan, bandingkan chip hasil dengan apa yang dijanjikan panel Agent Tools.

Setiap baris menampilkan kunci tool, misalnya custom:get_book untuk tool Custom API atau a2a:HelperDesk untuk agent A2A, lalu chip hasil, chip sumber, dan argumen yang dikirim agent. Satu baris di bawahnya menjelaskan apa yang terjadi. Header bagian menghitung hasilnya, misalnya Live 1 dan Blocked 1.

Pada step pertama ini, agent mencari sebuah buku dan menelusuri katalog. Kedua tool belum ditinjau di Tool Policy, jadi kedua panggilan Blocked. Chip hasil pertama diberi tanda.

Step berikutnya meminjamkan buku dengan create_loan. create_loan adalah salah satu API milik Anda sendiri (Custom API), jadi ia diblokir sampai seseorang meninjaunya di Tool Policy, baik ia membaca maupun menulis data.

Pada step terakhir, panggilan pertama Live karena Tool Policy mengizinkan tool itu berjalan live. Panggilan itu menampilkan peringatan "Live — may contain real data" dan satu baris berbunyi "Live call · Tool policy". Panggilan kedua menuju agent lain dan Blocked.

Pada panggilan Blocked Anda bisa mengklik Mock this call, dan pada panggilan Mocked atau Live Anda bisa mengklik Save as case, untuk mengubah panggilan itu menjadi mock untuk run berikutnya. Tool Mocks menjelaskan keduanya.

Periksa hasilnya

Anda berhasil jika Anda bisa menjawab ini:

• Untuk satu tool pada agent Anda, aturan mana yang menentukan apa yang terjadi: mock step, mock skenario, sebuah Allow live, Tool Policy, atau default bawaan?
• Tool mana dalam sebuah skenario yang akan Blocked jika Anda menjalankannya sekarang?
• Siapa di organisasi Anda yang bisa memakai Allow live… pada sebuah skenario?

Jika Anda melihat hal lain:

• Sebuah tool berbunyi Blocked · Not reviewed in the tool policy. Belum ada yang memutuskan tentang tool itu. Beri mock dengan Mock it, atau tinjau di Tool Policy.
• Panggilan yang sudah Anda mock masih menampilkan Default. Sebuah mock set menjawab dengan respons Otherwise-nya, karena tidak ada case yang cocok. Periksa kondisi case-nya.
• Panggilan yang sudah Anda mock masih menampilkan Blocked. Panggilan mungkin tidak cocok dengan case mana pun, dan set mungkin diatur untuk terus mencari. Periksa kartu Otherwise (every other call) milik tool itu.
• Sebuah panggilan menampilkan Live dan Anda tidak mengharapkannya. Lihat chip sumbernya. Tool policy berarti Tool Policy mengizinkan tool berjalan live. Allowed live in this scenario berarti skenario ini mengizinkannya. Hapus pengaturan itu, atau tambahkan mock pada skenario.
• Bagian Agent Tools hanya menampilkan pemberitahuan. Tool agent atau Tool Policy masih dimuat, atau pemuatan gagal. Bagian ini menampilkan "Failed to load the tool catalog. The rest of the form is still usable." atau "The agent's tool policy couldn't be loaded, so what each tool will do can't be shown. Runs still follow the saved policy." Klik Retry.

Langkah berikutnya

• Berikutnya dalam bagian ini: Tool Mocks menunjukkan cara menulis jawaban pura-pura.
• Menetapkan default untuk seluruh agent: Tool Policy.
• Sebagai bagian dari membangun Atlas: Menguji Tool dengan Aman Memakai Mock.
• Referensi per field: Scenarios, Results dan Tool Policy.