Tool Mocks

Tool adalah sesuatu yang dipakai agent Anda saat menjawab, seperti mencari sebuah buku atau mengirim permintaan ke sistem lain, dan setiap kali itu terjadi, itulah pemanggilan tool. Mock adalah jawaban yang sudah Anda tulis untuk sebuah tool. Ketika sebuah skenario berjalan dan agent memanggil tool itu, Qlar mengirim kembali jawaban Anda alih-alih menghubungi sistem sungguhan, sehingga pengujian memberi hasil yang sama setiap kali dan tidak mengubah apa pun yang sungguhan. Dalam panduan ini Anda mempelajari cara membuat mock set, cara memasangnya pada sebuah skenario atau pada satu step, cara mengubah panggilan yang Anda lihat di sebuah hasil menjadi mock, dan cara menjaga set Anda tetap rapi. Waktu yang dibutuhkan sekitar dua puluh menit.

Agent contohnya adalah Libraría, yang punya banyak tool. Kita memakai dua tool-nya: get_book, yang mencari sebuah buku berdasarkan ISBN-nya (nomor katalognya), dan create_loan, yang meminjamkan sebuah buku kepada anggota. Agent Anda punya tool dan nama lain. Langkah-langkahnya sama. Tool dalam Simulasi menjelaskan pemanggilan tool dengan lebih rinci.

AI bisa membantu di halaman ini: AI bisa menyusun draf respons untuk Anda, dan pemakaian tool oleh agent dalam sebuah run dihasilkan oleh AI. Draf respons dan sebuah run bisa berbeda setiap kali, jadi periksa apa yang Anda dapat sebelum Anda mengandalkannya.

Istilah penting

Sebelum memulai

• Anda memiliki peran Owner atau Contributor pada agent.
• Agent Anda punya setidaknya satu tool. Mock set hanya bisa me-mock tool yang dimiliki agent.
• Tool Mocks tampil di sidebar di bawah Simulation hanya jika fitur diaktifkan untuk CMS Anda.
• Anda punya skenario untuk dipasangi set itu, atau Anda akan membuatnya lewat Simulasi Pertama Anda.

Langkah 1: Pilih antara library set dan private set

Setiap mock set adalah salah satu dari dua jenis.

Mulailah dengan set private jika jawabannya khusus untuk satu skenario. Buat set library jika beberapa skenario butuh sistem pura-pura yang sama, misalnya "Book unavailable". Anda bisa mengubah yang satu menjadi yang lain nanti: Save to library mengubah private set menjadi library set, dan Make a private copy menyalin library set ke satu skenario sehingga Anda bisa mengubahnya tanpa memengaruhi yang lain.

Langkah 2: Buat mock set

1. Di sidebar, buka Simulation dan klik Tool Mocks.
2. Klik New Mock Set. Pada agent tanpa set, halaman kosongnya menampilkan No Mock Sets Yet dan tombol yang sama.

Layar Tool Mocks mendaftar library set Anda sebagai kartu. Setiap kartu menampilkan nama set, jumlah tool dan case-nya, nama tool-nya, dan "Used in n scenarios".

3. Ketik Name, misalnya "Book lookup: happy path". Nama wajib diisi.
4. Secara opsional, ketik Description untuk menjelaskan kegunaan set itu.

Editornya adalah halaman berjudul New Mock Set, dengan chip Library. Di sebelah kiri, Tools in this set menampilkan "No tools in this set yet." dan sisi kanan menampilkan "Select a tool to edit its mocks". Tombol Add tool, yang diberi tanda di bawah, adalah tujuan Anda berikutnya.

5. Klik Add tool. Daftar yang bisa dicari terbuka. Ketik di Search tools… dan klik tool yang Anda inginkan. Tool dikelompokkan menurut asalnya: Custom API (API milik Anda sendiri, yaitu cara bagi program untuk saling berbicara), Plugins, MCP (tool dari server MCP, layanan yang menyediakan tool bagi agent AI dengan cara standar), Other agents, A2A (agent yang dijalankan di tempat lain dan diajak bicara agent Anda lewat standar A2A), dan Built-in. Di samping setiap tool Anda melihat apa yang terjadi padanya secara default jika tidak di-mock: Blocked unless mocked, Runs live unless mocked, atau Simulated success. Tool yang sudah ada di set menampilkan Already in this set.

Sebuah judul bisa memuat nama grup API, misalnya CUSTOM API · LIBRARY. Setiap baris menampilkan metode HTTP tool itu, misalnya GET untuk tool yang membaca data atau POST untuk tool yang mengirim data. Label di sebelah kanan adalah default bawaan tool. Tool Policy bisa mengubah apa yang sungguh terjadi, jadi periksa panel Agent Tools di sebuah skenario untuk hasil akhirnya.

Tool itu muncul di bawah Tools in this set di sebelah kiri, dan detailnya terbuka di sebelah kanan. Di bagian atas Anda melihat deskripsinya dan Inputs-nya, satu chip untuk setiap detail yang dikirim agent bersama panggilan, dengan jenis nilai yang diterimanya, misalnya "text" atau "number", dan tanda bintang jika wajib. Anda akan memakai input ini dalam kondisi. Pada tool Custom API Anda mungkin juga melihat input bernama qlarToolsActionDescription. Qlar memakainya secara internal, jadi Anda bisa mengabaikannya.

Anda bisa menambahkan lebih banyak tool ke set yang sama, hingga 50. Hapus sebuah tool dari set dengan ikon tempat sampah di samping namanya.

Langkah 3: Tulis sebuah case

Sebuah case berkata: ketika agent memanggil tool ini dengan detail ini, jawab dengan ini.

1. Di bawah tool, klik Add case. Kartu case terbuka. Ketik label di Label this case (optional), misalnya "Known book".
2. Di bawah When all of these match, klik Add condition.

Sebuah petunjuk abu-abu di samping Add condition mendaftar input yang belum tercakup kondisi mana pun, misalnya "2 parameters aren't listed, so any value matches". Input tanpa kondisi menerima nilai apa saja.

3. Pilih input di dropdown pertama, sebuah perbandingan di dropdown kedua, dan ketik nilainya di yang ketiga. Contoh: isbn, is, 9780000000004.

Dropdown kedua mendaftar perbandingannya. Kolom nilai berbunyi Optional sampai Anda mengetik di dalamnya.

Kondisi yang sudah jadi berbunyi isbn is 9780000000004.

4. Di bawah Respond with, tulis jawabannya. Langkah 4 menunjukkan caranya.
5. Tambahkan lebih banyak case untuk situasi lain, misalnya "Unknown ISBN".

Case diperiksa dari yang pertama sampai yang terakhir, dan case pertama yang cocok yang menjawab. Seret gagang di sebelah kiri sebuah case untuk mengubah urutan. Case tanpa kondisi cocok dengan setiap panggilan, jadi setiap case di bawahnya tidak akan pernah tercapai. Letakkan case yang paling spesifik lebih dulu. Sebuah case bisa digandakan atau dihapus dengan ikon di kartunya yang terbuka, dan panah di sebelah kanannya menciutkannya.

Kondisi

Sebuah kondisi terdiri dari tiga bagian: sebuah input, sebuah perbandingan, dan sebuah nilai. Perbandingan yang bisa Anda pilih bergantung pada jenis input.

Yang perlu diketahui:

• Perbandingan teks mengabaikan huruf besar dan kecil. Klik tombol Aa pada kondisi untuk mengaktifkan Match case (on) dan membandingkan secara persis.
• Sebuah case hanya menjawab jika semua kondisinya terpenuhi. Input tanpa kondisi boleh bernilai apa pun.
• Hapus sebuah kondisi dengan × di ujungnya.
• Jika sebuah kondisi tampil dengan sorotan, input yang disebutnya sudah bukan input tool itu lagi, mungkin karena tool-nya berubah. Perbaiki atau hapus kondisi itu, atau kondisi itu tidak akan cocok.
• Di bawah Advanced — Match raw arguments Anda bisa menambahkan pencocokan tambahan pada detail mentah panggilan, ditulis sebagai JSON, cara menulis data terstruktur dengan teks biasa, seperti {"isbn": "9780000000004"}. Sebagian besar case tidak membutuhkannya.

Langkah 4: Tulis responsnya

Respons adalah apa yang diterima agent. Kontrolnya ada di samping Respond with.

Case baru pada tool Custom API dimulai dengan daftar JSON kosong, [], dan status 200 OK. Gantilah dengan jawaban Anda. Suggest diberi tanda pada gambar.

Use a real response dan Fetch a sample melakukan satu panggilan sungguhan ke sistem sungguhan. Pakai hanya pada tool yang aman dipanggil.

Berikut case "Known book" yang sudah jadi untuk get_book: satu kondisi dan respons JSON yang memberikan detail buku.

Form menyesuaikan diri dengan jenis tool, jadi Anda jarang perlu mengetik JSON sendiri.

Nilai yang ditandai terisi otomatis, seperti ID atau waktu, berasal dari panggilan itu sendiri dan tidak bisa diketik.

Langkah 5: Tentukan apa yang terjadi pada setiap panggilan lain

Di bagian bawah setiap tool, kartu Otherwise (every other call) menentukan apa yang terjadi pada panggilan yang tidak cocok dengan case mana pun. Secara default kartu ini berisi sebuah respons, sama seperti sebuah case, jadi setiap panggilan mendapat jawaban. Klik Advanced untuk memilih antara dua opsi:

Gambar menunjukkan kartu Otherwise (every other call) dengan Advanced terbuka (diberi tanda). Respond with a default terpilih, dan responsnya adalah daftar kosong [] yang menjadi awal tool Custom API.

Pilih Respond with a default jika set harus sepenuhnya menggantikan tool dalam sebuah skenario. Pilih Keep looking jika set hanya mencakup beberapa panggilan khusus, dan sisanya harus berperilaku seperti biasa. Tool yang setnya diatur Keep looking menampilkan Mocked for some inputs · otherwise … di panel Agent Tools, sehingga Anda bisa melihat apa yang akan dilakukan sisanya.

Klik Save di bagian atas. Anda melihat "Mock set created successfully" atau "Mock set saved successfully". Jika orang lain mengubah set itu pada saat yang sama, Qlar menampilkan "Someone else changed this set. Reload?" dan Anda mengklik Reload.

Setelah disimpan, set itu tampil di layar Tool Mocks sebagai kartu, di sini "1 tool · 1 case" dengan tool get_book dan "Used in 0 scenarios".

Langkah 6: Pasang set pada sebuah skenario

Mock set tidak melakukan apa-apa sampai sebuah skenario memakainya.

1. Buka sebuah skenario, atau klik New Scenario.
2. Di panel pengaturan di sebelah kiri, buka Tool Mocks. Panel ini menampilkan Mock sets attached (n). dengan catatan "Used by every step. A step’s own mock sets are checked before these." Pada layar sempit, bagian ini menjadi satu baris di bawah kartu informasi.
3. Klik Add Mock Set. Sebuah menu terbuka dengan dua pilihan.
   • From library… ("Reuse a shared set."). Panel Add from library terbuka. Ketik di Search mock sets or tools…, centang set yang Anda inginkan, lalu klik tombol di bagian bawah. Tombol itu berbunyi Add 1 mock set untuk satu set, Add 2 mock sets untuk dua set, dan seterusnya.
   • Create new ("Private to this scenario."). Editor terbuka di panel samping berjudul Create mock set. Susun seperti pada langkah 2 sampai 5, lalu klik Apply.
4. Klik Save pada skenario.

Menu Add Mock Set punya dua pilihan:

Panel Add from library dengan satu set dicentang:

Private set baru di panel Create mock set, di sini set bernama "Loan answers" yang berisi tool create_loan:

Setiap set yang terpasang adalah satu baris dengan ikon buku atau gembok, namanya, jumlah seperti "2 tools · 5 cases", dan nama tool-nya. Pakai ikon pensil untuk mengeditnya, dan menu ⋮ untuk Make a private copy, Save to library, atau Remove. Save to library berwarna abu-abu sampai Anda menyimpan skenario. Remove melepas set dari skenario ini. Library set tetap ada di library. Private set hanya hidup di skenario ini, jadi hilang setelah Anda menyimpan, kecuali Anda memilih Save to library lebih dulu.

Pada gambar, ikon buku (diberi tanda) berarti library set dan ikon gembok (diberi tanda) berarti private set. Private set yang baru Anda buat menampilkan chip Unsaved changes sampai Anda menyimpan skenario.

Langkah 7: Pasang set pada satu step

Kadang hanya satu step yang butuh jawaban pura-pura, misalnya step ketiga, ketika pengguna meminta meminjam buku yang tidak punya salinan tersisa.

1. Di formulir skenario, buka kartu step dan temukan bagian Tool Mocks (n)-nya.
2. Klik Add Mock Set dan pilih From library… atau Create new, seperti pada langkah 6.
3. Satu baris di bawah judul menjelaskan apa yang sekarang dilakukan step ini, misalnya "Calls this step’s 1 set doesn’t answer fall back to the scenario’s 2 sets." jika step punya set sendiri, atau "This step uses the scenario’s 2 sets." jika tidak punya. Tautan What will each tool do in this step? membuka panel Agent Tools pada step ini.

Judulnya berbunyi Tool Mocks (0) selama step belum punya set sendiri, seperti di sini:

Set mana yang menjawab lebih dulu

Untuk satu panggilan, Qlar memeriksa dengan urutan ini:

1. Mock set milik step itu sendiri, dari atas daftar ke bawah.
2. Lalu mock set milik skenario, dari atas ke bawah.
3. Lalu, jika tidak ada yang menjawab, Allow live, Tool Policy, dan default bawaan, seperti di Tool dalam Simulasi.

Mock set milik step itu sendiri diperiksa lebih dulu. Ketika dua set dalam daftar yang sama me-mock tool yang sama, sebuah nomor dan gagang seret muncul di setiap baris, dan sebuah pemberitahuan menyebut set mana yang menjawab lebih dulu, misalnya "Both sets mock get_book. 'Book lookup: happy path' is higher in the list, so it answers first. Drag to change the order." Seret sebuah baris untuk mengubah urutan.

Ingat bahwa set yang diatur Keep looking meneruskan panggilan ke set berikutnya. Begitulah cara set kecil milik step bisa berada di atas set skenario yang lebih besar.

Langkah 8: Buat mock dari sebuah hasil

Mock yang paling mudah ditulis adalah yang untuk panggilan yang baru Anda lihat. Setelah run, buka hasilnya dan temukan panggilan itu di bawah Tool calls (n). Membaca Hasil menunjukkan letaknya.

1. Untuk panggilan yang Blocked, klik Mock this call. Untuk panggilan yang Mocked atau Live, klik Save as case.

Pada gambar ini, panggilan yang Mocked punya Save as case (diberi tanda). Baris di bawah panggilan menyebut case yang menjawab: id-nya, sebuah kode panjang, lalu labelnya, set-nya, dan statusnya.

2. Sebuah menu menanyakan ke mana mock itu harus pergi.
   • New private set — this step: "Only used when this exact step runs."
   • New private set — this scenario: "Used by every step in this scenario."
   • Existing set…: "Pick a set once the scenario opens." Panel Add this case to a mock set lalu mendaftar set yang terpasang pada step dan pada skenario. Pilih satu, dan case ditambahkan ke dalamnya.

Menunya terlihat seperti ini:

3. Skenario terbuka dengan editor mock yang sudah terisi. Kondisinya disalin dari detail yang dikirim agent, sebagai pengujian "is". Untuk panggilan Blocked respons kosong dan Anda yang menulisnya. Untuk panggilan Mocked atau Live respons disalin dari apa yang dikembalikan.
4. Periksa respons, klik Apply, dan simpan skenario.

Dua peringatan bisa muncul:

• Respons Live mungkin berisi data sungguhan, jadi Qlar bertanya "This call ran live and may contain real data. Saving it as a case stores that response as the mock. Continue?" sebelum menyalinnya.
• Jika respons terlalu besar untuk disalin, Qlar menyatakannya dan Anda mengisinya sendiri.

Panggilan yang Blocked punya Mock this call di tempat yang sama, diberi tanda di sini:

Langkah 9: Lihat di mana library set dipakai, dan hapus

1. Di Simulation → Tool Mocks, kartu mock set menampilkan berapa skenario yang memakainya, misalnya "Used in 3 scenarios". Di List View, kolomnya adalah Name, Tools · cases, Used in, dan Updated.
2. Buka sebuah set dan klik Used in n scenarios untuk melihat skenario, dan step, yang memakainya.

Sebuah dialog berjudul Used in menampilkan "Attached in 1 place:" dan mendaftar setiap skenario, dengan "Scenario level" atau "Step n". Klik Close jika sudah selesai.

3. Untuk menghapus sebuah set, buka menu ⋮-nya dan pilih Delete, lalu konfirmasikan.

Jika sebuah set masih terpasang pada skenario, Qlar tidak menghapusnya diam-diam. Dialog This mock set is in use mendaftar di mana saja, masing-masing sebagai skenario dengan "Step n" atau "Scenario level". Tombol konfirmasinya, Remove from n scenarios and delete, melepas set di semua tempat lalu menghapusnya. Skenario-skenario itu kemudian kembali ke aturan berikutnya untuk tool tersebut, dan bisa menampilkan Blocked. Menu itu juga punya Duplicate, yang membuat salinan sebuah set.

Mengedit library set dari dalam sebuah skenario mengubahnya untuk semua orang. Panel menampilkan "Library set, used in n scenarios. Saving changes all of them." dengan tautan Make a private copy instead.

Periksa hasilnya

Jalankan skenario dan buka hasilnya. Lihat Menjalankan Simulasi jika Anda butuh langkah-langkahnya.

Anda berhasil jika:

• Panggilan ke tool menampilkan Mocked dengan chip sumber Step atau Scenario.
• Penjelasan di bawahnya menyebut case dan set Anda, misalnya "Case a90aced3-6289-4444-9e79-1dc464fae31b 'Known book' · Book lookup: happy path → 200". Kode panjang itu adalah id case.
• Jawaban agent memakai informasi dalam respons Anda.

Jika Anda melihat hal lain:

• Panggilan menampilkan Default. Tidak ada case yang cocok, jadi respons Otherwise yang menjawab. Periksa kondisinya.
• Panggilan masih menampilkan Blocked. Set belum dipasang pada skenario ini, Anda belum menyimpan skenario, atau panggilan tidak cocok dengan case mana pun sementara set diatur Keep looking. Buka Agent Tools dan Review all tools untuk melihat apa yang akan dilakukan tool itu.
• Case yang berbeda yang menjawab. Case atau set yang lebih awal cocok lebih dulu. Ubah urutannya, atau buat yang lebih awal lebih spesifik.
• Add tool tidak menampilkan tool. Pemilih menampilkan "This agent has no tools in its catalog." jika agent tidak punya tool, atau "Failed to load the tool catalog. Close and reopen Add tool to retry." jika pemuatan gagal. Pemilih mendaftar tool draft dan agent yang dipublikasikan sekaligus.

Praktik yang baik

• Beri nama set menurut situasi yang dibuatnya, seperti "Book unavailable", bukan menurut tool.
• Tulis case yang paling spesifik lebih dulu dan case yang umum terakhir.
• Batasi setiap case pada satu gagasan. Beberapa case kecil lebih mudah diperbaiki daripada satu case panjang.
• Cakup juga kegagalan. Case error menunjukkan apakah agent Anda mengatakan sesuatu yang masuk akal ketika sebuah tool sedang bermasalah.
• Pakai bentuk respons yang nyata. Salin satu dari Use a real response atau Fetch a sample pada tool yang aman, agar mock Anda terlihat seperti aslinya.
• Pakai library set untuk jawaban yang dipakai banyak skenario, dan private set untuk kasus sekali pakai.
• Mock hanya mengubah simulasi. Mock tidak mengubah agent live Anda, jadi tidak ada yang perlu dipublikasikan.

Langkah berikutnya

• Sebelumnya dalam bagian ini: Tool dalam Simulasi.
• Berikutnya dalam bagian ini: Tool Policy menetapkan apa yang dilakukan setiap tool ketika tidak ada mock yang menjawab.
• Sebagai bagian dari membangun Atlas: Menguji Tool dengan Aman Memakai Mock.
• Referensi per field: Tool Mocks dan Scenarios.