Debug dan Pemulihan Kegagalan Agen Ponsel Android: Runbook Praktis FoneClaw
Runbook untuk menghentikan, mendiagnosis, memulihkan, dan mengulang tugas agen ponsel Android yang gagal tanpa menggandakan efek eksternal, memakai pola Detect-Attribute-Recover-Rerun dan kontrol FoneClaw.
- Saat tugas agen ponsel gagal, jangan langsung mengulang seluruh tugas; hentikan efek lanjutan, simpan layar dan hasil terakhir, lalu pisahkan tugas baca-saja, reversibel, dan berdampak eksternal.
- Kesalahan yang muncul di akhir alur sering bukan akar penyebabnya. Diagnosis yang baik melihat niat awal, langkah tool, status layar, izin, persetujuan, jaringan, aplikasi target, dan hasil eksternal.
- Pola riset AgentDebugX Detect-Attribute-Recover-Rerun berguna sebagai kerangka kerja: deteksi kegagalan, atribusikan langkah penyebab paling awal, pulihkan prasyarat, lalu ulang hanya bagian yang aman.
- FoneClaw mendukung pemulihan melalui status tugas yang terlihat, konteks layar saat ini yang dipilih pengguna, persetujuan, penghentian, retry, pemulihan izin, dan 100+ built-in tools untuk tindakan Android yang didukung.
Respons Lima Menit Saat Tugas Agen Gagal
Ketika tugas agen ponsel gagal, tindakan pertama adalah berhenti dengan aman. Jangan langsung mengulang seluruh tugas. Agen ponsel dapat menyentuh efek eksternal: pesan yang terkirim, panggilan yang dimulai, pengaturan yang berubah, kalender yang dibuat, file yang dihapus, atau pembayaran yang diarahkan ke aplikasi lain. Retry tanpa memahami status terakhir dapat menggandakan tindakan yang sudah selesai.
Gunakan checklist lima menit. Pertama, hentikan tugas yang masih berjalan atau batalkan langkah berikutnya bila tersedia. Kedua, simpan hasil terakhir yang terlihat: layar, pesan error, status tool, izin yang diminta, dan apakah tindakan sudah terjadi. Ketiga, tentukan jenis tugas: baca-saja, reversibel, atau berdampak eksternal. Keempat, jangan bersihkan data aplikasi atau mencopot aplikasi sebagai langkah awal. Kelima, tulis satu kalimat niat awal, misalnya: agen diminta membuat pengingat jam delapan, tetapi berhenti setelah meminta izin kalender.
makalah AgentDebugX memberi kerangka segar untuk memahami kegagalan agen: Detect, Attribute, Recover, dan Rerun. Pelajaran utamanya sangat cocok untuk ponsel: error yang terlihat di akhir alur dapat muncul jauh setelah akar penyebab terjadi. Untuk tindakan sensitif, desain persetujuan yang jelas membantu pengguna berhenti pada titik yang tepat; kami membahas hubungan antara keyakinan, alasan, dan persetujuan di UX Persetujuan Agen AI di Ponsel: Keyakinan, Alasan, dan Kontrol Pengguna.
Kumpulkan Paket Bukti Kegagalan Minimal
Paket bukti yang baik cukup lengkap untuk merekonstruksi alur, tetapi cukup ringkas untuk tidak membocorkan data pribadi. Mulailah dari niat awal: apa yang Anda minta, hasil apa yang diharapkan, dan aplikasi atau kontak apa yang terlibat. Lalu catat jalur yang terlihat: tool atau langkah apa yang dimulai, layar apa yang terbuka, izin apa yang muncul, persetujuan apa yang diminta, dan hasil terakhir apa yang dibacakan atau ditampilkan.
Untuk debug dan pemulihan kegagalan agen ponsel, screenshot saja jarang cukup. Anda juga perlu status izin, jaringan, aplikasi target, waktu kejadian, mode baterai, apakah layar terkunci, apakah aplikasi berada di depan, dan apakah ada gangguan seperti panggilan masuk. Jika tugas menyentuh data sensitif, redact sebelum dibagikan: nama kontak dapat diganti menjadi Kontak A, isi pesan dapat diringkas, token dan kata sandi harus dihapus, dan nomor rekening atau alamat lengkap tidak perlu disertakan kecuali dukungan memintanya secara eksplisit.
AgentDebugX menekankan pentingnya memahami trajectory, bukan hanya error terakhir. Dalam konteks ponsel, trajectory berarti urutan niat, rencana, tool, layar, izin, persetujuan, hasil, dan efek eksternal. Catatan seperti ini juga membantu membedakan bug produk dari kondisi perangkat. Untuk struktur bukti identitas agen, izin, dan audit yang lebih formal, Identitas Agen AI: Izin, Persetujuan per Alat, dan Jejak Audit Phone Agent memberi kerangka lanjutan.
Klasifikasikan Lapisan Kegagalan Agen Ponsel
Langkah berikutnya adalah mengklasifikasikan lapisan kegagalan. Satu pesan error dapat berasal dari beberapa penyebab. Agen yang mengatakan tidak bisa mengirim pesan mungkin salah memahami niat, memilih tool yang tidak cocok, kehilangan izin SMS, membuka layar yang salah, gagal karena jaringan, atau berhenti karena persetujuan belum diberikan. Akar penyebab agen harus dicari dengan lapisan yang jelas.
| Lapisan | Gejala umum | Pemeriksaan cepat | Contoh pemulihan |
|---|---|---|---|
| Input dan niat | Agen menjalankan tugas yang berbeda dari maksud pengguna. | Bandingkan permintaan asli dengan rencana yang dibuat. | Ulangi instruksi dengan target, batas, dan hasil yang lebih eksplisit. |
| Model dan rencana | Rencana terlihat masuk akal, tetapi urutan langkah keliru. | Lihat apakah langkah awal memenuhi prasyarat sebelum tindakan. | Mulai dari langkah prasyarat yang hilang, bukan seluruh tugas. |
| Perutean kemampuan | Agen memilih tool atau plugin yang kurang tepat. | Periksa kemampuan yang terpasang, aktif, dan disarankan. | Pilih kemampuan yang benar atau gunakan fallback yang terlihat. |
| Konteks layar | Agen membaca atau mengetuk layar yang berbeda dari perkiraan. | Pastikan aplikasi target berada di depan dan layar cocok. | Kembalikan aplikasi ke layar yang benar lalu ulang langkah kecil. |
| Izin Android | Tugas berhenti saat kamera, kontak, kalender, SMS, lokasi, atau notifikasi dibutuhkan. | Periksa izin saat fitur dipakai dan apakah izin baru saja dicabut. | Berikan izin yang relevan atau pilih jalur degradasi yang aman. |
| Persetujuan | Tindakan menunggu konfirmasi pengguna. | Cek kartu persetujuan, alasan, target, dan isi tindakan. | Setujui setelah benar, ubah target, atau batalkan. |
| Layanan eksternal | API, jaringan, toko aplikasi, email, atau aplikasi pihak ketiga tidak merespons. | Uji koneksi dan status aplikasi tanpa mengulang efek eksternal. | Tunggu, ganti jaringan, atau simpan draf lokal. |
| Verifikasi hasil | Agen mengira selesai, tetapi status perangkat berbeda. | Bandingkan hasil tool dengan status aktual di aplikasi. | Jalankan cek baca-saja, lalu perbaiki hanya langkah yang belum terjadi. |
panduan Android tentang runtime permissions menegaskan bahwa izin harus diperiksa saat digunakan, dan pengguna dapat menolak, mencabut, atau menolak secara permanen izin tertentu. Karena itu, kegagalan izin bukan kegagalan model semata. Sebaliknya, izin yang sudah benar tidak membuktikan rencana model benar. Untuk lapisan perutean kemampuan seperti AutoAttach, Suggest, dan Fallback, baca Perutean Kemampuan Agen AI Android: AutoAttach, Suggest, Fallback, dan FoneClaw agar diagnosis routing tidak bercampur dengan izin atau UI.
Temukan Langkah Penyebab Paling Awal
Setelah lapisan kegagalan terlihat, cari langkah penyebab paling awal. Mulai dari error yang muncul, lalu telusuri mundur: kapan hasil mulai menyimpang dari niat? Apakah target salah sejak rencana? Apakah tool benar tetapi argumennya salah? Apakah izin hilang tepat sebelum tool dipanggil? Apakah aplikasi berpindah layar karena notifikasi, rotasi, atau dialog sistem?
Pola Detect-Attribute-Recover-Rerun dari AgentDebugX dapat diadaptasi seperti ini. Detect: tandai gejala yang terlihat dan status terakhir. Attribute: sebutkan penyebab paling awal yang punya bukti, bukan tebakan paling dramatis. Recover: pulihkan prasyarat yang hilang, seperti izin, aplikasi di depan, koneksi, target kontak, atau persetujuan. Rerun: ulang hanya suffix terkecil yang aman, misalnya langkah membuat kalender setelah izin kalender dipulihkan, bukan seluruh alur dari awal.
Ketika keyakinan belum penuh, tulis penyebab utama dan alternatifnya. Contoh: kemungkinan utama adalah izin kalender dicabut karena dialog sistem muncul sebelum tool kalender dipanggil; alternatifnya adalah akun kalender belum dipilih. Pernyataan seperti ini lebih berguna daripada label umum seperti model error. Untuk evaluasi yang lebih terstruktur setelah insiden selesai, Benchmark Phone Agent Android: Cara Mengevaluasi AI Agent Mobile 2026 membantu mengubah kasus gagal menjadi skenario uji yang bisa diulang.
Pulihkan tanpa Menggandakan Efek yang Sudah Selesai
Recovery yang aman dimulai dari inventaris efek. Apa yang sudah terjadi di luar agen? Pesan sudah terkirim atau baru menjadi draf? Pengingat sudah dibuat atau hanya formulir yang terbuka? Pengaturan Wi-Fi sudah berubah atau tool baru membaca status? Jika sebuah efek sudah selesai, jangan meminta agen mengulang dari awal sebelum Anda tahu apakah tindakan itu idempotent, reversibel, atau berdampak eksternal.
Gunakan ladder pemulihan berikut. Pertama, lakukan cek baca-saja: status pesan, kalender, pengaturan, file, atau aplikasi target. Kedua, pulihkan prasyarat yang jelas: izin, akun, koneksi, aplikasi di foreground, lock screen, atau target kontak. Ketiga, ulang hanya langkah gagal bila langkah itu aman. Keempat, verifikasi downstream state: apakah pengingat muncul, apakah mode perangkat berubah, apakah file tersimpan. Kelima, hentikan tugas setelah hasil sesuai; jangan menambah langkah baru saat masih dalam mode pemulihan.
Android dapat membuat izin ditolak permanen, dicabut manual, atau perlu diminta ulang dalam konteks fitur. catatan praktik izin Android menyarankan aplikasi meminta akses yang diperlukan dan menguji kombinasi izin diberikan maupun dicabut. Dalam alur agen, graceful degradation berarti pengguna tetap mendapat jalur yang masuk akal: simpan draf, buka pengaturan izin, tampilkan alasan, atau berhenti dengan status yang dapat dibaca.
Untuk tugas panjang dan multi-percakapan, pemulihan juga perlu menjaga antrian. Jangan biarkan satu retry menggandakan tugas lain yang sedang menunggu. Prinsipnya: perbaiki prasyarat, ulang bagian yang kecil, verifikasi, lalu kembali ke antrian tugas yang semestinya.
Gunakan Kontrol FoneClaw untuk Diagnosis dan Pemulihan
Di FoneClaw, kami membangun pemulihan dari pengalaman nyata: kegagalan ponsel jarang satu dimensi. Kadang model merencanakan dengan benar, tetapi izin Android belum siap. Kadang tool memberi hasil jelas, tetapi aplikasi target berubah layar. Kadang pengguna perlu menghentikan tugas, menyalin hasil, mengirim feedback, atau retry setelah memperbaiki prasyarat. Karena itu, kontrol pemulihan harus terlihat di tempat kerja, bukan hanya di log internal.
Gunakan alur FoneClaw seperti runbook. Kembali ke konteks tugas yang sama, baca status terakhir, dan lihat hasil tool yang sudah muncul. Jika masalahnya konteks layar, lampirkan layar saat ini secara sengaja melalui alur yang dipilih pengguna; FoneClaw tidak membutuhkan klaim tangkapan layar otomatis untuk semua keadaan. Jika masalahnya izin, gunakan pemulihan izin dan ulangi setelah akses yang relevan diberikan. Jika masalahnya persetujuan, baca ulang target tindakan, alasan, dan isi yang akan dikirim atau disimpan.
FoneClaw menyediakan 100+ built-in tools untuk tindakan Android yang didukung, termasuk cek baca-saja, pengaturan yang relatif reversibel, dan tindakan berdampak seperti komunikasi atau kalender. Kategori ini penting saat retry. Cek status baterai aman diulang. Mengirim pesan tidak diperlakukan sama. Membuat pengingat perlu dicek dulu agar tidak ganda. Prinsip yang kami pakai: rencana boleh dibantu model, tetapi eksekusi harus melewati tool, izin, persetujuan, status, dan pemulihan yang bisa dipahami pengguna.
Untuk memahami mekanisme konteks layar secara terpisah, baca Asisten AI Mengambang Android untuk Memahami Layar Saat Ini. Untuk kemampuan terkini, gunakan halaman Fitur FoneClaw; kami menjaga detail yang berubah di halaman resmi agar runbook ini tetap fokus pada cara mendiagnosis dan pulih.
Buat Laporan Dukungan atau Bug yang Berguna
Berhenti dan eskalasikan ketika tiga hal terjadi: efek eksternal tidak dapat dipastikan, izin atau aplikasi terus berulang gagal setelah prasyarat dipulihkan, atau agen memilih tool yang salah dengan pola yang bisa direproduksi. Laporan yang baik tidak perlu memuat seluruh kehidupan digital Anda. Laporan harus cukup untuk mengulang kasus.
Gunakan template singkat ini: niat awal, hasil yang diharapkan, hasil aktual, langkah terakhir yang terlihat, tool atau layar yang terlibat, status izin, status jaringan, perangkat dan versi Android, apakah layar terkunci, apakah tugas sudah menghasilkan efek eksternal, dan langkah pemulihan yang sudah dicoba. Hapus kredensial, token, isi pesan pribadi, nomor lengkap, kontak sensitif, lokasi detail, dan lampiran pribadi kecuali benar-benar dibutuhkan dan Anda menyetujuinya.
Tambahkan waktu kejadian relatif, misalnya setelah memberi izin kalender atau setelah aplikasi target berpindah ke layar login. Dukungan dapat bekerja lebih cepat dengan bukti yang tersusun daripada screenshot tunggal tanpa konteks.
Cegah Kegagalan Berulang dengan Tes Penerimaan
Satu pemulihan berhasil belum membuktikan masalah hilang. Ubah kegagalan menjadi tes penerimaan kecil. Tulis skenario: izin diberikan, izin dicabut, aplikasi target belum dibuka, jaringan lemah, layar terkunci, target ambigu, dan pengguna menolak persetujuan. Untuk setiap skenario, definisikan hasil lulus: agen menampilkan alasan, meminta izin yang benar, berhenti tanpa efek ganda, atau menawarkan fallback yang jelas.
Uji ulang tugas dengan kombinasi izin yang realistis seperti yang direkomendasikan praktik Android. Jangan hanya menguji jalur ideal. Tugas agen ponsel harus tetap bisa menjelaskan kegagalan saat izin hilang, kontak ambigu, kalender belum dipilih, atau aplikasi berubah UI. Untuk tim yang membangun harness dan tata kelola uji, Harness Phone Agent yang Terus Membaik: Uji, Tata Kelola, dan Batas Aman membantu membawa runbook ini ke proses produk.
Catat kapan tugas boleh diulang, kapan harus berhenti, dan bukti apa yang menunjukkan hasil akhir benar. Itulah inti coba ulang langkah alat gagal: ulang bagian yang aman, bukan seluruh cerita. Dengan kebiasaan ini, tugas agen AI gagal berubah dari kejutan menjadi kasus yang bisa didiagnosis, dipulihkan, dan dicegah.