Dostroj kontekst narzędzi agenta

Ten poradnik opisuje praktyczną pracę z dwuwarstwową powierzchnią narzędzi: co wysyła uruchomienie, jak to zmienić i jak zdiagnozować agenta, który sięgnął po niewłaściwe narzędzie. Dlaczego działa to właśnie tak, przeczytasz w artykule Kontekst narzędzi i cache promptów.

Zobacz, co uruchomienie faktycznie wysyła

Otwórz rozmowę i kliknij wskaźnik użycia kontekstu w nagłówku rozmowy. Odbudowuje on dokładnie tę powierzchnię, którą wysłałaby następna wysyłka, nie uruchamiając przy tym niczego. Zobacz więcej (albo polecenie /context) otwiera pełny eksplorator kontekstu, w którym możesz obejrzeć każde narzędzie.

Znaczenie mają tu dwa segmenty:

• Definicje narzędzi i Narzędzia MCP i dynamiczne — zestaw rezydentny, z rzeczywistym kosztem tokenów każdego narzędzia.
• Narzędzia ładowane na żądanie — odroczony indeks. Każda pozycja jest obciążana wyłącznie swoją nazwą, bo tylko nazwę niesie żądanie; otwarcie pozycji nadal pokazuje pełny opis i schemat, więc widzisz, ile by kosztowała, gdyby uruchomienie ją wciągnęło.

Jeśli segment odroczony jest pusty, odroczenie jest dla tego serwera wyłączone. Sprawdź --tool-deferral w dokumentacji referencyjnej CLI cc_server.

Zmień, które narzędzia ładują się z góry

Zestaw rezydentny to polityka, a nie konfiguracja — żyje w ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) i dotyczy każdego uruchomienia:

• residentBuiltins — słownik plików i powłoki.
• residentDiscovery — search_tools i list_my_tools. Nie usuwaj ich; to dzięki nim agent dociera do wszystkiego innego.
• residentMcpTools — garść narzędzi Control Center, których schemat opłaca się na każdym żądaniu.
• Blok dla danego trybu, obejmujący narzędzia, których ten tryb używa niemal w każdej turze.

Przy jego edycji obowiązują dwie zasady:

Dodawaj narzędzie tylko wtedy, gdy używa go większość uruchomień. Każda nazwa kosztuje swój schemat przy każdym żądaniu każdego uruchomienia, na zawsze. Narzędzie, które jest ważne, gdy się je stosuje, ale ogólnie rzadkie, należy do odroczonej połowy — agent i tak je znajdzie.

Używaj rzeczywistej nazwy narzędzia. Nazwa rezydentna, która nie pasuje do żadnego narzędzia, jest bezwładna: żadnego błędu, żadnego ostrzeżenia, narzędzie po prostu zostaje odroczone. test/tooling/resident_tool_names_test.dart to wychwytuje, a przy okazji trzyma każdy tryb poniżej 40 narzędzi rezydentnych, o co właśnie chodzi — powyżej tego przedziału wybór narzędzi mierzalnie się pogarsza.

Wymagane i przypięte czasowniki trybu są dodawane automatycznie, więc nigdy nie musisz wypisywać własnego czasownika wyjściowego trybu.

Zdiagnozuj zły wybór narzędzia

Gdy agent użył niewłaściwego narzędzia albo twierdził, że czegoś nie potrafi, ustal, która z trzech rzeczy się stała.

1. Czy w ogóle sprawdził?

Każde uruchomienie zapisuje, które odroczone narzędzia wczytało i co to wyzwoliło — bezpośrednie wywołanie po nazwie albo zapytanie search_tools. Otwórz strumień zdarzeń uruchomienia (Ustawienia → Obszar roboczy → Agenci → agenta → Logi → Widok) i poszukaj wpisu [harness] loaded N deferred tool(s).

• Nic w dzienniku, a agent twierdził, że brakuje tej możliwości — nigdy nie sprawdził. To problem promptu, a nie wyszukiwania: odroczony indeks znajduje się w jego prompcie systemowym wraz z instrukcją, by nie ogłaszać braku możliwości, dopóki wyszukiwanie nie zwróci pustego wyniku.
• Wyszukiwanie w dzienniku, ale nic się nie wczytało — prawdziwe nietrafienie wyszukiwania. Przejdź do kroku 2.
• Narzędzia wczytane, użyte niewłaściwe — znalezione narzędzia są zbyt podobne. Przejdź do kroku 3.

2. Napraw nietrafienie wyszukiwania

search_tools dopasowuje nazwy, opisy i nazwy argumentów. Nietrafienie niemal zawsze oznacza, że opis nie zawiera słów, których użył agent.

Dodaj je. Opisy są indeksem wyszukiwania, więc wydłużaj je, zamiast skracać — zapisuj słownictwo, które operator rzeczywiście by wpisał („przypisz”, „przekaż dalej”, „daj komuś”), a nie tylko wewnętrzny rzeczownik. Skrócenie opisu w celu oszczędzenia tokenów kosztuje cię i trafienie w wyszukiwaniu, i dokładność wyboru, a w porównaniu ze schematem oszczędza niemal nic.

Jeśli właściwe narzędzie istnieje, ale zajmuje niską pozycję, właśnie do tego służy argument limit; własny opis narzędzia mówi agentowi, żeby poszerzył wyszukiwanie, które wygląda blisko, ale chybia.

3. Napraw narzędzia wyglądające tak samo

Jeśli dwa narzędzia mają opisy, które dla kogoś nieznającego wcześniej różnicy brzmiałyby tak samo, model zgaduje. Scal je w jedno narzędzie z rozróżniającym argumentem.

ticket_relation i ticket_pr_link działają według tego wzorca: każde obsługuje wiązanie i odwiązywanie przez rozróżniający argument. Wybór dokonany wewnątrz jednego wywołania, z pełnym kontekstem żądania, jest bardziej niezawodny niż wybór między dwoma łudząco podobnymi opisami.

Trzymaj narzędzia osobno, gdy wymagają innego bramkowania zatwierdzeń, innego audytu albo innego renderowania — to powody, dla których scalenie naprawdę by cię na czymś kosztowało.

Sprawdź, czy cache promptów działa

Współczynnik trafień cache widać w Obserwowalność → Analizy pod Trafność cache. Zdrowa, długo tocząca się rozmowa utrzymuje go wysoko; jeśli jest stale niski, coś przepisuje prefiks w każdej turze.

Typowe przyczyny, w kolejności prawdopodobieństwa:

• Cokolwiek niedeterministycznego na początku promptu. Wystarczy znacznik czasu, identyfikator żądania albo zbiór iterowany w zmiennej kolejności.
• Zmiana modelu lub poziomu wysiłku w trakcie rozmowy. Obie zmieniają prefiks. Podagentów szczególnie łatwo tu zepsuć: uruchamianie dzieci na niższym poziomie wysiłku, by oszczędzić pieniądze, może kosztować więcej na utraconym współdzieleniu cache, niż oszczędza.
• Częste kompaktowanie. Kompaktowanie z założenia przepisuje historię, więc jego koszt jest realny; lekarstwem jest kompaktowanie rzadko i głęboko, a nie często i płytko.

Wyłączenie odroczenia przez --tool-deferral=off to zasadny test A/B do wyizolowania, czy zmiana zachowania pochodzi z dwuwarstwowej powierzchni. Odtwarza dokładnie żądanie sprzed wprowadzenia odroczenia, więc jeśli zachowanie utrzymuje się po wyłączeniu, powierzchnia nie jest przyczyną.