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 sebuah skenario, 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 skenario dua step terhadap mock set itu.

AI tetap terlibat. Mock mengembalikan jawaban tool yang persis sama setiap kali, tetapi Atlas yang memutuskan kapan memanggil tool dan menulis balasannya, dan AI menilai setiap kriteria. Hal-hal itu bisa berbeda dari satu run ke run berikutnya, jadi baca satu hasil sebagai contoh.

Sebelum memulai

• Anda memiliki peran Owner atau Contributor pada agent. Siapa pun dengan salah satu peran itu bisa memakai Simulation.
• 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, sehingga Anda bisa menjalankan terhadap Published seperti halaman lain dalam langkah ini. Editor mock menampilkan tool dari agent draft dan yang sudah di-publish sekaligus, jadi tool yang baru Anda simpan di draft pun bisa di-mock. Lihat Preview dan Publish Perubahan.
• Anda memahami dasar skenario (step, expected response, criteria). Jika belum, baca dulu Menyusun Rangkaian Uji Pertama dan Menulis Skenario yang Baik.
• Tool Mocks dan Tool Policy muncul di bawah Simulation pada sidebar agent. Jika tidak terlihat, fitur ini belum diaktifkan di CMS 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 → Tool 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.

Screenshot di halaman ini menampilkan nama yang berakhir dengan 2, seperti Projects API: KG-2041 on hold 2, karena agent demo sudah memiliki item dengan nama yang sama. Pakai nama persis seperti tertulis di atas.

Set baru terbuka di editor berjudul New Mock Set, dengan chip Library dan tombol Save. Chip Library berarti set ini dibagikan: Anda dapat memasangnya ke skenario mana pun milik agent ini. Di bawah field, Tools in this set masih kosong ("No tools in this set yet."), dan sisi kanan menampilkan "Select a tool to edit its mocks. Or use Add tool to get started." Setelah Anda menyimpan set itu dan membukanya kembali, judulnya juga menampilkan Used in 0 scenarios, yang berubah setelah Anda memasang set itu di Langkah 6, dan tombol Duplicate yang 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 di kotak Search tools… lalu klik. Daftar ini menampilkan tool dari agent draft dan yang sudah di-publish sekaligus, dikelompokkan menurut sumbernya di bawah judul huruf kapital (CUSTOM API, PLUGINS, MCP, OTHER AGENTS, A2A, BUILT-IN). Setiap entri menunjukkan apa yang dilakukan tool terhadap data dan apa yang akan dilakukannya dalam simulasi jika tidak di-mock: Blocked unless mocked, Runs live unless mocked, atau Simulated success. Misalnya, pencarian escalate menampilkan tool bawaan escalate_conversation dengan label Writes data dan Simulated success. Chip Draft only atau Published only muncul ketika tool hanya ada di satu versi agent.

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, set akan menampilkan Tool not found in the draft or 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, di Label this case (optional): 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 atau, untuk Custom API, Service down or timed out, Not found (404), Unauthorized (401), Rate limited (429), dan Invalid request (400), 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. Hasilnya berbeda setiap kali, jadi baca dulu sebelum Anda pakai. Format merapikan (pretty-print) JSON, berguna setelah Anda menempelkan body.
• 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 (404), 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 Tool Policy dan perilaku default tool sesuai tabel di Mengapa memakai mock. Di daftar tool, tool seperti ini ditandai "keeps looking".

Klik Save. CMS menampilkan "Mock set created successfully". Set tersebut kini muncul di halaman Tool Mocks beserta deskripsinya, 1 tool · 1 case, chip tool get_project_status, dan berapa skenario yang memakainya.

Langkah 6: Memasang mock set ke skenario

1. Buka Simulation → Scenarios, pilih folder Kirana Projects dari Menyusun Rangkaian Uji Pertama, klik New Scenario, lalu tulis skenario dengan dua step. Lihat Menulis Skenario yang Baik 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 panel setup di sisi kiri formulir, buka Tool Mocks lalu klik Add Mock Set:
   • From library… memasang set bersama. Di panel Add from library, centang Projects API: KG-2041 on hold lalu klik Add 1 mock set.
   • Create new membuat set Private yang hanya dimiliki skenario ini.
4. Klik Save. Dialog Scenario Information meminta Scenario Name dan Folder. Isi Project status: KG-2041 on hold, unknown code, biarkan folder Kirana Projects (jika Anda melewati halaman pertama langkah ini, Qlar menawarkan Default), lalu klik Continue. Setelah itu klik Yes pada "Are you sure you want to create this scenario?" dan Close pada pesan sukses.

Di bawah Agent Tools, yang berada di atas Tool Mocks pada panel setup, bar kini menampilkan chip Mocked, chip Simulated (untuk escalate_conversation), chip Live (untuk tool yang selalu berjalan live), dan chip Blocked. Klik Review all tools: get_project_status tertulis Mocked · Projects API: KG-2041 on hold, sedangkan tool Atlas lainnya, seperti Ledger dan dua tool MCP, tertulis Blocked · Not reviewed in the tool policy, karena belum ada yang meninjaunya. Langkah berikutnya menampilkan tool yang sama di konfirmasi run.

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 bagian Tool Mocks (n) sendiri dengan tombol Add Mock Set. Set milik step diperiksa sebelum set milik skenario, sehingga Anda bisa mengubah jawaban satu tool hanya untuk satu step (misalnya "pencarian pertama tidak menemukan apa pun, pencarian kedua menemukan proyeknya").
• Date and Time pada panel setup: secara default agent melihat waktu sungguhan. Aktifkan Fixed date & time untuk menetapkan Date & time dan Time zone untuk skenario 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 skenario ini salinannya sendiri yang bisa Anda ubah tanpa memengaruhi skenario lain, dan Save to library (pada set private) membagikannya ke simulasi lain milik agent.

Langkah 7: Menjalankan simulasi

Kembali di tab Scenarios, klik Run pada kartu skenario. Konfirmasi menanyakan Are you sure you want to run the scenario "Project status: KG-2041 on hold, unknown code"?. Di bawah Run against, pilih Published.

Jika run bisa menjangkau tool yang diblokir dalam simulasi dan belum punya mock, konfirmasi juga mencantumkannya. Untuk Atlas, konfirmasi menyebutkan bahwa run "will hit 3 blocked tools. A blocked tool returns a policy error instead of running, so any step that needs it will fail.": Ledger (agent dari Bekerja dengan Agent Lain) serta resolve-library-id dan query-docs (tool dari Menghubungkan MCP Server). Baris sesudahnya menambahkan: "To test those steps, cancel and open the scenario, then mock the tools (or allow them live) under "Tool Mocks". Otherwise choose "Run anyway" to continue without them." Tombol konfirmasi kini berbunyi Run anyway.

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, atau buka skenarionya dan klik Mock it di samping tool. Tool mana yang tampil sebagai blocked juga bergantung pada Tool Policy: lihat Memilih Tool yang Berjalan Live.

Periksa hasilnya

1. Klik Close pada pesan sukses. Qlar membuka halaman Simulation Result, atau Anda bisa membuka run-nya nanti dari tab Results (lihat Membaca Hasil). Kartu STATUS di bagian atas bertuliskan Completed. Di bawah Scenario (1) (kata ini tunggal untuk satu skenario), baris skenario menampilkan folder, 2/2 Steps completed, durasi (di sini 21 detik, berbeda dari run ke run), dan 5/6 Matched. Foldernya Kirana Projects jika Anda mengikuti Menyusun Rangkaian Uji Pertama, atau Default jika Anda melewatinya.

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 skenarionya, buka Step #1 lalu buka Tool calls. Pemanggilan custom:get_project_status dengan argumen {"projectCode":"KG-2041"} menampilkan chip Mocked dan Scenario. Baris di bawahnya menyebutkan case dengan id-nya diikuti labelnya, misalnya Case 9b8e8dfd-… 'KG-2041 is on hold', lalu mock set Projects API: KG-2041 on hold dan status 200. Di atas daftar, judulnya Tool calls (1) dengan chip Mocked 1, dan "In the order the agent called them".

Setiap pemanggilan menampilkan chip hasil dan asal jawabannya:

Ketika tidak ada mock yang menjawab, chip kedua menyebutkan aturan yang memutuskan: Tool policy, Not reviewed in the tool policy, Allowed live in this scenario, atau Built-in default. Tool dalam Simulasi menjelaskan masing-masing.

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 skenario, 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, masing-masing dalam kotak hijau dengan kutipan. Yang gagal adalah kotak abu-abu The answer identifies KG-2041 as the Surabaya warehouse expansion project.: alasan di bawahnya mengatakan bahwa jawaban tidak mengidentifikasi KG-2041 sebagai proyek itu.

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..."), mengujinya pada Draft seperti di Menguji Perubahan Sebelum Publish, publish, lalu jalankan skenario lagi sampai hasilnya 6/6 Matched. Perhatikan juga baris "Budget spent vs. total: Not provided": 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 skenario atau step ini, Anda belum menyimpan skenarionya, atau mock set itu untuk tool lain. Periksa bagian 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. Simpan dulu tool itu di agent. Tool yang hanya ada di draft menampilkan chip Draft only, dan yang hanya ada di agent yang sudah di-publish menampilkan Published only.

Batasan dan praktik yang baik

• Mock hanya berlaku untuk simulasi. Preview, agent yang sudah di-publish, dan channel sungguhan selalu memanggil tool sungguhan. Mock tidak mengubah agent yang tayang, jadi tidak ada yang perlu di-publish untuknya.
• 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 terikat pada sebuah tool. Jika Anda menghapus tool dari agent, mock-nya menampilkan Tool not found in the draft or published agent, dan Re-bind to… memindahkan case-nya ke tool lain.
• 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 Tool Mocks, Scenarios, dan Results.

Langkah berikutnya

• Berikutnya dalam langkah ini: Memilih Tool yang Berjalan Live, untuk menentukan tool Atlas mana yang boleh berjalan sungguhan saat pengujian.
• Fitur yang sama secara lebih mendalam: Tool Mocks dan Tool dalam Simulasi.
• Referensi per field: Tool Mocks, Scenarios, dan Results.
• Sebelumnya dalam langkah ini: Menyusun Rangkaian Uji Pertama.