Инструменты сторонних разработчиков позволяют агентам кода видеть не только DOM, сетевые запросы и журналы консоли. Предоставляя доступ к пользовательским инструментам непосредственно из вашего веб-сайта или фреймворка, вы позволяете вашему агенту взаимодействовать с недоступным иным способом состоянием и данными приложения.
Эти инструменты создаются с помощью JavaScript и автоматически обнаруживаются инструментами разработчика Chrome для агентов при загрузке страницы.
Разберитесь в инструментах сторонних разработчиков.
В контексте агентов-программистов инструменты представляют собой готовые функции, позволяющие агентам выполнять определенные действия. В частности, в случае с DevTools для агентов такие инструменты могут напрямую предоставлять агентам-программистам доступ к своему внутреннему состоянию во время выполнения, устраняя разрыв между отображаемым результатом и внутренней логикой.
При использовании сторонних инструментов следует учитывать следующее:
- Обнаружение во время выполнения. Инструменты автоматически обнаруживаются, когда ваше приложение реагирует на событие
devtoolstooldiscoveryгенерируемое инструментами разработчика Chrome для агентов на глобальном объектеwindow. - Область действия контекста. Инструменты выполняются только в контексте страницы, которая их определяет. Они не сохраняются при смене источника и перезагрузке страницы.
- Специфичность инструментов . Инструменты — это лишь дополнительный способ для вашего агента выполнить задачу. Он может предпочитать встроенные инструменты или базовые возможности модели для выполнения запроса. Поэтому делайте названия и описания инструментов максимально информативными.
Предварительные требования
Прежде чем внедрять сторонние инструменты, убедитесь, что вы соответствуете следующим требованиям:
- Инструменты разработчика Chrome для агентов. Используйте версию 0.25.0 или более позднюю.
- JavaScript включен. JavaScript включен и выполняется.
Внедрить инструмент
Для внедрения инструмента необходимо отслеживать определенное событие обнаружения и отправлять в ответ определения инструмента. Следующий код представляет собой ответ, включающий определения инструмента:
window.addEventListener(
'devtoolstooldiscovery',
(event: DevtoolsToolDiscoveryEvent) => {
event.respondWith({
name: 'Page-specific DevTools',
description: 'Provide runtime info directly from the JavaScript in the page.',
tools: [
{
name: 'add',
description: 'Calculates the sum of two numbers.',
inputSchema: {
type: 'object',
properties: {
a: {type: 'number'},
b: {type: 'number'},
},
required: ['a', 'b'],
},
execute: async (input: {a: number; b: number}) => {
return input.a + input.b;
},
},
],
});
},
);
Для регистрации инструментов в вашем приложении:
Определите свою группу инструментов. Создайте
ToolGroup, который будет содержать имя, описание и массив определений отдельных инструментов.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }Отслеживайте событие обнаружения. Chrome DevTools для агентов отправляет пользовательское событие
devtoolstooldiscoveryглобальному объектуwindowпосле каждой навигации и всякий раз, когда ему требуется обновленный список доступных инструментов.Зарегистрируйте свои инструменты. Вызовите метод
respondWith()события, чтобы передать агенту информацию о вашей группе инструментов.
Основные компоненты для отдельных инструментов
Каждое внедряемое вами определение инструмента должно включать следующие три части:
- Название и описание. В них содержатся инструкции, которые агент использует для принятия решения о том, когда и как вызвать ваш инструмент.
- Входная схема. JSON-схема, определяющая структуру и типы аргументов, которые ожидает инструмент.
- Функция выполнения. Фактический код JavaScript, который выполняется на странице, когда агент вызывает инструмент.
В следующем примере показаны эти три компонента в одном определении инструмента:
{
name: 'add',
description: 'Calculates the sum of two numbers.',
inputSchema: {
type: 'object',
properties: {
a: {type: 'number'},
b: {type: 'number'},
},
required: ['a', 'b'],
},
execute: async (input) => {
return input.a + input.b;
},
}
Примеры использования сторонних инструментов для разработчиков
Настройте своего агента на проверку глубинной логики приложения, а не только поверхностных элементов пользовательского интерфейса. Используйте эти пользовательские инструменты для упрощения отладки приложений, использующих состояние или активно работающих с фреймворком.
Советы по поиску инструментов
Напишите описательные названия и описания инструментов . Агенты используют эти описания в качестве контекста, чтобы решить, какой инструмент использовать; понятный язык помогает агенту самостоятельно определить, когда инструмент подходит для выполнения задачи.
Отладка метрик времени выполнения, специфичных для приложения.
Такие проблемы, как скрытые промахи кэша или избыточные вызовы API, часто остаются незамеченными при стандартном анализе. Предоставив внутреннюю статистику, ваш агент сможет объяснить, почему произошло то или иное поведение.
Предположим, у вас есть функция, которая предоставляет внутреннюю статистику; сначала вам нужно создать инструмент, подобный этому:
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: 'My app',
description: 'Tools to debug my app',
tools: [
{
name: 'getCacheStatistics',
description: 'Exposes runtime cache hits and misses for the frontend API service.',
inputSchema: {},
execute: async () => {
// Assuming window.__apiCacheService exists in your app
return window.__apiCacheService.getStats();
}
}
]
});
});
Если описание инструмента понятно, ваш агент может использовать его автоматически, когда сочтет это необходимым. Вы можете предложить агенту выполнить задачу с помощью инструмента следующим образом:
When I reassign a lead to a new sales rep, the dashboard takes a second to
update. Please verify if the frontend is correctly updating the local cache,
or if it is doing a full cache miss and refetching the entire pipeline from the
database.
Пример выполнения агента: Ваш агент обнаруживает инструмент getCacheStatistics предоставляемый вашим приложением. Он вызывает этот инструмент, анализирует соотношение попаданий и промахов и определяет, что фронтенд излишне перезагружает весь конвейер вместо обновления локального кэша.
Проверка флагов функций
Задайте пользовательские точки данных, чтобы отобразить текущие переменные среды или флаги функций, активные для конкретной пользовательской сессии. Это поможет вам отладить причины, по которым определенные функции отображаются или не отображаются для конкретных пользователей. Если пользователь сообщает об ошибке, агент может проверить, находится ли он в экспериментальной группе, которая может вызывать проблему.
Например, создайте инструмент, подобный этому, для возврата внутреннего состояния флага функции:
// Implementation for a website creator to expose feature flags
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: 'Application Configuration Tools',
description: 'Tools for inspecting runtime environment and feature toggles',
tools: [
{
name: 'getFeatureFlags',
description: 'Returns a list of all active feature flags and their current values for the session.',
inputSchema: {
type: 'object',
properties: {} // No input parameters required for this tool
},
execute: async () => {
// This should return your internal feature flag state
// Example: return window.AppConfig.getFlags();
return {
"new-ui-enabled": true,
"beta-search-v2": false,
"experiment-group": 'control',
"log-level": 'debug'
};
}
}
]
});
});
Если описание инструмента понятно, ваш агент может использовать его автоматически, когда сочтет это необходимым. Вы можете предложить агенту выполнить задачу с помощью инструмента следующим образом:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
Пример выполнения агента : Ваш агент вызывает инструмент getFeatureFlags , подтверждает, что флаг new-ui-enabled активен, и приступает к отладке компонентов, связанных с новым интерфейсом.
Проверьте глобальное состояние приложения.
Предоставьте доступ к дереву состояний вашего приложения во время выполнения, чтобы помочь вашему агенту понять внутреннюю логику без необходимости загрузки всего DOM-дерева.
Вы можете создать подобный инструмент для запроса определенных путей в дереве состояний, например, такой:
// Library-agnostic implementation for inspecting global application state
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: "Global State Inspector",
description: 'Tools to inspect the runtime state tree of the application',
tools: [
{
name: 'getGlobalState',
description: "Returns the current application state. Use the 'path' parameter to drill down into specific sections (for example, 'auth.user' or 'cart.items'). ",
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'Optional dot-notation path to a specific property in the state tree.'
}
}
},
execute: async (input) => {
// Library-agnostic access:
// Website creators can point this to whatever global store they use.
const state = window.__APP_STATE__ ||
(window.store && typeof window.store.getState === 'function' ? window.store.getState() : null);
if (!state) {
return { error: 'Application state is not accessible via window.__APP_STATE__ or window.store.' };
}
if (!input.path) {
return state;
}
// Helper to resolve a dot-notated path against the state object
return input.path.split('.').reduce((acc, part) => {
return acc && acc[part] !== undefined ? acc[part] : undefined;
}, state);
}
}
]
});
});
Если описание инструмента понятно, ваш агент может использовать его автоматически, когда сочтет это необходимым. Вы можете предложить агенту выполнить задачу с помощью инструмента следующим образом:
The number of items in my cart is not updating. Inspect the global state at the
path cart.items and list the current items and their quantities, see if they are
the same.
Пример выполнения агента : Ваш агент вызывает getGlobalState с параметром path . Он получает список товаров из корзины и выявляет несоответствие между внутренним состоянием и товарами, отображаемыми на странице.
Несколько важных замечаний относительно этого примера использования инструмента:
- Разделенная логика : агент ИИ запрашивает «состояние». Вы, как разработчик, решаете, как сопоставить этот запрос с вашей фактической структурой данных в функции
execute. - Целенаправленная отладка : Указав параметр
path, агент может избежать загрузки всего дерева состояний (которое может быть огромным) и сосредоточиться только на соответствующей части, экономя токены и повышая производительность. - Стандартизированный интерфейс : даже если вы перейдете на другую библиотеку управления состоянием, достаточно обновить эту функцию
execute, и вашему агенту отладки ИИ не понадобятся новые инструкции или инструменты.
Проверить содержимое базы данных
Убедитесь, что данные в бэкэнде соответствуют состоянию пользовательского интерфейса, запросив записи в базе данных напрямую через отладочную точку доступа только для чтения.
Предоставьте безопасный доступ к точке отладки и создайте инструмент, подобный этому, для проверки записей в бэкэнде:
// Framework-agnostic implementation for inspecting database content
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: 'Database Inspection Tools',
description: 'Tools to query backend database records using existing browser session',
tools: [
{
name: 'queryDatabaseTable',
description: 'Retrieves a limited set of records from a specific table. Useful for verifying that backend data matches the UI state.',
inputSchema: {
type: 'object',
properties: {
tableName: {
type: 'string',
description: 'The name of the database table to inspect.'
},
limit: {
type: 'number',
default: 5,
description: 'Maximum number of rows to return.'
}
},
required: ['tableName']
},
execute: async (input) => {
// This calls a generic debug endpoint you've set up on your server.
// It's framework-agnostic because it just expects a JSON response.
try {
const response = await fetch(`/api/debug/db-inspect?table=${input.tableName}&limit=${input.limit}`);
if (!response.ok) {
return { error: `Backend returned ${response.status}: ${response.statusText}` };
}
return await response.json();
} catch (error) {
return { error: `Failed to connect to debug endpoint: ${error.message}` };
}
}
}
]
});
});
Если описание инструмента понятно, ваш агент может использовать его автоматически, когда сочтет это необходимым. Вы можете предложить агенту выполнить задачу с помощью инструмента следующим образом:
The total price on the checkout page seems wrong. Query the orders table for my
last order to verify the subtotal and tax values and see what may be causing the
problem, if any.
Пример выполнения агента : Ваш агент вызывает queryDatabaseTable для таблицы orders. Он извлекает запись в формате JSON, выявляет ошибку в расчете налогов на бэкэнде и предлагает исправление для серверной логики.
Несколько важных замечаний относительно этого примера использования инструмента:
- Безопасность и аутентификация : Вам не нужно передавать учетные данные базы данных агенту ИИ. Вызов функции
fetchиспользует текущую сессию входа в браузер для авторизации запроса на вашем бэкэнде. - Эффективная отладка : если агент ИИ обнаруживает ошибку в пользовательском интерфейсе, он может немедленно вызвать функцию
queryDatabaseTable, чтобы проверить, находится ли ошибка в исходных данных или в вычислениях на стороне клиента. - Минимальная настройка : Вам нужно всего лишь предоставить на сервере одну «безопасную» (только для чтения) точку отладки, которая принимает имя таблицы и возвращает JSON. Используемый вами фреймворк для создания этой точки отладки не имеет значения.