Laděte kontext nástrojů agenta

Tenhle návod je o praktické práci s dvouúrovňovou plochou nástrojů: co běh posílá, jak to změnit a jak diagnostikovat agenta, který sáhl po špatném nástroji. Proč to funguje právě tak, čti v Kontext nástrojů a cache promptů.

Podívej se, co běh opravdu posílá

Otevři konverzaci a klepni na ukazatel využití kontextu v záhlaví konverzace. Sestaví přesně tu plochu, kterou by poslalo příští odeslání, a nic přitom nespustí. Zobrazit více (nebo příkaz /context) otevře celý průzkumník kontextu, kde si prohlédneš každý nástroj.

Tady záleží na dvou segmentech:

• Definice nástrojů a MCP a dynamické nástroje — rezidentní sada, s reálnou cenou každého nástroje v tokenech.
• Nástroje načtené na vyžádání — odložený index. Každá položka se účtuje jen za jméno, protože požadavek nese jen to; když ji otevřeš, pořád uvidíš celý popis a schéma, takže víš, kolik by stála, kdyby ji běh načetl.

Když je odložený segment prázdný, má tenhle server odložení vypnuté. Zkontroluj --tool-deferral v CLI cc_server.

Změň, které nástroje se načtou předem

Rezidentní sada je politika, ne konfigurace — žije v ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) a platí pro každý běh:

• residentBuiltins — slovník souborů a shellu.
• residentDiscovery — search_tools a list_my_tools. Neodstraňuj je; přes ně se agent dostane ke všemu ostatnímu.
• residentMcpTools — hrstka nástrojů Control Center, u kterých se schéma vyplatí na každém požadavku.
• Blok daného režimu, pro nástroje, které ten režim použije skoro na každém tahu.

Při úpravě platí dvě pravidla:

Přidej nástroj jen tehdy, když ho používá většina běhů. Každé jméno stojí své schéma na každém požadavku každého běhu, a to natrvalo. Nástroj, který je důležitý, když přijde na řadu, ale celkově vzácný, patří do odložené poloviny — agent ho pořád najde.

Používej skutečné jméno nástroje. Rezidentní jméno, které neodpovídá žádnému nástroji, je inertní: žádná chyba, žádné varování, nástroj se prostě odloží. test/tooling/resident_tool_names_test.dart to chytí a zároveň drží každý režim pod 40 rezidentními nástroji. O to tu jde — za tím pásmem se výběr nástrojů měřitelně zhoršuje.

Povinná a připnutá slovesa režimu se doplní sama, takže vlastní výstupní sloveso režimu vypisovat nemusíš.

Diagnostikuj špatnou volbu nástroje

Když agent použil špatný nástroj, nebo tvrdil, že něco neumí, zjisti, která ze tří věcí se stala.

1. Podíval se?

Každý běh si zapíše odložené nástroje, které načetl, a co to spustilo — přímé volání jménem, nebo dotaz search_tools. Otevři proud událostí běhu (Nastavení → Pracovní prostor → Agenti → agenta → Protokoly → Zobrazit) a hledej [harness] loaded N deferred tool(s).

• Nic v záznamu a agent řekl, že schopnost chybí — nepodíval se. To je problém promptu, ne vyhledání: odložený index má v systémovém promptu spolu s pokynem, aby schopnost neprohlásil za chybějící, dokud hledání nevrátí prázdný výsledek.
• Hledání v záznamu je, ale nic se nenačetlo — skutečné minutí vyhledání. Pokračuj krokem 2.
• Nástroje se načetly, použitý je špatný — ty, které našel, jsou si příliš podobné. Pokračuj krokem 3.

2. Oprav minutí vyhledání

search_tools hledá ve jménech, popisech a jménech argumentů. Minutí skoro vždy znamená, že popis neobsahuje slova, která agent použil.

Doplň je. Popisy jsou index vyhledání, takže je prodlužuj místo zkracování — piš slovník, který by operátor opravdu napsal („přiřaď“, „předej“, „dej“), ne jen vnitřní podstatné jméno. Když popis zkrátíš kvůli tokenům, ztratíš zásah hledání i přesnost výběru a vedle schématu neušetříš skoro nic.

Když správný nástroj existuje, ale řadí se nízko, přesně na to je argument limit; vlastní popis nástroje říká agentovi, aby rozšířil hledání, které je blízko, ale mine.

3. Oprav nástroje, které vypadají stejně

Když mají dva nástroje popisy, které by stejně přečetl i někdo, kdo rozdíl předem nezná, model hádá. Slouč je do jednoho nástroje s rozlišujícím argumentem.

ticket_relation a ticket_pr_link jdou podle tohohle vzoru: každý řeší navázání i zrušení vazby přes rozlišující argument. Volba uvnitř jednoho volání, s plným kontextem požadavku, je spolehlivější než volba mezi dvěma podobnými popisy.

Nástroje nech oddělené, když potřebují jinou bránu schválení, jiný audit nebo jiné vykreslení — to jsou důvody, proč by sloučení něco reálného stálo.

Zkontroluj, že cache promptů funguje

Míra zásahů cache se v Observabilita → Přehledy ukazuje jako Míra cache. Zdravá dlouhá konverzace drží vysokou míru; když je trvale nízká, něco na každém tahu přepisuje prefix.

Obvyklé příčiny, od nejpravděpodobnější:

• Cokoliv nedeterministického na začátku promptu. Časové razítko, id požadavku, nebo množina procházená v proměnlivém pořadí to udělá.
• Změna modelu nebo úsilí uprostřed konverzace. Obě změní prefix. Subagenti se tu zvlášť snadno pokazí: pouštět potomky na nižším úsilí kvůli úspoře může stát víc na ztraceném sdílení cache, než to ušetří.
• Častá komprimace. Komprimace historii přepisuje schválně, takže její cena je reálná; oprava je komprimovat zřídka a do hloubky, ne často a mělce.

Vypnutí odložení přes --tool-deferral=off je platné A/B, když chceš izolovat, jestli změna chování přišla z dvouúrovňové plochy. Vyrobí přesně požadavek z doby před odložením, takže když chování přetrvá i po vypnutí, plocha není příčina.