Pemecahan Masalah - Amazon Q Developer
Kesalahan konfigurasiMasalah pemuatan agen kustomMasalah izin alatDebugging perilaku agen kustomMendapatkan bantuan tambahan

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Pemecahan Masalah

Bagian ini mencakup masalah umum yang mungkin Anda temui saat bekerja dengan agen khusus dan cara mengatasinya.

Kesalahan konfigurasi

Sintaks JSON tidak valid

Masalah: Agen khusus gagal memuat dengan kesalahan penguraian JSON.

Gejala:

  • Pesan kesalahan yang menyebutkan “JSON tidak valid” atau “kesalahan sintaks”

  • Agen kustom tidak muncul di /agent list

  • Mundur ke perilaku agen default

Solusi:

  • Validasi JSON Anda menggunakan validator atau linter JSON

  • Periksa kesalahan JSON umum:

    • Tanda koma yang hilang antara elemen array atau properti objek

    • Tanda koma setelah elemen terakhir

    • Kurung atau kawat gigi yang tak tertandingi

    • Kutipan yang tidak terlolos dalam nilai string

  • Gunakan /agent schema untuk memverifikasi struktur konfigurasi Anda

Kesalahan validasi skema

Masalah: Konfigurasi agen khusus tidak cocok dengan skema yang diharapkan.

Gejala:

  • Peringatan tentang bidang konfigurasi yang tidak diketahui

  • Perilaku agen kustom tidak cocok dengan konfigurasi

  • Kesalahan bidang wajib hilang

Solusi:

  • Bandingkan konfigurasi Anda dengan skema menggunakan /agent schema

  • Periksa nama bidang untuk kesalahan ketik (mis., allowedTools vsallowedTool)

  • Verifikasi tipe data yang cocok dengan persyaratan skema (array vs string, boolean vs string)

  • Tinjau dokumentasi format agen dalam dokumentasi CLI Pengembang Amazon Q tambahan untuk sintaks yang benar

Masalah pemuatan agen kustom

Agen kustom tidak ditemukan

Masalah: Agen kustom tidak muncul dalam daftar atau tidak dapat digunakan.

Gejala:

  • /agent listtidak menunjukkan agen kustom Anda

  • /agent use [name]gagal dengan “agen tidak ditemukan”

  • Fallback ke agen default tanpa peringatan

Solusi:

  • Verifikasi file agen kustom berada di lokasi yang benar:

    • Global: ~/.aws/amazonq/cli-agents/[name].json

    • Lokal: amazonq/cli-agents/[name].json

  • Periksa izin file - pastikan file dapat dibaca

  • Verifikasi nama file cocok dengan nama agen kustom yang Anda coba gunakan

  • Pastikan file memiliki .json ekstensi

Pemuatan versi agen kustom yang salah

Masalah: Versi berbeda dari agen kustom Anda dimuat dari yang diharapkan.

Gejala:

  • Perilaku agen kustom tidak cocok dengan perubahan konfigurasi terbaru Anda

  • Pesan peringatan tentang konflik agen kustom

  • Ketersediaan atau izin alat yang tidak terduga

Solusi:

  • Periksa konflik nama agen kustom antara direktori lokal dan global

  • Ingat bahwa agen kustom lokal lebih diutamakan daripada agen kustom global

  • Gunakan /agent list untuk melihat versi mana yang sedang dimuat

  • Hapus atau ganti nama file agen kustom yang bertentangan jika perlu

Masalah izin alat

Alat tidak tersedia

Masalah: Agen khusus tidak dapat mengakses alat yang telah Anda konfigurasikan.

Gejala:

  • Pesan galat tentang alat yang tidak dikenal atau tidak tersedia

  • Agen kustom meminta izin untuk alat di allowedTools

  • Alat server MCP tidak berfungsi

Solusi:

  • Verifikasi nama alat dieja dengan benar dalam array tools

  • Untuk alat MCP, pastikan server dikonfigurasi dengan benar mcpServers

  • Periksa apakah server MCP berjalan dan dapat diakses

  • Gunakan sintaks yang benar untuk alat MCP: @server_name/tool_name

  • Verifikasi nama alat bawaan terhadap dokumentasi alat bawaan dalam dokumentasi CLI Pengembang Amazon Q tambahan

/tools perintah mengembalikan daftar kosong

Masalah: /tools Perintah tidak menunjukkan alat yang tersedia atau alat yang lebih sedikit dari yang diharapkan.

Gejala:

  • /toolsmengembalikan daftar kosong

  • Alat yang diharapkan hilang dari daftar alat

  • Agen khusus tampaknya tidak memiliki kemampuan

Penyebab umum:

  • toolsArray kosong dalam konfigurasi agen kustom

  • Kesalahan ketik dalam nama alat dalam array tools

  • Nama alat server MCP salah (awalan server hilang)

  • Masalah konfigurasi server MCP mencegah pemuatan alat

Solusi:

  • Periksa apakah konfigurasi agen kustom Anda menyertakan tools array dengan nama alat yang valid

  • Verifikasi nama alat dieja dengan benar (peka huruf besar/kecil)

  • Untuk alat MCP, pastikan Anda menggunakan format awalan server yang benar: server-name___tool-name

  • Uji dengan agen default untuk mengonfirmasi alat tersedia: q chat lalu /tools

  • Periksa status server MCP jika menggunakan alat eksternal

Permintaan izin yang tidak terduga

Masalah: Agen khusus meminta izin untuk alat yang Anda pikir telah disetujui sebelumnya.

Gejala:

  • Permintaan izin untuk alat yang tercantum dalam allowedTools

  • Gangguan alur kerja meskipun konfigurasi agen khusus

Solusi:

  • Pastikan alat terdaftar di keduanya tools dan allowedTools array

  • Periksa kesalahan ketik pada nama alat di antara dua array

  • Untuk alat MCP, gunakan nama awalan server lengkap di allowedTools

  • Verifikasi toolAliases yang diterapkan dengan benar

Debugging perilaku agen kustom

Konteks atau sumber daya yang hilang

Masalah: Agen khusus tampaknya tidak memiliki akses ke file atau konteks yang diharapkan.

Solusi:

  • Verifikasi jalur file dalam resources array sudah benar dan file ada

  • Periksa apakah pola glob dalam sumber daya cocok dengan file yang dimaksud

  • Pastikan perintah hook dijalankan dengan sukses dan menghasilkan output

  • Uji perintah hook secara manual untuk memverifikasi bahwa perintah tersebut berfungsi di lingkungan Anda

  • Periksa pengaturan batas waktu kait jika perintah sedang terputus

Masalah server MCP

Masalah: Server MCP tidak berfungsi atau alat tidak tersedia.

Solusi:

  • Verifikasi perintah server MCP benar dan executable ada di PATH Anda

  • Periksa apakah variabel lingkungan yang diperlukan disetel

  • Uji server MCP secara independen untuk memastikan mereka bekerja

  • Tinjau log server MCP untuk pesan kesalahan

  • Tingkatkan nilai batas waktu jika server lambat untuk memulai

  • Untuk pemecahan masalah MCP lainnya, lihat Menggunakan MCP dengan Pengembang Amazon Q

Menguji konfigurasi agen kustom

Untuk menguji konfigurasi agen kustom Anda secara sistematis:

  1. Validasi sintaks JSON menggunakan validator JSON

  2. Periksa konfigurasi terhadap skema menggunakan /agent schema

  3. Uji pemuatan agen kustom dengan /agent list

  4. Beralih ke agen kustom dengan /agent use [name]

  5. Uji setiap alat satu per satu untuk memverifikasi akses dan izin

  6. Verifikasi bahwa sumber daya dan kait menyediakan konteks yang diharapkan

  7. Uji alur kerja umum untuk memastikan agen kustom berperilaku seperti yang diharapkan

Mendapatkan bantuan tambahan

Jika Anda terus mengalami masalah dengan agen: