Sesuaikan konteks alat agen

Panduan ini membahas pekerjaan praktis seputar permukaan alat dua tingkat: melihat apa yang dikirim sebuah run, mengubahnya, dan mendiagnosis agen yang meraih alat yang salah. Untuk alasan di balik cara kerjanya, baca Konteks alat dan cache prompt.

Lihat apa yang sebenarnya dikirim sebuah run

Buka percakapan dan ketuk indikator penggunaan konteks di tajuk percakapan. Indikator itu membangun kembali permukaan persis yang akan dikirim pengiriman berikutnya, tanpa menjalankan apa pun. Lihat selengkapnya (atau perintah /context) membuka penjelajah konteks lengkap, tempat Anda dapat memeriksa setiap alat.

Ada dua segmen yang penting di sini:

• Definisi alat dan MCP & alat dinamis — himpunan residen, beserta biaya token sebenarnya dari tiap alat.
• Alat yang dimuat sesuai permintaan — indeks yang ditunda. Setiap entri hanya dikenai biaya namanya, karena hanya nama itulah yang dibawa permintaan; membuka salah satunya tetap menampilkan deskripsi dan skema lengkapnya, sehingga Anda dapat melihat berapa biaya yang akan ditimbulkannya jika run menariknya masuk.

Jika segmen yang ditunda kosong, penundaan dimatikan untuk server ini. Periksa --tool-deferral pada CLI cc_server.

Ubah alat mana yang dimuat lebih dahulu

Himpunan residen adalah kebijakan, bukan konfigurasi — himpunan itu berada di ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) dan berlaku untuk setiap run:

• residentBuiltins — kosakata file dan shell.
• residentDiscovery — search_tools dan list_my_tools. Jangan hapus keduanya; itulah cara agen menjangkau semua alat lainnya.
• residentMcpTools — segelintir alat Control Center yang layak membawa skemanya pada setiap permintaan.
• Blok per mode, untuk alat yang dipakai mode tertentu pada hampir setiap giliran.

Dua aturan saat mengeditnya:

Tambahkan alat hanya jika sebagian besar run memakainya. Setiap nama membebani skemanya pada setiap permintaan dari setiap run, selamanya. Alat yang penting saat dipakai tetapi jarang secara keseluruhan termasuk ke bagian yang ditunda — agen tetap akan menemukannya.

Gunakan nama asli alat itu. Nama residen yang tidak cocok dengan alat mana pun tidak berpengaruh sama sekali: tanpa galat, tanpa peringatan, alat itu sekadar ditunda. test/tooling/resident_tool_names_test.dart menangkap hal ini dan juga menjaga setiap mode di bawah 40 alat residen, dan itulah inti persoalannya — di luar rentang itu, pemilihan alat terdegradasi secara terukur.

Kata kerja yang diwajibkan dan disematkan milik sebuah mode ditambahkan secara otomatis, jadi Anda tidak perlu mencantumkan kata kerja luaran milik mode itu sendiri.

Diagnosis pilihan alat yang buruk

Ketika agen memakai alat yang salah atau mengaku tidak dapat melakukan sesuatu, tentukan mana dari tiga hal berikut yang terjadi.

1. Apakah agen mencarinya?

Setiap run mencatat alat tertunda yang dimuatnya dan apa yang memicunya — panggilan langsung berdasarkan nama, atau kueri search_tools. Buka aliran peristiwa run tersebut (Pengaturan → Ruang kerja → Agen → agen → Log → Lihat) dan cari [harness] loaded N deferred tool(s).

• Tidak ada yang tercatat, dan agen menyatakan kemampuannya tidak ada — agen tidak pernah mencarinya. Itu masalah prompt, bukan masalah pengambilan kembali: indeks yang ditunda ada di prompt sistemnya dengan instruksi untuk tidak menyatakan sebuah kemampuan tidak ada sampai sebuah pencarian kembali dengan hasil kosong.
• Sebuah pencarian tercatat, tetapi tidak ada yang dimuat — kegagalan pengambilan kembali yang sesungguhnya. Lanjut ke langkah 2.
• Alat dimuat, tetapi yang salah yang dipakai — alat yang ditemukannya terlalu mirip. Lanjut ke langkah 3.

2. Perbaiki kegagalan pengambilan kembali

search_tools mencocokkan nama, deskripsi, dan nama argumen. Kegagalan hampir selalu berarti deskripsinya tidak memuat kata-kata yang dipakai agen.

Tambahkan kata-kata itu. Deskripsi adalah indeks pengambilan kembali, jadi panjangkan, jangan pangkas — tulis kosakata yang benar-benar akan diketik operator (“assign”, “hand off”, “give to”), bukan hanya kata benda internalnya. Memangkas deskripsi untuk menghemat token merugikan Anda baik pada keberhasilan pencarian maupun akurasi pemilihan, dan hampir tidak menghemat apa pun dibandingkan skema.

Jika alat yang tepat ada tetapi peringkatnya rendah, di situlah gunanya argumen limit; deskripsi alat itu sendiri memberi tahu agen agar memperluas pencarian yang tampak dekat tetapi meleset.

3. Perbaiki alat yang tampak serupa

Jika dua alat memiliki deskripsi yang akan terbaca sama bagi orang yang belum tahu perbedaannya, model sedang menebak. Gabungkan keduanya menjadi satu alat dengan argumen pembeda.

ticket_relation dan ticket_pr_link mengikuti pola ini: masing-masing menangani penautan dan pelepasan tautan melalui argumen pembeda. Pilihan yang dibuat di dalam satu panggilan, dengan konteks permintaan yang lengkap, lebih andal daripada pilihan yang dibuat di antara dua deskripsi yang tampak serupa.

Biarkan alat tetap terpisah ketika masing-masing memerlukan gerbang persetujuan, audit, atau perenderan yang berbeda — itu alasan penggabungan akan merugikan Anda sesuatu yang nyata.

Pastikan cache prompt berfungsi

Tingkat keberhasilan cache muncul di Observabilitas → Wawasan sebagai Tingkat cache. Percakapan panjang yang sehat berada di angka tinggi; jika angkanya terus rendah, ada sesuatu yang menulis ulang awalannya pada setiap giliran.

Penyebab umum, diurutkan berdasarkan kemungkinannya:

• Apa pun yang non-deterministik di bagian awal prompt. Stempel waktu, id permintaan, atau himpunan yang diiterasi dalam urutan yang berubah-ubah sudah cukup untuk itu.
• Perubahan model atau upaya penalaran di tengah percakapan. Keduanya mengubah awalan. Subagen sangat mudah salah di sini: menjalankan anak pada upaya penalaran yang lebih rendah untuk menghemat uang bisa lebih mahal akibat kehilangan berbagi cache daripada penghematan yang didapat.
• Pemadatan yang sering. Pemadatan menulis ulang riwayat secara sengaja, jadi biayanya nyata; solusinya adalah memadatkan secara jarang dan mendalam, bukan sering dan dangkal.

Menonaktifkan penundaan dengan --tool-deferral=off adalah uji A/B yang sah untuk mengisolasi apakah perubahan perilaku berasal dari permukaan dua tingkat. Opsi itu menghasilkan ulang permintaan sebelum penundaan secara persis, jadi jika perilakunya tetap ada saat penundaan dimatikan, permukaannya bukan penyebabnya.