Menguji Tool dengan Aman Memakai Mock

Begitu agent Anda memanggil tool (API Anda sendiri, MCP server, agent lain, atau plugin), pengujian menjadi lebih sulit: satu test run bisa membaca data live yang berubah setiap hari, menulis ke sistem sungguhan, atau gagal karena sebuah layanan sedang down. Mock mengatasi hal itu. Di langkah ini Anda menulis jawaban terskrip untuk tool Anda, memasangnya ke conversation simulation, lalu menjalankannya, sehingga setiap run mendapatkan hasil tool yang sama dan dapat diprediksi tanpa menyentuh apa pun yang nyata.

Dalam tutorial ini Anda menguji cara Atlas, asisten operasional Kirana Group, melaporkan status proyek. Atlas mencari data proyek dengan Custom API get_project_status dari Menghubungkan API Anda. Data proyek sungguhan berubah seiring pekerjaan berjalan, jadi Anda menguncinya dengan sebuah mock set: KG-2041 selalu berstatus On hold di tahap CFO, dan semua kode lain mengembalikan 404 Not Found. Lalu Anda menjalankan simulasi dua step terhadap mock set itu.

Sebelum memulai

• Agent Anda memiliki setidaknya satu tool: Menghubungkan API Anda, Menghubungkan MCP Server, Bekerja dengan Agent Lain, atau plugin dari Menggunakan Plugin. Untuk mengikuti tutorial ini, Atlas memiliki API get_project_status.
• Agent sudah di-publish. Simulasi berjalan terhadap versi yang sudah di-publish, dan editor mock hanya menawarkan tool dari versi tersebut. Lihat Preview dan Publish Perubahan.
• Anda memahami dasar conversation simulation (step, expected response, criteria). Jika belum, baca dulu Otomasi Pengujian dan Merancang Skenario.
• Item Mocks muncul di bawah Simulation pada sidebar agent. Jika tidak terlihat, fitur Mocks belum diaktifkan di environment Anda.

Mengapa memakai mock

Selama simulasi, setiap pemanggilan tool melewati sebuah gerbang yang menentukan apa yang terjadi padanya. Tanpa mock, setiap jenis tool punya perilaku default yang tetap:

Jadi tanpa mock, skenario yang bergantung pada Projects API milik Atlas tidak akan pernah lolos, dan skenario yang membaca tabel live bisa lolos hari ini tetapi gagal besok. Mock memberi tool sebuah jawaban terskrip sebagai gantinya. Dengan begitu Anda dapat:

• Menguji tanpa menyentuh sistem atau data sungguhan. Tidak ada data proyek sungguhan, tidak ada penulisan ke sistem production, tidak ada pemanggilan ke API berbayar.
• Mendapatkan hasil yang sama di setiap run, sehingga run yang gagal berarti agent-nya yang berubah, bukan datanya.
• Menguji jalur yang sulit dengan sengaja: hasil kosong, "not found", error 500, timeout, proyek yang sedang ditahan. Kondisi seperti ini sulit dipicu dengan layanan sungguhan.

Istilah penting

Langkah 1: Membuat mock set

1. Di CMS, buka Simulation → Mocks pada sidebar agent. Halamannya berjudul Tool Mocks.

2. Klik New Mock Set.

3. Isi set-nya:

   Field	Nilai untuk Atlas
   Name (wajib, maksimal 120 karakter)	Projects API: KG-2041 on hold
   Description	get_project_status returns a fixed "On hold" answer for KG-2041 and 404 for any other code.

Chip Library di samping judul berarti set ini dibagikan: Anda dapat memasangnya ke conversation simulation mana pun milik agent ini. Used in 0 conversations berubah setelah Anda memasangnya di Langkah 6. Duplicate membuat salinan seluruh set.

Langkah 2: Menambahkan tool yang ingin di-mock

1. Di bawah Tools in this set, klik Add tool.
2. Cari get_project_status lalu klik. Daftar ini menampilkan tool dari agent yang sudah di-publish, dikelompokkan menurut sumbernya (Custom API, MCP, Plugins, Built-in). Setiap entri menunjukkan apa yang dilakukan tool terhadap data dan apa yang akan dilakukannya dalam simulasi jika tidak di-mock. Misalnya, pencarian escalate menampilkan tool bawaan escalate_conversation dengan label Writes data dan Simulated success. Catatan di bagian bawah mengingatkan bahwa ini adalah tool dari Atlas yang sudah di-publish, versi yang dipakai simulasi.

Kartu tool yang dipilih menampilkan tipenya (Custom API, GET), deskripsinya, dan Inputs-nya (argumen yang diisi AI saat memanggil tool; untuk get_project_status argumennya projectCode). Anda dapat menambahkan beberapa tool ke satu set; pilih tool di daftar sebelah kiri untuk mengedit case-nya.

Jika suatu saat tool dihapus dari agent yang sudah di-publish, set akan menampilkan Tool not found in the published agent. Gunakan Re-bind to… untuk memindahkan case-nya ke tool lain.

Langkah 3: Menambahkan case dengan condition

1. Klik Add case. Beri label agar mudah dikenali nanti: KG-2041 is on hold.
2. Di bawah When all of these match, klik Add condition. Pilih argumen projectCode, perbandingan is, lalu ketik KG-2041. Field ini menampilkan deskripsi argumen dari API ("Kirana project code in the form KG-0000, for example KG-2041. Use upper case.") untuk membantu Anda mengetik nilai yang valid.
3. Tambahkan condition lain bila perlu. Case hanya menjawab jika setiap condition terpenuhi. Argumen yang tidak Anda cantumkan boleh bernilai apa saja.

Perbandingan yang bisa dipilih bergantung pada tipe argumen:

Tips:

• Perbandingan teks mengabaikan huruf besar dan kecil, kecuali Anda mengaktifkan Aa (match case) pada condition tersebut. Jadi kg-2041 juga cocok dengan case ini.
• is one of menerima daftar yang dipisahkan koma; is between menerima nilai minimum dan maksimum.
• matches pattern memakai regular expression.
• Case tanpa condition cocok dengan semua pemanggilan. Letakkan di urutan terakhir, karena case diperiksa dari atas ke bawah dan case "tangkap semua" akan menutupi case di bawahnya.
• Untuk input yang tidak biasa, buka Advanced — Match raw arguments dan tempelkan potongan JSON yang harus terkandung dalam argumen pemanggilan. Ini diperiksa sebagai tambahan dari condition.

Langkah 4: Menulis respons

Di bawah Respond with, tulis apa yang dikembalikan tool untuk case ini. Untuk Atlas, biarkan status 200 OK, pilih JSON, lalu tempelkan:

{
  "projectCode": "KG-2041",
  "name": "Surabaya warehouse expansion",
  "status": "On hold",
  "percentComplete": 62,
  "approval": {
    "stage": "CFO",
    "nextApprover": null
  },
  "latestUpdate": "Paused by the CFO until the revised steel quotation is approved."
}

Editornya menyesuaikan dengan tool:

• Untuk Custom API, pilih HTTP status di field samping Respond with (default 200 OK). Kode error di rentang 5xx sampai ke agent sebagai hasil kosong, sama seperti API sungguhan yang gagal.
• Beralih antara JSON dan Text untuk body. Beberapa tool juga menawarkan Form yang sesuai dengan output tool (misalnya baris dan kolom untuk query tabel), dengan View as JSON untuk body mentahnya.
• Success dan Error membuka template siap pakai, seperti list kosong, "Not found (404)", "Unauthorized (401)", "Rate limited (429)", "Service down or timed out" untuk Custom API, atau "Query fails" dan "No rows found" untuk query tabel.
• Untuk tool MCP, pilih Content atau MCP error. Untuk agent lain, tulis teks balasannya.
• Suggest meminta AI membuat draf respons untuk case tersebut. Format merapikan JSON.
• Use a real response memanggil tool sungguhan satu kali agar Anda bisa menyalin bentuk datanya. Tombol ini hanya tersedia untuk tool yang hanya membaca data, seperti Custom API yang memakai GET; untuk tool lain tombol ini terkunci karena memanggilnya bisa membuat data sungguhan.

Body respons bisa berukuran hingga 64 KB.

Langkah 5: Menentukan nasib pemanggilan lainnya

Di bawah daftar case, kotak Otherwise (every other call) menentukan jawaban tool ketika tidak ada case yang cocok. Untuk Atlas, semua kode proyek lain harus terlihat tidak dikenal:

1. Klik Error dan pilih template not found, atau atur sendiri status menjadi 404 Not Found.
2. Pastikan body-nya {"error":"Not found"} dalam mode JSON.
3. Buka Advanced dan biarkan Respond with a default terpilih.

Dua opsi di bawah Advanced:

• Respond with a default: pemanggilan mendapat respons yang Anda tulis di kotak ini (di sini: 404 dengan {"error":"Not found"}).
• Keep looking: pemanggilan berlanjut ke mock set berikutnya, dan jika tidak ada yang menjawab, ke perilaku default tool sesuai tabel di Mengapa memakai mock. Di daftar tool, tool seperti ini ditandai "Keeps looking".

Klik Save. Set tersebut kini muncul di halaman Tool Mocks beserta deskripsinya, 1 tool · 1 case, chip tool get_project_status, dan berapa conversation yang memakainya.

Langkah 6: Memasang mock set ke conversation simulation

1. Buka Simulation → Scenarios dan buat conversation simulation dengan dua step. Lihat Merancang Skenario untuk detailnya.
   • Step 1, pesan pengguna: What is the status of project KG-2041?
   • Step 2, pesan pengguna: And project KG-9999?
2. Tambahkan expected response, lalu klik Suggest All Criteria agar AI menulis evaluation criteria untuk setiap step. Tinjau hasilnya dan hapus yang tidak Anda inginkan.
3. Di kartu Tool mocks, klik Add mock set:
   • From library… memasang set bersama. Pilih Projects API: KG-2041 on hold.
   • Create new membuat set Private yang hanya dimiliki conversation ini.
4. Klik Save. CMS meminta Conversation Name dan Folder. Isi Project status: KG-2041 on hold, unknown code, biarkan folder Default, lalu klik Continue.

Hal-hal yang perlu diketahui:

• Set yang dipasang di sini dipakai oleh setiap step. Seret barisnya untuk mengubah urutan: set pertama yang menjawab sebuah pemanggilan yang dipakai.
• Setiap step juga punya baris Tool mocks (n) sendiri dengan tombol Add step mock set. Set milik step diperiksa sebelum set milik conversation, sehingga Anda bisa mengubah jawaban satu tool hanya untuk satu step (misalnya "pencarian pertama tidak menemukan apa pun, pencarian kedua menemukan proyeknya").
• Date & time the agent sees: secara default agent melihat waktu sungguhan. Aktifkan switch untuk menetapkan tanggal, jam, dan zona waktu untuk simulasi ini. Gunakan ketika argumen tool bergantung pada tanggal ("besok"), agar condition tetap cocok di setiap run.
• Di menu ⋮ pada baris, Make a private copy (pada set library) memberi conversation ini salinannya sendiri yang bisa Anda ubah tanpa memengaruhi conversation lain, dan Save to library (pada set private) membagikannya ke simulasi lain milik agent.

Langkah 7: Menjalankan simulasi

Klik Run pada conversation. Jika run bisa menjangkau tool yang diblokir dalam simulasi dan belum punya mock, dialog Attention mencantumkannya lebih dulu. Untuk Atlas, dialog menyebutkan bahwa run "will hit 3 blocked tools, which will return a policy error instead of actually running": Ledger (agent dari Bekerja dengan Agent Lain) serta resolve-library-id dan query-docs (tool dari Menghubungkan MCP Server).

Pertanyaan-pertanyaan ini tentang status proyek, jadi Atlas seharusnya tidak membutuhkan tool-tool tersebut. Klik Run anyway. Jika sebuah skenario memang bergantung pada tool yang diblokir, klik Cancel dan tambahkan mock untuknya terlebih dahulu.

Periksa hasilnya

1. Setelah run selesai, buka dari tab Results (lihat Menjalankan dan Memantau). Conversation menampilkan Completed, folder Default, 2/2 Steps completed, durasi (di sini 14 detik), dan 5/6 Matched.

2. Klik Mocks used in this run untuk melihat mock set persis yang dipakai run tersebut, dibekukan pada saat run, serta jam simulasi jika Anda mengaturnya.
3. Buka Step #1 lalu buka Tool calls. Pemanggilan custom:get_project_status dengan argumen {"projectCode":"KG-2041"} menampilkan chip Mocked dan Conversation. Baris di bawahnya menyebutkan case 'KG-2041 is on hold', mock set Projects API: KG-2041 on hold, dan status 200.

Setiap pemanggilan menampilkan chip hasil dan asal jawabannya:

Buka sebuah pemanggilan untuk melihat Arguments dan Response lengkapnya. Jika tool memiliki Response Prompt, baris tersebut mencatat bahwa prompt itu diterapkan di atas respons mock, sama seperti di production. Pada pemanggilan Mocked atau Live, Save as case mengubah pemanggilan itu menjadi case baru (di set private untuk step ini, untuk seluruh conversation, atau di set yang sudah ada), yang merupakan cara tercepat membangun mock dari perilaku sungguhan.

4. Lihat jawaban dan criteria step tersebut. Di Step #1, Atlas melaporkan status On hold pada tahap persetujuan CFO, progres 62%, dan update terbaru dari mock. Tiga dari empat criteria cocok. Yang gagal adalah Identifies KG-2041 as the Surabaya warehouse expansion project: evaluasinya mencatat bahwa jawaban tidak menyebut KG-2041 maupun nama proyeknya.

Inilah gunanya simulasi. Data mock-nya benar, jadi kegagalan ini menunjuk ke agent, bukan ke data. Response Prompt milik Atlas memintanya memulai dengan status dan tahap persetujuan, sehingga Atlas tidak pernah menyebut proyek mana yang sedang dibahas. Pembaca yang sedang memantau tiga proyek bisa tertukar. Anda bisa memperbaikinya di Response Prompt get_project_status (misalnya, "Start with the project code and name, then the status and the current approval stage..."), publish, lalu jalankan simulasi lagi sampai hasilnya 6/6 Matched. Perhatikan juga baris "Budget: Not provided in the project status": mock tidak berisi field anggaran, dan Atlas mengatakannya alih-alih mengarang angka.

5. Buka Step #2. Pemanggilan untuk KG-9999 tidak cocok dengan case mana pun, jadi default Otherwise menjawab dengan 404, dan Atlas mengatakan bahwa kode itu tidak dikenal serta meminta pengguna memeriksanya, sesuai Rules pada API. Kedua criteria step ini cocok.

Jika hasilnya tidak sesuai harapan:

• Pemanggilan menampilkan Blocked, bukan Mocked. Mock set belum dipasang ke conversation atau step ini, atau mock set itu untuk tool lain. Periksa kartu Tool mocks dan nama tool-nya.
• Pemanggilan untuk KG-2041 menampilkan Default. Condition tidak cocok dengan argumen yang dikirim AI. Buka pemanggilannya, bandingkan Arguments dengan condition, dan periksa apakah Aa (match case) aktif.
• Tool tidak muncul di Add tool. Publish agent setelah menambah atau mengganti nama tool.

Batasan dan praktik yang baik

• Mock hanya berlaku untuk conversation simulation. Preview, agent yang sudah di-publish, dan channel sungguhan selalu memanggil tool sungguhan.
• Satu mock set menampung hingga 50 tool, setiap tool hingga 50 case, setiap case hingga 20 condition.
• Web search dan web scraping tidak bisa di-mock; keduanya berjalan live dalam simulasi.
• Mock mengikuti agent yang sudah di-publish: publish setelah menambah atau mengganti nama tool, lalu perbarui mock set Anda.
• Buat satu tujuan per mock set ("happy path", "API down", "proyek ditahan") dan kombinasikan beberapa set per skenario, alih-alih satu set raksasa.
• Selalu uji setidaknya satu jalur error (template Error) agar Anda tahu bagaimana agent menjawab ketika sebuah layanan gagal. Respons 404 untuk KG-9999 di atas adalah salah satunya.

Untuk daftar lengkap field di layar-layar ini, lihat halaman Help Mocks, Scenarios, dan Results.

Langkah berikutnya

• Berikutnya dalam alur: Mengingat Setiap Pengguna, langkah pertama Tahap 4 · Lanjutan.
• Menjalankan dan Memantau: jalankan skenario secara rutin dan pantau statusnya.
• Menganalisis dan Memperbaiki: ubah criteria yang gagal menjadi perbaikan.
• Langkah sebelumnya: Berbicara dengan Suara.