Налаштувати контекст інструментів агента

Цей посібник охоплює практичну роботу з дворівневою поверхнею інструментів: побачити, що надсилає запуск, змінити це й діагностувати агента, який узявся не за той інструмент. Про те, чому це працює саме так, читайте в Контекст інструментів і кеш промптів.

Подивіться, що насправді надсилає запуск

Відкрийте розмову й торкніться індикатора використання контексту в заголовку розмови. Він перебудовує ту саму поверхню, яку надіслав би наступний запуск, нічого не виконуючи. Показати більше (або команда /context) відкриває повний оглядач контексту, де можна переглянути кожен інструмент.

Тут важливі два сегменти:

• Визначення інструментів і MCP і динамічні інструменти — резидентний набір, із реальною вартістю в токенах для кожного інструмента.
• Інструменти, що завантажуються за потреби — відкладений індекс. Кожен запис оплачується лише своєю назвою, бо назва — це все, що несе запит; відкриття запису все одно показує повний опис і схему, тож видно, скільки він коштував би, якби запуск його підтягнув.

Якщо відкладений сегмент порожній, відкладення вимкнено для цього сервера. Перевірте --tool-deferral у довідці з CLI cc_server.

Змінити, які інструменти завантажуються наперед

Резидентний набір — це політика, а не конфігурація: він живе в ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) і застосовується до кожного запуску:

• residentBuiltins — лексика файлів і оболонки.
• residentDiscovery — search_tools і list_my_tools. Не видаляйте їх; саме через них агент дістається всього іншого.
• residentMcpTools — жменя інструментів Control Center, чия схема варта того, щоб бути в кожному запиті.
• Блок для кожного режиму — для інструментів, які цей режим використовує майже кожного ходу.

Два правила під час редагування:

Додавайте інструмент, лише якщо його використовує більшість запусків. Кожна назва коштує свою схему в кожному запиті кожного запуску, завжди. Інструмент, важливий тоді, коли вживається, але загалом рідкісний, належить до відкладеної половини — агент усе одно його знайде.

Використовуйте справжню назву інструмента. Резидентна назва, яка не збігається з жодним інструментом, інертна: жодної помилки, жодного попередження, інструмент просто відкладено. test/tooling/resident_tool_names_test.dart ловить це, а також тримає кожен режим під 40 резидентними інструментами — у цьому й сенс вправи: за цією межею вибір інструментів помітно гіршає.

Обов’язкові та закріплені дієслова режиму додаються автоматично, тож вам ніколи не потрібно перелічувати власне вихідне дієслово режиму.

Діагностувати невдалий вибір інструмента

Коли агент використав не той інструмент або заявив, що не може чогось зробити, з’ясуйте, що саме з трьох речей сталося.

1. Чи він шукав?

Кожен запуск записує відкладені інструменти, які він завантажив, і що це спричинило — прямий виклик за назвою чи запит search_tools. Відкрийте потік подій запуску (Налаштування → Робочий простір → Агенти → агент → Журнали → Перегляд) і знайдіть [harness] loaded N deferred tool(s).

• Нічого не записано, а агент сказав, що можливості немає — він не шукав. Це проблема промпту, а не пошуку: відкладений індекс є в його системному промпті разом з інструкцією не оголошувати можливість відсутньою, доки пошук не повернеться порожнім.
• Пошук записано, але нічого не завантажено — справжній промах пошуку. Перейдіть до кроку 2.
• Інструменти завантажено, але використано не той — знайдені інструменти занадто схожі. Перейдіть до кроку 3.

2. Виправити промах пошуку

search_tools зіставляє назви, описи та назви аргументів. Промах майже завжди означає, що опис не містить слів, які використав агент.

Додайте їх. Описи — це індекс пошуку, тож подовжуйте їх, а не підрізайте — пишіть лексику, яку оператор справді набрав би («призначити», «передати», «віддати»), а не лише внутрішній іменник. Підрізання опису заради економії токенів коштує вам і влучання в пошуку, і точності вибору, а економить майже нічого порівняно зі схемою.

Якщо потрібний інструмент існує, але має низький рейтинг, для цього й потрібен аргумент limit; власний опис інструмента підказує агенту розширити пошук, який виглядає близьким, але не влучає.

3. Виправити схожі інструменти

Якщо описи двох інструментів читалися б однаково для того, хто ще не знає різниці, модель просто вгадує. Об’єднайте їх в один інструмент із розрізнювальним аргументом.

ticket_relation і ticket_pr_link дотримуються цього зразка: кожен обробляє зв’язування та роз’єднування через розрізнювальний аргумент. Вибір, зроблений усередині одного виклику, з повним контекстом запиту, надійніший за вибір між двома схожими описами.

Залишайте інструменти окремими, коли їм потрібні різні шлюзи схвалення, різний аудит або різне відображення — це причини, через які об’єднання коштувало б вам чогось реального.

Перевірте, чи працює кеш промптів

Частка влучань у кеш відображається в Спостережуваність → Інсайти як Частка кешу. Здорова тривала розмова тримається високо; якщо вона стабільно низька, щось переписує префікс кожного ходу.

Типові причини, у порядку ймовірності:

• Будь-що недетерміноване на початку промпту. Позначка часу, ідентифікатор запиту або множина, що перебирається в різному порядку, уже зроблять це.
• Зміна моделі або рівня міркування посеред розмови. Обидві змінюють префікс. Із субагентами тут особливо легко помилитися: запуск дочірніх із нижчим рівнем міркування, щоб зекономити, може коштувати більше через втрачене спільне кешування, ніж зекономити.
• Часта компакція. Компакція за задумом переписує історію, тож її ціна реальна; рішення — ущільнювати рідко й глибоко, а не часто й поверхово.

Вимкнення відкладення через --tool-deferral=off — слушний A/B для з’ясування, чи зміна поведінки походить від дворівневої поверхні. Він точно відтворює запит до появи відкладення, тож якщо поведінка зберігається з вимкненим відкладенням, причина не в поверхні.