Ρύθμιση του πλαισίου εργαλείων ενός πράκτορα

Αυτός ο οδηγός καλύπτει την πρακτική εργασία γύρω από την επιφάνεια εργαλείων δύο επιπέδων: να βλέπετε τι στέλνει μια εκτέλεση, να το αλλάζετε και να διαγιγνώσκετε έναν πράκτορα που έκανε λάθος επιλογή εργαλείου. Για το γιατί λειτουργεί έτσι, διαβάστε το Πλαίσιο εργαλείων και προσωρινή αποθήκευση προτροπών.

Δείτε τι στέλνει πραγματικά μια εκτέλεση

Ανοίξτε μια συνομιλία και πατήστε την ένδειξη χρήσης συμφραζομένων στην κεφαλίδα της συνομιλίας. Αναδομεί την ακριβή επιφάνεια που θα έστελνε η επόμενη αποστολή, χωρίς να εκτελέσει τίποτα. Το Δείτε περισσότερα (ή η εντολή /context) ανοίγει τον πλήρη εξερευνητή συμφραζομένων, όπου μπορείτε να εξετάσετε κάθε εργαλείο.

Δύο τμήματα έχουν σημασία εδώ:

• Ορισμοί εργαλείων και MCP και δυναμικά εργαλεία — το μόνιμο σύνολο, με το πραγματικό κόστος token κάθε εργαλείου.
• Εργαλεία κατ’ απαίτηση — το αναβαλλόμενο ευρετήριο. Κάθε καταχώριση χρεώνεται μόνο το όνομά της, γιατί ένα όνομα είναι το μόνο που μεταφέρει το αίτημα· το άνοιγμά της δείχνει ακόμη την πλήρη περιγραφή και το σχήμα, ώστε να δείτε πόσο θα κόστιζε αν η εκτέλεση το τραβούσε μέσα.

Αν το αναβαλλόμενο τμήμα είναι κενό, η αναβολή είναι απενεργοποιημένη για αυτόν τον διακομιστή. Ελέγξτε το --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 αντιστοιχίζει ονόματα, περιγραφές και ονόματα ορισμάτων. Μια αστοχία σημαίνει σχεδόν πάντα ότι η περιγραφή δεν περιέχει τις λέξεις που χρησιμοποίησε ο πράκτορας.

Προσθέστε τις. Οι περιγραφές είναι το ευρετήριο ανάκτησης, οπότε επεκτείνετέ τις αντί να τις κόβετε — γράψτε το λεξιλόγιο που θα πληκτρολογούσε πραγματικά ένας χειριστής («ανάθεσε», «παράδωσε», «δώσε σε»), όχι μόνο το εσωτερικό ουσιαστικό. Το κόψιμο μιας περιγραφής για εξοικονόμηση token σας κοστίζει και την επιτυχία στην αναζήτηση και την ακρίβεια επιλογής, και δεν εξοικονομεί σχεδόν τίποτα δίπλα στο σχήμα.

Αν το σωστό εργαλείο υπάρχει αλλά κατατάσσεται χαμηλά, γι’ αυτό είναι το όρισμα limit· η ίδια η περιγραφή του εργαλείου λέει στον πράκτορα να διευρύνει μια αναζήτηση που φαίνεται κοντά αλλά αστοχεί.

3. Διορθώστε εργαλεία που μοιάζουν μεταξύ τους

Αν δύο εργαλεία έχουν περιγραφές που θα διάβαζε το ίδιο κάποιος που δεν ξέρει ήδη τη διαφορά, το μοντέλο μαντεύει. Συγχωνεύστε τα σε ένα εργαλείο με ένα διακριτικό όρισμα.

Τα ticket_relation και ticket_pr_link ακολουθούν αυτό το μοτίβο: το καθένα χειρίζεται τη σύνδεση και την αποσύνδεση μέσω ενός διακριτικού ορίσματος. Μια επιλογή που γίνεται μέσα σε μία κλήση, με όλα τα συμφραζόμενα του αιτήματος, είναι πιο αξιόπιστη από μια επιλογή ανάμεσα σε δύο περιγραφές που μοιάζουν.

Κρατήστε τα εργαλεία χωριστά όταν χρειάζονται διαφορετική πύλη έγκρισης, διαφορετική καταγραφή ελέγχου ή διαφορετική απόδοση — αυτοί είναι λόγοι για τους οποίους μια συγχώνευση θα σας κόστιζε κάτι πραγματικό.

Ελέγξτε ότι λειτουργεί η cache προτροπών

Το ποσοστό επιτυχιών στην cache εμφανίζεται στην Παρατηρησιμότητα → Στοιχεία ως Ποσοστό cache. Μια υγιής μακροχρόνια συνομιλία κάθεται ψηλά· αν είναι επίμονα χαμηλό, κάτι ξαναγράφει το πρόθεμα σε κάθε στροφή.

Συνήθεις αιτίες, κατά σειρά πιθανότητας:

• Οτιδήποτε μη ντετερμινιστικό νωρίς στην προτροπή. Μια χρονοσφραγίδα, ένα αναγνωριστικό αιτήματος ή ένα σύνολο που διατρέχεται με μεταβαλλόμενη σειρά αρκεί.
• Αλλαγή μοντέλου ή προσπάθειας στη μέση της συνομιλίας. Και τα δύο αλλάζουν το πρόθεμα. Οι υποπράκτορες είναι ιδιαίτερα εύκολο να γίνουν λάθος εδώ: η εκτέλεση παιδιών σε χαμηλότερη προσπάθεια για εξοικονόμηση χρημάτων μπορεί να κοστίσει περισσότερο σε χαμένο διαμοιρασμό cache από όσο εξοικονομεί.
• Συχνή συμπύκνωση. Η συμπύκνωση ξαναγράφει το ιστορικό εκ σχεδιασμού, οπότε το κόστος της είναι πραγματικό· η διόρθωση είναι να συμπυκνώνετε σπάνια και βαθιά αντί συχνά και ρηχά.

Η απενεργοποίηση της αναβολής με --tool-deferral=off είναι ένα έγκυρο A/B για να απομονώσετε αν μια αλλαγή συμπεριφοράς προήλθε από την επιφάνεια δύο επιπέδων. Αναπαράγει ακριβώς το αίτημα πριν από την αναβολή, οπότε αν η συμπεριφορά επιμένει με αυτήν απενεργοποιημένη, η επιφάνεια δεν είναι η αιτία.