AI Tool
TM AI Tool adalah aksi yang dapat dieksekusi yang dapat dilakukan oleh AI Agent untuk berinteraksi dengan sistem, memanipulasi data, dan melaksanakan tugas spesifik dalam aplikasi TechMaju.
Memahami DocType TM AI Tool
Tujuan: TM AI Tool memungkinkan administrator platform dan developer untuk membuat aksi kustom yang dapat dieksekusi oleh AI Agent. Tool ini menjembatani kesenjangan antara penalaran AI dan operasi sistem, memungkinkan agent untuk membuat, membaca, memperbarui, dan menghapus data, memanggil API eksternal, mengirim notifikasi, dan melakukan aksi programatik apa pun yang diperlukan untuk menyelesaikan permintaan pengguna.
Fungsi: TM AI Tool menyediakan: - Script Python yang dapat dieksekusi yang dapat dipanggil oleh AI Agent - Schema input terstruktur yang mendefinisikan parameter yang diperlukan - Mekanisme output untuk mengembalikan hasil ke AI Agent - Integrasi dengan API framework Frappe dan logika bisnis kustom - Reusabilitas di berbagai AI Agent dan Skill - Audit trail eksekusi tool melalui record AI Agent Run
Role yang Diperlukan
Role berikut diperlukan untuk mengelola TM AI Tool:
- TM AI Developer: Akses penuh untuk membuat, mengedit, dan menghapus AI Tool
- System Manager: Akses administratif ke semua AI Tool
Field TM AI Tool
| Field | Deskripsi |
|---|---|
| Tool Name | Identifier unik untuk tool (slugified, lowercase dengan underscore) |
| Description | Penjelasan jelas tentang apa yang dilakukan tool (maksimum 240 karakter, digunakan AI untuk memahami tujuan tool) |
| Input Schema | Object JSON yang mendefinisikan parameter wajib dan opsional dengan deskripsi |
| Script | Kode Python yang dieksekusi ketika tool dipanggil (tanpa import, gunakan API Frappe langsung) |
| Active | Checkbox untuk mengaktifkan atau menonaktifkan tool |
Prosedur
1. Navigasi ke TM AI Tool
Navigasi ke TechMaju AI > TM AI Tool
2. Menambahkan TM AI Tool Baru
- Klik + Add TM AI Tool untuk membuka form pembuatan
- Masukkan Tool Name: Gunakan lowercase dengan underscore (misalnya: createcustomer, sendemail, updateorderstatus)
- Masukkan Description: Tulis penjelasan yang jelas dan ringkas (maksimal 240 karakter) yang menggambarkan apa yang dilakukan tool
- Centang checkbox Active untuk mengaktifkan tool
3. Mengkonfigurasi Input Schema
Input Schema mendefinisikan parameter apa yang harus disediakan AI Agent saat memanggil tool ini.
Format Schema: - Gunakan struktur object JSON - Nama parameter harus berupa keys menggunakan snake_case - Nilai harus berupa deskripsi yang dapat dibaca manusia - Tunjukkan dengan jelas parameter opsional dan nilai default - Dokumentasikan tipe data yang diharapkan dalam deskripsi - Tentukan opsi valid untuk field pilihan atau select
Best Practice: - Jaga konsistensi nama parameter dengan nama field Frappe - Gunakan penjelasan yang jelas dan deskriptif untuk setiap parameter - Tandai parameter opsional secara eksplisit dalam deskripsi - Sertakan aturan validasi atau batasan dalam deskripsi - Kelompokkan parameter terkait secara logis
4. Menulis Script
Bagian Script berisi kode Python yang dieksekusi ketika tool dipanggil oleh AI Agent.
Variable Konteks yang Tersedia:
| Variable | Tipe | Deskripsi |
|---|---|---|
| input_param | dict | Parameter yang diberikan oleh AI Agent berdasarkan input schema |
| result | dict | Dictionary output untuk menyimpan dan mengembalikan hasil ke agent |
| application | str | Nama konteks aplikasi saat ini |
| context_tools | list | Daftar nama tool lain yang tersedia |
| frappe | module | Modul framework Frappe (sudah pre-imported dan siap digunakan) |
Aturan Kritis Script:
Dilarang: - TIDAK ADA statement import (Frappe dan modul umum sudah pre-imported) - TIDAK ADA definisi fungsi menggunakan keyword def - TIDAK ADA statement return (gunakan dictionary result) - TIDAK ADA panggilan frappe.db.commit() (commit ditangani otomatis) - TIDAK ADA operator augmented assignment (+=, -=, *=, dll.)
Wajib: - Selalu validasi input yang diperlukan di awal - Gunakan inputparam.get() untuk mengambil parameter - Gunakan frappe.throw() untuk error validasi - Simpan semua hasil di dictionary result - Tangani exception dengan baik - Gunakan API Frappe langsung (frappe.getdoc, frappe.db.set_value)
Validasi Input: - Periksa parameter wajib terlebih dahulu - Validasi tipe data dan format - Verifikasi dokumen yang direferensikan ada - Periksa permission user jika sesuai - Berikan pesan error yang jelas menggunakan frappe.throw()
Struktur Dictionary Result:
Dictionary result menggunakan key khusus untuk mengkomunikasikan hasil kembali ke AI Agent:
| Key | Tujuan | Format Nilai |
|---|---|---|
| _created | Lacak dokumen yang dibuat | Dictionary yang memetakan nama DocType ke list nama dokumen |
| _updated | Lacak dokumen yang diperbarui | Dictionary yang memetakan nama DocType ke list nama dokumen |
| _deleted | Lacak dokumen yang dihapus | Dictionary yang memetakan nama DocType ke list nama dokumen |
| _message | Pesan informasional | String message yang menjelaskan apa yang dilakukan |
| continueloop | Kontrol eksekusi loop | Boolean (False menghentikan loop, True melanjutkan) |
| contextfor_next | Update prompt berikutnya | String untuk mengganti prompt saat ini di iterasi berikutnya |
Key Kustom: - Anda dapat menambahkan key kustom ke dictionary result - Key kustom tersedia untuk tool berikutnya dalam eksekusi yang sama - Gunakan nama key yang deskriptif untuk data kustom
5. Testing Tool
Pendekatan Testing:
Testing System Console: - Navigasi ke System Console di Frappe - Setup dictionary inputparam dengan data sample - Inisialisasi dictionary result kosong - Set variable application dan contexttools - Paste dan jalankan kode script Anda - Verifikasi dictionary result berisi output yang diharapkan
Testing AI Agent: - Buat AI Agent khusus untuk testing - Tambahkan tool ke tabel Tools agent - Konfigurasi agent dengan context yang sesuai - Jalankan agent dengan prompt yang dirancang untuk memicu tool - Review record AI Agent Run untuk verifikasi eksekusi - Periksa hasil tool di field results Run
Testing Integrasi: - Test tool dengan kombinasi input berbeda - Verifikasi tool bekerja dengan tool lain dalam sequence - Test error handling dengan input tidak valid - Validasi permissions dan access control - Periksa performa dengan volume data realistis
6. Menyimpan dan Mengaktifkan Tool
Checklist Pre-Save: - Tool Name unik dan deskriptif - Description menjelaskan tujuan tool dengan jelas - Input Schema lengkap dan terdokumentasi dengan baik - Script telah ditest dan divalidasi - Error handling sudah diimplementasikan - Dictionary result diisi dengan benar - Checkbox Active tercentang
Proses Penyimpanan: - Klik tombol Save untuk membuat tool - Sistem memvalidasi konfigurasi - Tool tersedia segera jika Active tercentang - Tool muncul di daftar seleksi tool AI Agent
Aksi Post-Save: - Test tool di environment development - Dokumentasikan persyaratan atau dependency khusus - Update Skill terkait jika tool adalah bagian dari paket capability - Monitor penggunaan awal melalui record AI Agent Run
7. Menggunakan Tool di AI Agent
Penugasan Tool Langsung: - Buka record AI Agent - Navigasi ke section Tools - Klik Add Row di tabel Tools - Pilih tool Anda dari dropdown - Simpan agent untuk mengaktifkan tool
Penugasan via Skill: - Buka record TM AI Skill - Navigasi ke section Skill Tools - Pilih tool Anda di field Table MultiSelect - Simpan skill - Tugaskan skill ke AI Agent yang relevan
Alur Eksekusi Tool: - AI Agent menganalisis permintaan user - Agent menentukan tool mana yang digunakan berdasarkan description - Agent menyiapkan parameter input sesuai input schema - Script tool dieksekusi dengan parameter yang diberikan - Hasil dikembalikan via dictionary result - Agent menggunakan hasil untuk merumuskan respons atau aksi berikutnya
Best Practice
Prinsip Desain Tool
Single Responsibility: - Setiap tool harus melakukan satu aksi spesifik yang terdefinisi dengan baik - Hindari membuat tool multi-purpose yang melakukan terlalu banyak hal - Pecah operasi kompleks menjadi beberapa tool yang terkoordinasi
Penamaan yang Jelas: - Gunakan pola verb-noun yang deskriptif (createcustomer, sendemail) - Nama harus langsung menyampaikan apa yang dilakukan tool - Jaga nama tetap ringkas tapi tidak ambigu - Ikuti konvensi penamaan yang konsisten di semua tool
Idempotency: - Desain tool agar aman ketika dipanggil berkali-kali - Periksa apakah operasi sudah selesai sebelum mengeksekusi - Kembalikan status yang sesuai jika tidak perlu aksi - Cegah pembuatan data duplikat
Validasi Input: - Validasi semua input di awal script - Periksa tipe data, format, dan constraint - Verifikasi dokumen yang direferensikan ada - Berikan pesan error yang jelas untuk input tidak valid
Best Practice Pengembangan Script
Organisasi Kode: - Kelompokkan operasi terkait secara logis - Beri komentar pada logika kompleks untuk maintainability - Gunakan indentasi dan formatting yang konsisten - Jaga script tetap ringkas dan fokus
Error Handling: - Gunakan blok try-except untuk operasi berisiko - Berikan pesan error yang bermakna - Log error dengan tepat menggunakan frappe.log_error() - Fail dengan anggun tanpa mengekspos detail sensitif
Penggunaan API Frappe: - Gunakan frappe.getall() daripada getlist() untuk performa lebih baik - Tentukan field yang diperlukan daripada mengambil dokumen penuh - Gunakan filter secara efektif untuk mengurangi pengambilan data - Manfaatkan sistem validasi dan permission built-in Frappe
Manajemen Permission: - Gunakan ignore_permissions=True dengan bijaksana - Implementasikan pemeriksaan permission kustom saat bypass permission sistem - Dokumentasikan persyaratan permission dalam description tool - Pertimbangkan implikasi keamanan dari semua operasi
Optimisasi Performa
Akses Data Efisien: - Minimalkan query database - Ambil hanya field yang diperlukan - Gunakan filter yang sesuai untuk membatasi result set - Cache data yang sering diakses
Batch Processing: - Proses beberapa record bersama jika memungkinkan - Gunakan bulk operations untuk performa lebih baik - Pertimbangkan pagination untuk dataset besar - Monitor waktu eksekusi dan optimisasi bottleneck
Manajemen Resource: - Jaga waktu eksekusi tool di bawah 5 detik jika memungkinkan - Hindari operasi memory-intensive - Bersihkan data temporary - Monitor penggunaan resource di production
Pertimbangan Keamanan
Sanitasi Input: - Sanitasi input HTML menggunakan frappe.sanitize_html() - Validasi dan escape data yang disediakan user - Cegah SQL injection melalui parameterized query - Validasi upload file dan path
Access Control: - Verifikasi user memiliki permission yang diperlukan - Periksa permission level dokumen jika sesuai - Audit operasi sensitif - Log aksi yang relevan dengan keamanan
Proteksi Data: - Jangan pernah log informasi sensitif (password, token) - Mask data sensitif dalam pesan error - Ikuti regulasi privasi data - Enkripsi data sensitif dengan tepat
Audit Trail: - Log eksekusi tool yang signifikan - Lacak siapa yang mengeksekusi tool dan kapan - Monitor pola yang tidak biasa - Pertahankan catatan compliance
Testing dan Deployment
Testing Development: - Test semua skenario input termasuk edge case - Verifikasi error handling bekerja dengan benar - Test dengan volume data realistis - Validasi integrasi dengan tool lain
Environment Staging: - Deploy tool baru ke staging terlebih dahulu - Lakukan user acceptance testing - Verifikasi performa under load - Test dengan skenario bisnis aktual
Deployment Production: - Deploy selama periode low-traffic - Monitor eksekusi tool awalnya - Siapkan rencana rollback - Dokumentasikan deployment dan masalah apa pun
Maintenance Berkelanjutan: - Review performa tool secara berkala - Update tool seiring kebutuhan bisnis berubah - Deprecate tool yang tidak digunakan - Jaga dokumentasi tetap current
Kolaborasi dan Dokumentasi
Standar Tim: - Tetapkan konvensi penamaan - Definisikan standar coding untuk script - Dokumentasikan tujuan dan use case tool - Bagikan best practice di seluruh tim
Version Control: - Lacak perubahan pada script tool - Dokumentasikan mengapa perubahan dibuat - Pertahankan riwayat perubahan - Gunakan commit message yang bermakna
Knowledge Sharing: - Dokumentasikan pertimbangan khusus - Bagikan pelajaran yang dipelajari - Buat library tool internal - Latih anggota tim tentang penggunaan tool
Pemecahan Masalah
Masalah Umum
Tool Tidak Muncul di List: - Verifikasi checkbox Active tercentang - Periksa nama tool unik - Refresh halaman atau form - Bersihkan browser cache jika diperlukan
Error Validasi: - Pastikan semua parameter wajib disediakan - Periksa nama parameter cocok persis dengan input schema - Verifikasi tipe data benar - Review logika validasi dalam script
Error Permission Denied: - Periksa user memiliki role yang diperlukan - Verifikasi permission dokumen - Gunakan ignore_permissions=True jika sesuai - Review pemeriksaan permission kustom
Kegagalan Eksekusi Script: - Periksa Error Log untuk pesan error detail - Verifikasi sintaks benar (tanpa import, return, dll.) - Test di System Console terlebih dahulu - Review variable konteks yang tersedia
Hasil Tidak Dikembalikan: - Pastikan dictionary result diisi - Gunakan key standar (_created, _updated, dll.) - Periksa exception script - Verifikasi tidak ada statement return yang digunakan
Strategi Debugging
Enable Detailed Logging: - Tambahkan statement debug log dalam script - Gunakan frappe.log_error() untuk masalah kompleks - Periksa Background Jobs untuk eksekusi async - Review record AI Agent Run
Isolasi Masalah: - Test tool secara independen di System Console - Hapus logika kompleks sementara - Test dengan input minimal terlebih dahulu - Tambahkan logging di setiap langkah
Verifikasi Konfigurasi: - Periksa input schema cocok dengan ekspektasi script - Verifikasi tool ditugaskan ke agent dengan benar - Pastikan semua dependency tersedia - Review context dan settings agent
Dokumentasi Terkait
- TM AI Agent - Konfigurasi dan eksekusi agent utama
- TM AI Skill - Paket tool dan context bersama
- TM AI Context - Menyediakan pengetahuan ke agent
- Arsitektur AI Agent Loop - Memahami alur eksekusi agent
- Dokumentasi Frappe Framework - API dan method framework inti