ปรับบริบทเครื่องมือของเอเจนต์

คู่มือนี้ครอบคลุมงานภาคปฏิบัติรอบพื้นผิวเครื่องมือสองชั้น: การดูว่าการรันส่งอะไร การเปลี่ยนมัน และการวินิจฉัยเอเจนต์ที่เอื้อมไปหยิบเครื่องมือผิด สำหรับเหตุผลที่มันทำงานแบบนี้ อ่านบริบทเครื่องมือและการแคชพรอมต์

ดูว่าการรันส่งอะไรจริง ๆ

เปิดบทสนทนาแล้วแตะตัวบ่งชี้การใช้บริบทในส่วนหัวของบทสนทนา มันประกอบพื้นผิวเดิมทุกประการที่การสั่งงานครั้งถัดไปจะส่งขึ้นใหม่ โดยไม่รันอะไรเลย ดูเพิ่ม (หรือคำสั่ง /context) เปิดตัวสำรวจบริบทแบบเต็ม ที่คุณตรวจสอบเครื่องมือแต่ละตัวได้

มีสองส่วนที่สำคัญตรงนี้:

• คำจำกัดความเครื่องมือ และ เครื่องมือ MCP และไดนามิก — ชุดประจำ พร้อมต้นทุนโทเค็นจริงของเครื่องมือแต่ละตัว
• เครื่องมือที่โหลดตามต้องการ — ดัชนีที่ถูกหน่วงไว้ แต่ละรายการคิดค่าเพียงชื่อของมัน เพราะคำขอพกมาแค่ชื่อ การเปิดรายการหนึ่งยังคงแสดงคำอธิบายและสคีมาแบบเต็ม คุณจึงเห็นได้ว่ามันจะมีต้นทุนเท่าใดหากการรันดึงมันเข้ามา

หากส่วนที่ถูกหน่วงว่างเปล่า แสดงว่าการหน่วงถูกปิดสำหรับเซิร์ฟเวอร์นี้ ตรวจสอบ --tool-deferral ใน CLI ของ cc_server

เปลี่ยนว่าเครื่องมือใดโหลดล่วงหน้า

ชุดประจำคือนโยบาย ไม่ใช่การตั้งค่า — มันอยู่ใน ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) และใช้กับการรันทุกครั้ง:

• residentBuiltins — คำศัพท์ว่าด้วยไฟล์และเชลล์
• residentDiscovery — search_tools และ list_my_tools อย่าลบสิ่งเหล่านี้ เพราะมันคือวิธีที่เอเจนต์เข้าถึงทุกอย่างอื่น
• residentMcpTools — เครื่องมือ Control Center ไม่กี่ตัวที่คุ้มค่ากับการส่งสคีมาในทุกคำขอ
• บล็อกรายโหมด สำหรับเครื่องมือที่โหมดหนึ่ง ๆ ใช้เกือบทุกเทิร์น

มีสองกฎเมื่อแก้ไขมัน:

เพิ่มเครื่องมือเฉพาะเมื่อการรันส่วนใหญ่ใช้มัน ทุกชื่อมีต้นทุนเท่าสคีมาของมันในทุกคำขอของการรันทุกครั้งตลอดไป เครื่องมือที่สำคัญเมื่อถูกใช้แต่หายากโดยรวมควรอยู่ในครึ่งที่ถูกหน่วงไว้ — เอเจนต์จะยังหามันเจอ

ใช้ชื่อจริงของเครื่องมือ ชื่อประจำที่ไม่ตรงกับเครื่องมือใดเลยจะไม่มีผลอะไร: ไม่มีข้อผิดพลาด ไม่มีคำเตือน เครื่องมือนั้นก็แค่ถูกหน่วงไว้ test/tooling/resident_tool_names_test.dart จับกรณีนี้และยังคุมให้แต่ละโหมดมีเครื่องมือประจำต่ำกว่า 40 ตัว ซึ่งคือจุดประสงค์ของแบบฝึกนี้ — เมื่อพ้นช่วงนั้นไป การเลือกเครื่องมือจะแย่ลงอย่างวัดได้

คำกริยาที่โหมดต้องมีและที่ถูกปักหมุดไว้จะถูกเพิ่มอัตโนมัติ คุณจึงไม่จำเป็นต้องระบุคำกริยาส่งผลลัพธ์ของโหมดเองเลย

วินิจฉัยการเลือกเครื่องมือที่ไม่ดี

เมื่อเอเจนต์ใช้เครื่องมือผิดหรืออ้างว่าทำบางอย่างไม่ได้ ให้หาว่าเกิดจากหนึ่งในสามกรณีใด

1. มันค้นหาหรือไม่

การรันแต่ละครั้งบันทึกเครื่องมือที่ถูกหน่วงไว้ซึ่งมันโหลด และบันทึกว่าอะไรเป็นตัวกระตุ้น — การเรียกตรงด้วยชื่อ หรือคำค้น search_tools เปิดสตรีมเหตุการณ์ของการรัน (การตั้งค่า → เวิร์กสเปซ → เอเจนต์ → เอเจนต์ → บันทึก → ดู) แล้วมองหา [harness] loaded N deferred tool(s)

• ไม่มีอะไรถูกบันทึก และเอเจนต์บอกว่าขีดความสามารถนั้นหายไป — มันไม่เคยค้นหาเลย นั่นคือปัญหาที่พรอมต์ ไม่ใช่ปัญหาการดึงข้อมูล: ดัชนีที่ถูกหน่วงไว้อยู่ในพรอมต์ระบบของมัน พร้อมคำสั่งไม่ให้ประกาศว่าขีดความสามารถใดหายไปจนกว่าการค้นหาจะส่งผลลัพธ์ว่างกลับมา
• บันทึกว่ามีการค้นหา แต่ไม่มีอะไรถูกโหลด — เป็นการพลาดในการดึงข้อมูลจริง ไปที่ขั้นตอนที่ 2
• โหลดเครื่องมือแล้ว แต่ใช้ผิดตัว — เครื่องมือที่มันพบคล้ายกันเกินไป ไปที่ขั้นตอนที่ 3

2. แก้ไขการพลาดในการดึงข้อมูล

search_tools จับคู่จากชื่อ คำอธิบาย และชื่ออาร์กิวเมนต์ การพลาดเกือบทุกครั้งหมายความว่าคำอธิบายไม่มีคำที่เอเจนต์ใช้

เพิ่มคำเหล่านั้นเข้าไป คำอธิบายคือดัชนีสำหรับการดึงข้อมูล ดังนั้นทำให้มันยาวขึ้นแทนที่จะตัดให้สั้นลง — เขียนคำศัพท์ที่ผู้ปฏิบัติงานจะพิมพ์จริง ๆ (“assign”, “hand off”, “give to”) ไม่ใช่แค่คำนามภายใน การตัดคำอธิบายให้สั้นลงเพื่อประหยัดโทเค็นทำให้คุณเสียทั้งการค้นหาที่เคยเจอและความแม่นยำในการเลือก และประหยัดได้แทบไม่มีอะไรเลยเมื่อเทียบกับสคีมา

หากเครื่องมือที่ใช่มีอยู่แต่อันดับต่ำ นั่นคือสิ่งที่อาร์กิวเมนต์ limit มีไว้สำหรับ คำอธิบายของเครื่องมือเองบอกให้เอเจนต์ขยายการค้นหาที่ดูใกล้เคียงแต่ไม่พบ

3. แก้ไขเครื่องมือที่หน้าตาคล้ายกัน

หากเครื่องมือสองตัวมีคำอธิบายที่คนซึ่งไม่รู้ความต่างอยู่แล้วจะอ่านว่าเหมือนกัน โมเดลก็กำลังเดา ให้รวมมันเป็นเครื่องมือเดียวที่มีอาร์กิวเมนต์แยกแยะ

ticket_relation และ ticket_pr_link ทำตามรูปแบบนี้: แต่ละตัวจัดการการเชื่อมและการยกเลิกเชื่อมผ่านอาร์กิวเมนต์แยกแยะ การเลือกที่ทำภายในการเรียกครั้งเดียว โดยมีบริบทเต็มของคำขอ เชื่อถือได้มากกว่าการเลือกที่ทำระหว่างคำอธิบายสองอันที่หน้าตาคล้ายกัน

เก็บเครื่องมือไว้แยกกันเมื่อมันต้องใช้การควบคุมการอนุมัติ การตรวจสอบ หรือการแสดงผลที่ต่างกัน — นั่นคือเหตุผลที่การรวมเข้าด้วยกันจะทำให้คุณเสียสิ่งที่มีค่าจริง

ตรวจสอบว่าแคชพรอมต์ทำงานอยู่

อัตราการเข้าแคชแสดงอยู่ใน การสังเกตการณ์ → ข้อมูลเชิงลึก เป็น อัตราแคช บทสนทนายาว ๆ ที่สุขภาพดีจะอยู่ในระดับสูง หากมันต่ำอย่างต่อเนื่อง แสดงว่ามีบางอย่างเขียนคำนำหน้าขึ้นใหม่ทุกเทิร์น

สาเหตุที่พบบ่อย เรียงตามความเป็นไปได้:

• สิ่งใดก็ตามที่ไม่เป็นดีเทอร์มินิสติกตอนต้นพรอมต์ ไทม์สแตมป์ รหัสคำขอ หรือเซตที่วนซ้ำในลำดับที่แปรผัน ก็ทำให้เกิดได้
• การเปลี่ยนโมเดลหรือระดับความพยายามกลางบทสนทนา ทั้งสองอย่างเปลี่ยนคำนำหน้า ซับเอเจนต์เป็นจุดที่พลาดได้ง่ายเป็นพิเศษตรงนี้: การรันเอเจนต์ลูกด้วยความพยายามที่ต่ำลงเพื่อประหยัดเงินอาจเสียมากกว่าที่ประหยัดได้จากการแชร์แคชที่หายไป
• การบีบอัดบ่อยครั้ง การบีบอัดเขียนประวัติใหม่โดยการออกแบบ ต้นทุนของมันจึงเป็นของจริง วิธีแก้คือบีบอัดให้นาน ๆ ครั้งและลึก แทนที่จะบ่อยและตื้น

การปิดการหน่วงด้วย --tool-deferral=off เป็นการทดสอบ A/B ที่ใช้ได้เพื่อแยกว่าการเปลี่ยนพฤติกรรมมาจากพื้นผิวสองชั้นหรือไม่ มันสร้างคำขอก่อนมีการหน่วงขึ้นมาใหม่ได้อย่างแม่นยำ ดังนั้นหากพฤติกรรมยังคงอยู่เมื่อปิดมัน พื้นผิวก็ไม่ใช่สาเหตุ