Ajustează contextul de instrumente al unui agent

Acest ghid acoperă munca practică din jurul suprafeței de instrumente pe două niveluri: să vezi ce trimite o rulare, să o schimbi și să diagnostichezi un agent care a apucat instrumentul greșit. Pentru explicația din spate, citește Contextul instrumentelor și cache-ul prompturilor.

Uită-te la ce trimite de fapt o rulare

Deschide o conversație și apasă indicatorul de utilizare a contextului din antetul conversației. Acesta reconstruiește exact suprafața pe care ar trimite-o următoarea trimitere, fără să ruleze nimic. Vezi mai mult (sau comanda /context) deschide exploratorul complet de context, unde poți inspecta fiecare instrument.

Două segmente contează aici:

• Definiții de instrumente și Instrumente MCP și dinamice — setul rezident, cu costul real în tokeni al fiecărui instrument.
• Instrumente încărcate la cerere — indexul amânat. Fiecărei intrări i se percepe doar numele, pentru că doar numele este tot ce cară cererea; deschiderea unei intrări arată totuși descrierea și schema completă, ca să vezi cât ar costa dacă rularea ar trage instrumentul înăuntru.

Dacă segmentul amânat este gol, amânarea este dezactivată pentru acest server. Verifică --tool-deferral la CLI-ul cc_server.

Schimbă ce instrumente se încarcă de la început

Setul rezident este politică, nu configurare — trăiește în ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) și se aplică fiecărei rulări:

• residentBuiltins — vocabularul de fișiere și shell.
• residentDiscovery — search_tools și list_my_tools. Nu le elimina; ele sunt calea prin care un agent ajunge la orice altceva.
• residentMcpTools — mâna de instrumente Control Center care merită schema lor la fiecare cerere.
• Un bloc pentru fiecare mod, pentru instrumentele pe care un anumit mod le folosește aproape la fiecare tură.

Două reguli când îl editezi:

Adaugă un instrument doar dacă majoritatea rulărilor îl folosesc. Fiecare nume costă schema lui la fiecare cerere a fiecărei rulări, pentru totdeauna. Un instrument care este important când este folosit, dar rar în ansamblu, își are locul în jumătatea amânată — agentul îl va găsi oricum.

Folosește numele real al instrumentului. Un nume rezident care nu se potrivește cu niciun instrument este inert: fără eroare, fără avertisment, instrumentul este pur și simplu amânat. test/tooling/resident_tool_names_test.dart prinde asta și ține fiecare mod sub 40 de instrumente rezidente, care este chiar scopul exercițiului — dincolo de acel interval, selecția instrumentelor se degradează măsurabil.

Verbele obligatorii și fixate ale unui mod sunt adăugate automat, așa că nu trebuie niciodată să listezi verbul de ieșire propriu al unui mod.

Diagnostichează o alegere greșită de instrument

Când un agent a folosit instrumentul greșit sau a susținut că nu poate face ceva, stabilește care dintre trei lucruri s-a întâmplat.

1. S-a uitat?

Fiecare rulare înregistrează instrumentele amânate pe care le-a încărcat și ce le-a declanșat — un apel direct pe nume sau o interogare search_tools. Deschide fluxul de evenimente al rulării (Setări → Spațiu de lucru → Agenți → agentul → Jurnale → Vizualizează) și caută [harness] loaded N deferred tool(s).

• Nimic consemnat, iar agentul a spus că îi lipsește capacitatea — nu s-a uitat niciodată. Aceasta este o problemă de prompt, nu una de recuperare: indexul amânat se află în promptul lui de sistem, cu instrucțiunea de a nu declara o capacitate lipsă până când o căutare nu s-a întors goală.
• O căutare consemnată, dar nimic încărcat — o ratare de recuperare autentică. Treci la pasul 2.
• Instrumente încărcate, dar folosit unul greșit — instrumentele găsite seamănă prea mult. Treci la pasul 3.

2. Repară o ratare de recuperare

search_tools potrivește pe nume, descrieri și nume de argumente. O ratare înseamnă aproape întotdeauna că descrierea nu conține cuvintele pe care le-a folosit agentul.

Adaugă-le. Descrierile sunt indexul de recuperare, așa că lungește-le în loc să le scurtezi — scrie vocabularul pe care un operator l-ar tasta de fapt („atribuie”, „predă”, „dă-i”), nu doar substantivul intern. Scurtarea unei descrieri pentru a economisi tokeni te costă atât potrivirea la căutare, cât și acuratețea selecției, și economisește aproape nimic în comparație cu schema.

Dacă instrumentul potrivit există, dar se clasează jos, pentru asta este argumentul limit; descrierea instrumentului însuși îi spune agentului să lărgească o căutare care pare apropiată, dar ratează.

3. Repară instrumentele care seamănă

Dacă două instrumente au descrieri care s-ar citi la fel pentru cineva care nu cunoaște deja diferența, modelul ghicește. Contopește-le într-un singur instrument cu un argument discriminatoriu.

ticket_relation și ticket_pr_link urmează acest tipar: fiecare se ocupă de legare și dezlegare printr-un argument discriminatoriu. O alegere făcută în interiorul unui singur apel, cu contextul complet al cererii, este mai fiabilă decât o alegere făcută între două descrieri care seamănă.

Ține instrumentele separate atunci când au nevoie de reguli de aprobare diferite, de auditare diferită sau de randare diferită — acestea sunt motive pentru care o contopire te-ar costa ceva real.

Verifică dacă funcționează cache-ul de prompturi

Rata de potrivire în cache apare în Observabilitate → Insights ca Rată cache. O conversație lungă sănătoasă stă sus; dacă este constant scăzută, ceva rescrie prefixul la fiecare tură.

Cauze frecvente, în ordinea probabilității:

• Orice lucru nedeterminist devreme în prompt. O marcă de timp, un id de cerere sau o mulțime iterată într-o ordine variabilă fac asta.
• O schimbare de model sau de efort la mijlocul conversației. Ambele schimbă prefixul. Subagenții sunt deosebit de ușor de greșit aici: rularea copiilor la un efort mai mic pentru a economisi bani poate costa mai mult prin partajarea pierdută a cache-ului decât economisește.
• Compactare frecventă. Compactarea rescrie istoricul prin concepție, așa că costul ei este real; soluția este să compactezi rar și profund, nu des și superficial.

Dezactivarea amânării cu --tool-deferral=off este un A/B valid pentru a izola dacă o schimbare de comportament a venit de la suprafața pe două niveluri. Reproduce exact cererea de dinainte de amânare, așa că dacă comportamentul persistă cu ea oprită, suprafața nu este cauza.