Ügynök eszközkontextusának hangolása

Ez az útmutató a kétszintű eszközfelület körüli gyakorlati munkát járja körül: hogyan látható, mit küld egy futás, hogyan változtatható meg, és hogyan diagnosztizálható egy ügynök, amely rossz eszközhöz nyúlt. Hogy miért működik így, arról az Eszközkontextus és promptgyorsítótár oldalon olvashat.

Nézze meg, mit küld valójában egy futás

Nyisson meg egy beszélgetést, és koppintson a beszélgetés fejlécében lévő kontextushasználat-jelzőre. Ez pontosan azt a felületet építi újra, amelyet a következő indítás elküldene, anélkül hogy bármit futtatna. A Több megjelenítése (vagy a /context parancs) megnyitja a teljes kontextusfelfedezőt, ahol az egyes eszközöket is megvizsgálhatja.

Itt két szegmens számít:

• Eszközdefiníciók és MCP- és dinamikus eszközök — a rezidens készlet, az egyes eszközök valódi tokenköltségével.
• Igény szerint betöltött eszközök — a halasztott index. Minden bejegyzésnél csak a név kerül felszámításra, mert a kérésben csak a név utazik; egy elem megnyitása azonban a teljes leírást és sémát mutatja, így láthatja, mennyibe kerülne, ha a futás behúzná.

Ha a halasztott szegmens üres, a halasztás ki van kapcsolva ennél a szervernél. Ellenőrizze a --tool-deferral kapcsolót a cc_server CLI oldalon.

Változtassa meg, mely eszközök töltődnek be előre

A rezidens készlet szabályzat, nem konfiguráció — a ModeToolPolicy-ban él (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart), és minden futásra érvényes:

• residentBuiltins — a fájl- és shell-szókincs.
• residentDiscovery — a search_tools és a list_my_tools. Ne távolítsa el őket; ezeken keresztül ér el az ügynök minden mást.
• residentMcpTools — az a néhány Control Center-eszköz, amely megéri a sémáját minden kérésben.
• Egy módonkénti blokk azoknak az eszközöknek, amelyeket egy adott mód szinte minden körben használ.

Két szabály a szerkesztésekor:

Csak akkor vegyen fel egy eszközt, ha a futások többsége használja. Minden név a sémájával együtt minden futás minden kérésében fizetendő, a végtelenségig. Egy eszköz, amely használatkor fontos, de összességében ritka, a halasztott felébe való — az ügynök így is megtalálja.

Az eszköz valódi nevét használja. Egy rezidens név, amely egyetlen eszközzel sem egyezik, hatástalan: nincs hiba, nincs figyelmeztetés, az eszköz egyszerűen halasztott marad. A test/tooling/resident_tool_names_test.dart ezt elkapja, és emellett módonként 40 rezidens eszköz alatt tartja a készletet, ami épp a gyakorlat lényege — azon a sávon túl az eszközválasztás mérhetően romlik.

Egy mód kötelező és beékelt igéit a rendszer automatikusan hozzáadja, így soha nem kell felsorolnia egy mód saját kimeneti igéjét.

Egy rossz eszközválasztás diagnosztizálása

Amikor egy ügynök rossz eszközt használt, vagy azt állította, hogy nem tud megtenni valamit, derítse ki, hogy a három eset közül melyik történt meg.

1. Odanézett?

Minden futás rögzíti, mely halasztott eszközöket töltötte be, és hogy mi váltotta ki a betöltést — egy közvetlen hívás név szerint, vagy egy search_tools lekérdezés. Nyissa meg a futás eseményfolyamát (Beállítások → Munkaterület → Ügynökök → az ügynök → Naplók → Nézet), és keresse a [harness] loaded N deferred tool(s) sort.

• Semmi nincs naplózva, és az ügynök azt mondta, hogy hiányzik a képesség — nem is nézett utána. Ez promptprobléma, nem visszakeresési hiba: a halasztott index a rendszerpromptjában van, azzal az utasítással, hogy ne jelentse ki egy képesség hiányát, amíg egy keresés üresen nem tér vissza.
• Naplózódott egy keresés, de semmi nem töltődött be — valódi visszakeresési kihagyás. Ugorjon a 2. lépésre.
• Betöltődtek az eszközök, de rosszat használt — a megtalált eszközök túlságosan hasonlók. Ugorjon a 3. lépésre.

2. Javítsa a visszakeresési kihagyást

A search_tools a nevekre, a leírásokra és az argumentumnevekre illeszt. Egy kihagyás szinte mindig azt jelenti, hogy a leírás nem tartalmazza azokat a szavakat, amelyeket az ügynök használt.

Adja hozzá őket. A leírások a visszakeresési index, ezért hosszabbítsa meg őket, ne rövidítse — írja bele azt a szókincset, amelyet egy kezelő valóban begépelne („hozzárendel”, „átad”, „odaad”), ne csak a belső főnevet. Egy leírás megkurtítása a tokenek megtakarítása érdekében egyszerre kerül a keresési találatba és a kiválasztás pontosságába, a sémához képest pedig szinte semmit nem takarít meg.

Ha a megfelelő eszköz létezik, de alacsonyan rangsorol, erre való a limit argumentum; az eszköz saját leírása arra utasítja az ügynököt, hogy szélesítse ki a közelinek tűnő, de célt tévesztő keresést.

3. Javítsa a hasonmás eszközöket

Ha két eszköz leírása ugyanúgy hangzana valakinek, aki még nem ismeri a köztük lévő különbséget, a modell csak találgat. Vonja össze őket egyetlen eszközzé egy megkülönböztető argumentummal.

A ticket_relation és a ticket_pr_link ezt a mintát követi: mindkettő egy megkülönböztető argumentumon keresztül kezeli az összekapcsolást és a szétválasztást. Az egyetlen híváson belül, a kérés teljes kontextusával meghozott döntés megbízhatóbb, mint a két hasonmás leírás közötti választás.

Tartsa külön azokat az eszközöket, amelyek eltérő jóváhagyási kapuzást, eltérő auditálást vagy eltérő megjelenítést igényelnek — ezek olyan okok, amelyek miatt egy összevonás valódi veszteséget okozna.

Ellenőrizze, hogy működik-e a promptgyorsítótár

A gyorsítótár találati aránya a Megfigyelhetőség → Betekintések alatt Gyorsítótár-arány néven jelenik meg. Egy egészséges, hosszan futó beszélgetés értéke magas; ha tartósan alacsony, valami minden körben újraírja a prefixumot.

A gyakori okok, valószínűség szerinti sorrendben:

• Bármi nem determinisztikus dolog a prompt elején. Egy időbélyeg, egy kérésazonosító vagy egy változó sorrendben bejárt halmaz is elég hozzá.
• Modell- vagy erőfeszítésváltás a beszélgetés közben. Mindkettő megváltoztatja a prefixumot. Az alügynököknél ezt különösen könnyű elrontani: ha a gyermekeket alacsonyabb erőfeszítéssel futtatja a pénz megtakarítása érdekében, az az elveszett gyorsítótár-megosztás miatt többbe kerülhet, mint amennyit megtakarít.
• Gyakori tömörítés. A tömörítés tervezésénél fogva újraírja az előzményeket, így a költsége valódi; a megoldás az, hogy ritkán és mélyen tömörítsen, ne gyakran és sekélyen.

A halasztás kikapcsolása a --tool-deferral=off kapcsolóval érvényes A/B-vizsgálat annak elkülönítésére, hogy egy viselkedésváltozás a kétszintű felülettől ered-e. Pontosan a halasztás előtti kérést állítja elő, így ha a viselkedés kikapcsolt állapotban is fennmarad, a felület nem az oka.