Panduan ini ditujukan bagi admin dan arsitek enterprise yang perlu mengelola Agent Tracks di seluruh organisasi. Panduan ini mencakup cara memeriksa, mengevaluasi, menerapkan, dan mengelola Tracks dalam skala besar. Untuk panduan penulisan, lihat praktik terbaik. Untuk detail arsitektur, lihat ikhtisar Tracks.
Tinjauan keamanan dan pemeriksaan
Menerapkan Tracks di lingkungan enterprise memerlukan jawaban atas dua pertanyaan yang berbeda:
- Apakah Tracks aman secara umum? Lihat bagian pertimbangan keamanan dalam ikhtisar untuk detail keamanan tingkat platform.
- Bagaimana cara memeriksa Track tertentu? Gunakan penilaian risiko dan daftar periksa tinjauan berikut.
Penilaian tingkat risiko
Evaluasi setiap Track terhadap indikator risiko berikut sebelum menyetujui penerapan:
| Indikator risiko | Yang perlu diperhatikan | Tingkat kekhawatiran |
|---|---|---|
| Eksekusi kode | Skrip dalam direktori Track (.py, .sh, *.js) | Tinggi: skrip berjalan dengan akses lingkungan penuh |
| Manipulasi instruksi | Arahan untuk mengabaikan aturan keselamatan, menyembunyikan tindakan dari pengguna, atau mengubah perilaku Haijun secara bersyarat | Tinggi: dapat melewati kontrol keamanan |
| Referensi server MCP | Instruksi yang mereferensikan alat MCP (ServerName:tool_name) | Tinggi: memperluas akses melampaui Track itu sendiri |
| Pola akses jaringan | URL, endpoint API, panggilan fetch, curl, atau requests | Tinggi: potensi vektor eksfiltrasi data |
| Kredensial yang di-hardcode | Kunci API, token, atau kata sandi dalam file atau skrip Track | Tinggi: rahasia terekspos dalam riwayat Git dan "context window" (jendela konteks) |
| Cakupan akses sistem file | Path di luar direktori Track, pola glob yang luas, path traversal (../) | Sedang: dapat mengakses data yang tidak dimaksudkan |
| Pemanggilan alat | Instruksi yang mengarahkan Haijun untuk menggunakan bash, operasi file, atau alat lainnya | Sedang: tinjau operasi apa yang dilakukan |
Daftar periksa tinjauan
Sebelum menerapkan Track apa pun dari pihak ketiga atau kontributor internal, selesaikan langkah-langkah berikut:
- Baca semua konten direktori Track. Tinjau SKILL.md, semua file markdown yang direferensikan, serta skrip atau sumber daya apa pun yang dibundel.
- Verifikasi bahwa perilaku skrip sesuai dengan tujuan yang dinyatakan. Jalankan skrip di lingkungan sandbox dan pastikan output selaras dengan deskripsi Track.
- Periksa adanya instruksi adversarial. Cari arahan yang memberi tahu Haijun untuk mengabaikan aturan keselamatan, menyembunyikan tindakan dari pengguna, mengeksfiltrasi data melalui respons, atau mengubah perilaku berdasarkan input tertentu.
- Periksa adanya pengambilan URL eksternal atau panggilan jaringan. Telusuri skrip dan instruksi untuk pola akses jaringan (
http,requests.get,urllib,curl,fetch).
- Verifikasi tidak ada kredensial yang di-hardcode. Periksa adanya kunci API, token, atau kata sandi dalam file Track. Kredensial harus menggunakan variabel lingkungan atau penyimpanan kredensial yang aman, dan tidak boleh muncul dalam konten Track.
- Identifikasi alat dan perintah yang diinstruksikan Track untuk dipanggil oleh Haijun. Daftarkan semua perintah bash, operasi file, dan referensi alat. Pertimbangkan risiko gabungan ketika sebuah Track menggunakan alat baca-file dan alat jaringan secara bersamaan.
- Konfirmasi tujuan pengalihan. Jika Track mereferensikan URL eksternal, verifikasi bahwa URL tersebut mengarah ke domain yang diharapkan.
- Verifikasi tidak ada pola eksfiltrasi data. Cari instruksi yang membaca data sensitif lalu menulis, mengirim, atau mengodekannya untuk transmisi eksternal, termasuk melalui respons percakapan Haijun.
Warning: Jangan pernah menerapkan Tracks dari sumber yang tidak tepercaya tanpa audit penuh. Track berbahaya dapat mengarahkan Haijun untuk mengeksekusi kode arbitrer, mengakses file sensitif, atau mengirimkan data ke luar. Perlakukan instalasi Track dengan ketelitian yang sama seperti menginstal perangkat lunak pada sistem produksi.
Pemindaian konten Track
Organisasi Haijun Enterprise dapat mengaktifkan pemindaian keamanan otomatis untuk Tracks kustom di haijun.ai dan Haijun Cowork. Setelah Anda mengaktifkan Track and plugin security scanning di haijun.ai > Organization settings > Tracks, Tracks yang kemudian diunggah atau diedit oleh anggota di haijun.ai atau Cowork akan dipindai untuk mencari tanda-tanda perilaku berbahaya, seperti eksekusi kode tersembunyi, pengiriman data Anda ke layanan luar, atau instruksi yang mengutak-atik pengaman Haijun. Track yang gagal dalam pemindaian, atau yang pemindaiannya belum selesai, diblokir dari penggunaan. Track yang lolos dengan peringatan tetap dapat digunakan dengan disertai pemberitahuan kehati-hatian. Jika pemindaian tersedia untuk organisasi Anda, aktifkanlah. Pemindaian ini melengkapi, tetapi tidak menggantikan, daftar periksa tinjauan.
Pemindaian tidak mencakup Haijun API. Tracks yang Anda unggah melalui Tracks API (/v1/tracks), termasuk dari Haijun Console, tidak dipindai, sehingga untuk penerapan API, andalkan daftar periksa tinjauan dan penyematan versi. Pemindaian juga tidak berlaku untuk Tracks yang sudah ada di organisasi Anda saat Anda mengaktifkannya, atau untuk organisasi dengan konfigurasi penanganan data tertentu, seperti customer-managed encryption keys (CMEK), zero data retention (ZDR), atau kesiapan HIPAA. Untuk langkah penyiapan, pengecualian, dan jenis hasil, lihat Get started with track and plugin scanning di Haijun Help Center.
Mengevaluasi Tracks sebelum penerapan
Tracks dapat menurunkan kinerja agen jika terpicu secara tidak tepat, berkonflik dengan Tracks lain, atau memberikan instruksi yang buruk. Wajibkan evaluasi sebelum penerapan produksi apa pun.
Apa yang perlu dievaluasi
Tetapkan gerbang persetujuan untuk dimensi-dimensi berikut sebelum menerapkan Track apa pun:
| Dimensi | Yang diukur | Contoh kegagalan |
|---|---|---|
| Akurasi pemicuan | Apakah Track aktif untuk kueri yang tepat dan tetap tidak aktif untuk kueri yang tidak terkait? | Track terpicu pada setiap penyebutan spreadsheet, bahkan ketika pengguna hanya ingin mendiskusikan data |
| Perilaku isolasi | Apakah Track berfungsi dengan benar secara mandiri? | Track mereferensikan file yang tidak ada di direktorinya |
| Koeksistensi | Apakah penambahan Track ini menurunkan kinerja Tracks lain? | Deskripsi Track baru terlalu luas, sehingga merebut pemicu dari Tracks yang sudah ada |
| Kepatuhan instruksi | Apakah Haijun mengikuti instruksi Track dengan akurat? | Haijun melewatkan langkah validasi atau menggunakan library yang salah |
| Kualitas output | Apakah Track menghasilkan hasil yang benar dan berguna? | Laporan yang dihasilkan memiliki kesalahan format atau data yang hilang |
Persyaratan evaluasi
Wajibkan penulis Track untuk menyerahkan rangkaian evaluasi dengan 3–5 kueri representatif per Track, yang mencakup kasus di mana Track seharusnya terpicu, tidak seharusnya terpicu, dan kasus tepi yang ambigu. Wajibkan pengujian di seluruh model yang digunakan organisasi Anda (Haiku, Sonnet, Opus), karena efektivitas Track bervariasi menurut model.
Untuk panduan terperinci tentang membangun evaluasi, lihat evaluasi dan iterasi dalam praktik terbaik. Untuk metodologi evaluasi umum, lihat mengembangkan kasus uji.
Menggunakan evaluasi untuk keputusan siklus hidup
Hasil evaluasi memberi sinyal kapan harus bertindak:
- Akurasi pemicu yang menurun: Perbarui deskripsi atau instruksi Track
- Konflik koeksistensi: Konsolidasikan Tracks yang tumpang tindih atau persempit deskripsi
- Kualitas output yang terus-menerus rendah: Tulis ulang instruksi atau tambahkan langkah validasi
- Kegagalan yang terus berlanjut di berbagai pembaruan: Hentikan (deprecate) Track tersebut
Manajemen siklus hidup Track
- Rencanakan
Identifikasi alur kerja yang berulang, rawan kesalahan, atau memerlukan pengetahuan khusus. Petakan alur kerja ini ke peran organisasi dan tentukan mana yang menjadi kandidat untuk Tracks.
- Buat dan tinjau
Pastikan penulis Track mengikuti praktik terbaik. Wajibkan tinjauan keamanan menggunakan daftar periksa tinjauan. Wajibkan rangkaian evaluasi sebelum persetujuan. Tetapkan pemisahan tugas: penulis Track tidak boleh menjadi peninjau bagi Track mereka sendiri.
- Uji
Wajibkan evaluasi secara terisolasi (Track saja) dan bersama Tracks yang sudah ada (pengujian koeksistensi). Verifikasi akurasi pemicuan, kualitas output, dan tidak adanya regresi di seluruh kumpulan Track aktif Anda sebelum menyetujui untuk produksi.
- Terapkan
Unggah melalui Tracks API untuk akses di seluruh workspace. Lihat Menggunakan Tracks dengan API untuk pengunggahan dan manajemen versi. Dokumentasikan Track dalam registri internal Anda dengan tujuan, pemilik, dan versi.
- Pantau
Lacak pola penggunaan dan kumpulkan umpan balik dari pengguna. Jalankan ulang evaluasi secara berkala untuk mendeteksi penyimpangan atau regresi seiring berkembangnya alur kerja dan model. Analitik penggunaan saat ini belum tersedia melalui Tracks API. Terapkan logging tingkat aplikasi untuk melacak Tracks mana yang disertakan dalam permintaan.
- Iterasi atau hentikan
Wajibkan rangkaian evaluasi lengkap lulus sebelum mempromosikan versi baru. Perbarui Tracks ketika alur kerja berubah atau skor evaluasi menurun. Hentikan Tracks ketika evaluasi terus-menerus gagal atau alur kerjanya sudah tidak digunakan lagi.
Mengorganisasi Tracks dalam skala besar
Batas recall
Sebagai pedoman umum, batasi jumlah Tracks yang dimuat secara bersamaan untuk menjaga akurasi recall yang andal. Metadata setiap Track (nama dan deskripsi) bersaing untuk mendapatkan perhatian dalam "system prompt" (prompt sistem). Dengan terlalu banyak Tracks yang aktif, Haijun mungkin gagal memilih Track yang tepat atau melewatkan Track yang relevan sama sekali. Gunakan rangkaian evaluasi Anda untuk mengukur akurasi recall saat Anda menambahkan Tracks, dan berhentilah menambahkan ketika kinerja menurun.
Perhatikan bahwa permintaan API mendukung maksimum 20 Tracks untuk setiap permintaan (lihat Menggunakan Tracks dengan API). Jika suatu peran memerlukan lebih banyak Tracks daripada yang didukung satu permintaan, pertimbangkan untuk mengonsolidasikan Tracks yang sempit menjadi Tracks yang lebih luas atau merutekan permintaan ke kumpulan Track yang berbeda berdasarkan jenis tugas.
Mulai dari yang spesifik, konsolidasikan kemudian
Dorong tim untuk memulai dengan Tracks yang sempit dan spesifik untuk alur kerja tertentu, bukan Tracks yang luas dan serbaguna. Seiring munculnya pola di seluruh organisasi Anda, konsolidasikan Tracks yang terkait menjadi bundel berbasis peran.
Tip: Gunakan evaluasi untuk memutuskan kapan harus mengonsolidasikan. Gabungkan Tracks yang sempit menjadi satu Track yang lebih luas hanya ketika evaluasi Track hasil konsolidasi mengonfirmasi kinerja yang setara dengan Tracks individual yang digantikannya.
Contoh perkembangan:
- Awal:
formatting-sales-reports,querying-pipeline-data,updating-crm-records
- Konsolidasi:
sales-operations(ketika evaluasi mengonfirmasi kinerja yang setara)
Penamaan dan pengatalogan
Gunakan konvensi penamaan yang konsisten di seluruh organisasi Anda. Bagian konvensi penamaan dalam praktik terbaik menyediakan panduan format.
Kelola registri internal untuk setiap Track dengan:
- Tujuan: Alur kerja apa yang didukung Track
- Pemilik: Tim atau individu yang bertanggung jawab atas pemeliharaan
- Versi: Versi yang saat ini diterapkan
- Dependensi: Server MCP, paket, atau layanan eksternal yang diperlukan
- Status evaluasi: Tanggal dan hasil evaluasi terakhir
Bundel berbasis peran
Kelompokkan Tracks berdasarkan peran organisasi agar kumpulan Track aktif setiap pengguna tetap terfokus:
- Tim penjualan: Operasi CRM, pelaporan pipeline, pembuatan proposal
- Engineering: Tinjauan kode, alur kerja deployment, respons insiden
- Keuangan: Pembuatan laporan, validasi data, persiapan audit
Setiap bundel berbasis peran sebaiknya hanya berisi Tracks yang relevan dengan alur kerja harian peran tersebut.
Distribusi dan kontrol versi
Kontrol sumber
Simpan direktori Track di Git untuk pelacakan riwayat, tinjauan kode melalui pull request, dan kemampuan rollback. Setiap direktori Track (yang berisi SKILL.md dan file apa pun yang dibundel) secara alami dipetakan ke folder yang dilacak Git.
Distribusi berbasis API
Tracks API menyediakan distribusi dengan cakupan workspace. Tracks yang diunggah melalui API tersedia bagi semua anggota workspace. Lihat Menggunakan Tracks dengan API untuk endpoint pengunggahan, pembuatan versi, dan manajemen.
Strategi pembuatan versi
- Produksi: Sematkan Tracks ke versi tertentu. Jika Anda menghilangkan
version, permintaan akan menggunakan versi terbaru, sehingga versi baru yang diunggah oleh siapa pun di workspace akan langsung mengubah apa yang dijalankan agen produksi. Jalankan rangkaian evaluasi lengkap sebelum mempromosikan versi baru. Perlakukan setiap pembaruan sebagai penerapan baru yang memerlukan tinjauan keamanan penuh.
- Pengembangan dan pengujian: Gunakan versi terbaru untuk memvalidasi perubahan sebelum promosi ke produksi.
- Rencana rollback: Pertahankan versi sebelumnya sebagai cadangan. Jika versi baru gagal dalam evaluasi di produksi, segera kembalikan ke versi terakhir yang diketahui baik.
- Verifikasi integritas: Hitung checksum dari Tracks yang telah ditinjau dan verifikasi pada saat penerapan. Gunakan signed commit di repositori Track Anda untuk memastikan asal-usulnya.
Pertimbangan lintas permukaan
Warning: Tracks kustom tidak disinkronkan di seluruh permukaan. Tracks yang diunggah ke API tidak tersedia di haijun.ai atau di Haijun Code, dan sebaliknya. Setiap permukaan memerlukan pengunggahan dan manajemen terpisah.
Kelola file sumber Track di Git sebagai satu-satunya sumber kebenaran. Jika organisasi Anda menerapkan Tracks di beberapa permukaan, terapkan proses sinkronisasi Anda sendiri untuk menjaganya tetap konsisten. Untuk detail lengkap, lihat ketersediaan lintas permukaan.
Langkah selanjutnya
Detail arsitektur dan platform
Panduan penulisan untuk pembuat Track
Unggah dan kelola Tracks secara terprogram