Bir ajanın araç bağlamını ayarlama

Bu kılavuz, iki katmanlı araç yüzeyi etrafındaki pratik işleri kapsar: bir çalıştırmanın ne gönderdiğini görmek, bunu değiştirmek ve yanlış araca uzanan bir ajanı tanılamak. Bunun neden böyle çalıştığını okumak için Araç bağlamı ve istem önbelleği sayfasına bakın.

Bir çalıştırmanın gerçekte ne gönderdiğine bakın

Bir konuşma açın ve konuşma başlığındaki bağlam kullanımı göstergesine dokunun. Hiçbir şey çalıştırmadan, bir sonraki gönderimin göndereceği yüzeyin aynısını yeniden oluşturur. Daha fazlasını gör (veya /context komutu) her aracı inceleyebileceğiniz tam bağlam gezginini açar.

Burada iki segment önemlidir:

• Araç tanımları ve MCP ve dinamik araçlar — her aracın gerçek token maliyetiyle birlikte yerleşik küme.
• İstek üzerine yüklenen araçlar — ertelenmiş dizin. Her girdi için yalnızca adı ücretlendirilir, çünkü isteğin taşıdığı tek şey bir addır; birini açtığınızda yine tam açıklama ve şema gösterilir, böylece çalıştırma onu içeri çekseydi ne kadar mal olacağını görebilirsiniz.

Ertelenmiş segment boşsa, bu sunucuda istek üzerine yükleme kapalıdır. cc_server CLI üzerindeki --tool-deferral seçeneğine bakın.

Hangi araçların baştan yüklendiğini değiştirin

Yerleşik küme yapılandırma değil politikadır — ModeToolPolicy içinde yaşar (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) ve her çalıştırmaya uygulanır:

• residentBuiltins — dosya ve kabuk sözcük dağarcığı.
• residentDiscovery — search_tools ve list_my_tools. Bunları kaldırmayın; bir ajanın diğer her şeye ulaşma yolu bunlardır.
• residentMcpTools — her istekte şemasına değen bir avuç Control Center aracı.
• Belirli bir modun neredeyse her turda kullandığı araçlar için mod başına bir blok.

Onu düzenlerken iki kural:

Bir aracı yalnızca çalıştırmaların çoğu onu kullanıyorsa ekleyin. Her ad, sonsuza dek her çalıştırmanın her isteğinde şemasının bedelini ödetir. Kullanıldığında önemli olan ama genel olarak seyrek görülen bir araç ertelenmiş yarıya aittir — ajan onu yine de bulur.

Aracın gerçek adını kullanın. Hiçbir araçla eşleşmeyen yerleşik bir ad etkisizdir: hata yok, uyarı yok, araç yalnızca ertelenir. test/tooling/resident_tool_names_test.dart bunu yakalar ve ayrıca her modu 40 yerleşik aracın altında tutar; asıl amaç da budur — bu bandın ötesinde araç seçimi ölçülebilir biçimde bozulur.

Bir modun zorunlu ve sabitlenmiş fiilleri otomatik olarak eklenir, böylece bir modun kendi çıktı fiilini hiçbir zaman listelemek zorunda kalmazsınız.

Hatalı bir araç seçimini tanılayın

Bir ajan yanlış aracı kullandığında ya da bir şeyi yapamadığını söylediğinde, üç şeyden hangisinin olduğunu belirleyin.

1. Aradı mı?

Her çalıştırma, yüklediği ertelenmiş araçları ve bunu neyin tetiklediğini kaydeder — ada göre doğrudan bir çağrı ya da bir search_tools sorgusu. Çalıştırmanın olay akışını açın (Ayarlar → Çalışma alanı → Ajanlar → ajan → Loglar → Görünüm) ve [harness] loaded N deferred tool(s) ifadesini arayın.

• Hiçbir şey kaydedilmemiş ve ajan yeteneğin eksik olduğunu söylemiş — hiç aramamıştır. Bu bir erişim değil istem sorunudur: ertelenmiş dizin, bir arama boş dönene kadar bir yeteneğin eksik olduğunu bildirmemesini söyleyen bir yönergeyle birlikte ajanın sistem isteminde bulunur.
• Bir arama kaydedilmiş ama hiçbir şey yüklenmemiş — gerçek bir erişim ıskası. 2. adıma geçin.
• Araçlar yüklenmiş ama yanlış olan kullanılmış — bulduğu araçlar birbirine fazla benziyor. 3. adıma geçin.

2. Erişim ıskasını düzeltin

search_tools adlara, açıklamalara ve argüman adlarına göre eşleştirir. Bir ıska neredeyse her zaman, açıklamanın ajanın kullandığı sözcükleri içermediği anlamına gelir.

Bu sözcükleri ekleyin. Açıklamalar erişim dizinidir, bu yüzden kısaltmak yerine uzatın — yalnızca içsel ismi değil, bir operatörün gerçekte yazacağı sözcükleri (“assign”, “hand off”, “give to”) yazın. Token tasarrufu için bir açıklamayı kısaltmak size hem arama isabetini hem de seçim doğruluğunu kaybettirir ve şemanın yanında neredeyse hiçbir şey kazandırmaz.

Doğru araç varsa ama düşük sırada kalıyorsa, limit argümanı tam da bunun içindir; aracın kendi açıklaması, yakın görünen ama ıskalayan bir aramayı genişletmesini söyler.

3. Birbirine benzeyen araçları düzeltin

İki aracın açıklamaları, aradaki farkı zaten bilmeyen biri için aynı okunuyorsa, model tahmin yürütüyordur. Bunları ayırt edici bir argümanla tek bir araçta birleştirin.

ticket_relation ve ticket_pr_link bu kalıbı izler: her biri bağlama ve bağlantıyı çözmeyi ayırt edici bir argüman üzerinden yürütür. İsteğin tüm bağlamıyla, tek bir çağrının içinde verilen bir karar, birbirine benzeyen iki açıklama arasında verilen bir karardan daha güvenilirdir.

Farklı onay kapılarına, farklı denetime veya farklı işlemeye ihtiyaç duyduklarında araçları ayrı tutun — bunlar, birleştirmenin size gerçek bir bedel ödeteceği nedenlerdir.

İstem önbelleğinin çalıştığını doğrulayın

Önbellek isabet oranı, Gözlemlenebilirlik → İçgörüler altında Önbellek oranı olarak görünür. Sağlıklı, uzun süren bir konuşma yüksek seyreder; sürekli düşükse, her turda öneki bir şey yeniden yazıyordur.

Olasılık sırasına göre yaygın nedenler:

• İstemin başındaki belirlenimsiz her şey. Bir zaman damgası, bir istek kimliği ya da değişen sırayla yinelenen bir küme bunu yapmaya yeter.
• Konuşmanın ortasında bir model veya efor değişikliği. Her ikisi de öneki değiştirir. Alt ajanlarda bu özellikle kolayca hata yapılır: para tasarrufu için alt süreçleri daha düşük eforda çalıştırmak, kaybedilen önbellek paylaşımı nedeniyle tasarruf ettiğinden daha fazlaya mal olabilir.
• Sık sıkıştırma. Sıkıştırma, tasarımı gereği geçmişi yeniden yazar, dolayısıyla maliyeti gerçektir; çözüm, sık ve sığ yerine seyrek ve derin sıkıştırmaktır.

İstek üzerine yüklemeyi --tool-deferral=off ile kapatmak, bir davranış değişikliğinin iki katmanlı yüzeyden gelip gelmediğini yalıtmak için geçerli bir A/B’dir. İstek üzerine yükleme öncesi isteği tam olarak yeniden üretir; dolayısıyla kapalıyken davranış sürüyorsa, neden bu yüzey değildir.