Juster verktøykonteksten til en agent

Denne veiledningen dekker det praktiske arbeidet rundt verktøyflaten med to nivåer: å se hva en kjøring sender, å endre det, og å diagnostisere en agent som grep etter feil verktøy. For å forstå hvorfor det fungerer slik, les Verktøykontekst og promptbuffer.

Se hva en kjøring faktisk sender

Åpne en samtale og trykk på kontekstbruksindikatoren i samtalens topptekst. Den bygger opp den nøyaktige flaten neste utsending ville sende, uten å kjøre noe. Se mer (eller kommandoen /context) åpner hele kontekstutforskeren, der du kan inspisere hvert verktøy.

To segmenter er viktige her:

• Verktøydefinisjoner og MCP- og dynamiske verktøy — det faste settet, med den reelle tokenkostnaden til hvert verktøy.
• Verktøy lastet ved behov — den utsatte indeksen. Hver oppføring belastes bare med navnet sitt, fordi et navn er alt forespørselen bærer med seg; å åpne ett viser fortsatt hele beskrivelsen og skjemaet, slik at du kan se hva det ville koste hvis kjøringen trakk det inn.

Hvis det utsatte segmentet er tomt, er utsettelse av for denne serveren. Sjekk --tool-deferral i cc_server-CLI-en.

Endre hvilke verktøy som lastes på forhånd

Det faste settet er policy, ikke konfigurasjon — det ligger i ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) og gjelder for hver kjøring:

• residentBuiltins — fil- og shell-vokabularet.
• residentDiscovery — search_tools og list_my_tools. Ikke fjern disse; det er slik en agent når alt annet.
• residentMcpTools — de få Control Center-verktøyene som er verdt skjemaet sitt ved hver forespørsel.
• En blokk per modus, for verktøyene en gitt modus bruker i nesten hver tur.

To regler når du redigerer det:

Legg bare til et verktøy hvis de fleste kjøringer bruker det. Hvert navn koster skjemaet sitt ved hver forespørsel i hver kjøring, for alltid. Et verktøy som er viktig når det brukes, men sjeldent totalt sett, hører hjemme i den utsatte halvdelen — agenten finner det fortsatt.

Bruk verktøyets virkelige navn. Et fast navn som ikke samsvarer med noe verktøy, er inert: ingen feil, ingen advarsel, verktøyet blir rett og slett utsatt. test/tooling/resident_tool_names_test.dart fanger opp dette og holder i tillegg hver modus under 40 faste verktøy, som er hele poenget — forbi det båndet blir verktøyvalget målbar dårligere.

En modus’ påkrevde og festede verb legges til automatisk, så du trenger aldri å føre opp en modus’ eget utdataverb.

Diagnostiser et dårlig verktøyvalg

Når en agent brukte feil verktøy eller hevdet at den ikke kunne gjøre noe, finn ut hvilken av tre ting som skjedde.

1. Lette den?

Hver kjøring registrerer hvilke utsatte verktøy den lastet, og hva som utløste det — et direkte kall ved navn, eller en search_tools-spørring. Åpne hendelsesstrømmen til kjøringen (Innstillinger → Arbeidsområde → Agenter → agenten → Logger → Vis) og se etter [harness] loaded N deferred tool(s).

• Ingenting logget, og agenten sa at evnen manglet — den lette aldri. Det er et promptproblem, ikke et gjenfinningsproblem: den utsatte indeksen ligger i systemprompten med en instruks om ikke å erklære en evne som manglende før et søk har kommet tomt tilbake.
• Et søk logget, men ingenting lastet — et ekte gjenfinningsbom. Gå til steg 2.
• Verktøy lastet, men feil brukt — verktøyene den fant, er for like. Gå til steg 3.

2. Fiks et gjenfinningsbom

search_tools matcher på navn, beskrivelser og argumentnavn. Et bom betyr nesten alltid at beskrivelsen ikke inneholder ordene agenten brukte.

Legg dem til. Beskrivelser er gjenfinningsindeksen, så forleng dem i stedet for å kutte — skriv vokabularet en operatør faktisk ville skrevet («tilordne», «overlevere», «gi til»), ikke bare det interne substantivet. Å kutte en beskrivelse for å spare tokens koster deg både søketreffet og valgnøyaktigheten, og sparer nesten ingenting sammenlignet med skjemaet.

Hvis det riktige verktøyet finnes, men rangeres lavt, er det derfor limit-argumentet finnes; verktøyets egen beskrivelse ber agenten utvide et søk som ser nært ut, men bommer.

3. Fiks verktøy som ligner hverandre

Hvis to verktøy har beskrivelser som ville lest likt for noen som ikke allerede kjenner forskjellen, gjetter modellen. Slå dem sammen til ett verktøy med et diskriminerende argument.

ticket_relation og ticket_pr_link følger dette mønsteret: hver av dem håndterer kobling og avkobling gjennom et diskriminerende argument. Et valg som tas inne i ett kall, med hele konteksten i forespørselen, er mer pålitelig enn et valg som tas mellom to beskrivelser som ligner hverandre.

Hold verktøy adskilt når de trenger forskjellige godkjenningsregler, ulik revisjon eller ulik rendering — det er grunner til at en sammenslåing ville koste deg noe reelt.

Sjekk at promptbufferen virker

Treffprosenten på bufferen vises i Observabilitet → Innsikt som Cache-rate. En sunn, langvarig samtale ligger høyt; hvis den vedvarende er lav, er det noe som skriver om prefikset hver tur.

Vanlige årsaker, i rekkefølge etter sannsynlighet:

• Alt ikke-deterministisk tidlig i prompten. Et tidsstempel, en forespørsels-id eller et sett som itereres i varierende rekkefølge, er nok.
• En endring av modell eller resonneringsinnsats midt i samtalen. Begge endrer prefikset. Underagenter er spesielt lette å gjøre feil her: å kjøre barn med lavere resonneringsinnsats for å spare penger kan koste mer i tapt bufferdeling enn det sparer.
• Hyppig kompaktering. Kompaktering skriver om historikken med vilje, så kostnaden er reell; løsningen er å kompaktere sjelden og dypt i stedet for ofte og grunt.

Å slå av utsettelse med --tool-deferral=off er en gyldig A/B-test for å isolere om en atferdsendring kom fra flaten med to nivåer. Den gjenskaper forespørselen fra før utsettelsen nøyaktig, så hvis atferden vedvarer med den av, er ikke flaten årsaken.