As ferramentas de desenvolvedores terceirizadas permitem que os agentes de programação vejam além do DOM, das solicitações de rede e dos registros do console. Ao expor ferramentas personalizadas diretamente do seu site ou framework, você permite que o agente interaja com dados e estados de aplicativos inacessíveis.
Essas ferramentas são criadas em JavaScript e descobertas automaticamente pelo Chrome DevTools para agentes quando a página é carregada.
Entender as ferramentas de desenvolvedores de terceiros
No contexto de agentes de programação, as ferramentas são funções prontas para que os agentes realizem ações específicas. Para o DevTools para agentes especificamente, essas ferramentas podem expor o estado de tempo de execução interno diretamente aos agentes de programação, diminuindo a lacuna entre a saída renderizada e a lógica interna.
Ao usar ferramentas de terceiros, lembre-se do seguinte:
- Descoberta de tempo de execução. As ferramentas são detectadas automaticamente quando seu
aplicativo responde ao evento
devtoolstooldiscoveryemitido pelo Chrome DevTools para agentes no objeto globalwindow. - Escopo de contexto. As ferramentas são executadas apenas no contexto da página que as define. Elas não são mantidas em origens e recarregamentos de página.
- Especificidade da ferramenta. As ferramentas são apenas uma maneira adicional para o agente realizar uma tarefa. Ele pode preferir ferramentas integradas ou recursos básicos do modelo para atender a um comando. Por isso, crie nomes e descrições o mais descritivos possível.
Pré-requisitos
Antes de implementar ferramentas de terceiros, verifique se você atende aos seguintes requisitos:
- Chrome DevTools para agentes. Use a versão 0.25.0 ou posterior.
- Ativou o JavaScript. Ter o JavaScript ativado e em execução.
Implementar uma ferramenta
Para implementar uma ferramenta, você precisa detectar um evento de descoberta específico e responder com as definições da ferramenta. O código a seguir representa uma resposta que inclui definições de ferramentas:
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;
},
},
],
});
},
);
Para registrar ferramentas no seu aplicativo:
Defina seu grupo de ferramentas. Crie um
ToolGroupque contenha um nome, uma descrição e uma matriz de definições de ferramentas individuais.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }Detecte o evento de descoberta. O Chrome DevTools para agentes envia um evento
devtoolstooldiscoverypersonalizado no objetowindowglobal após cada navegação e sempre que precisa de uma lista atualizada de ferramentas disponíveis.Registre suas ferramentas. Chame o método
respondWith()do evento para fornecer seu grupo de ferramentas ao agente.
Componentes essenciais para ferramentas individuais
Cada definição de ferramenta implementada precisa incluir as três partes a seguir:
- Nome e descrição. Elas fornecem as instruções que o agente usa para decidir quando e como chamar sua ferramenta.
- Esquema de entrada. Um esquema JSON que define a estrutura e os tipos de argumentos esperados pela ferramenta.
- Função de execução. O código JavaScript real que é executado na página quando o agente invoca a ferramenta.
O exemplo a seguir mostra esses três componentes em uma única definição de ferramenta:
{
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;
},
}
Casos de uso para ferramentas de desenvolvedores terceirizados
Instrua o agente a inspecionar a lógica do aplicativo em profundidade, em vez de apenas elementos da interface no nível da superfície. Use essas ferramentas personalizadas para simplificar a depuração de aplicativos com estado ou pesados em frameworks.
Dicas para descobrir ferramentas
Escreva nomes e descrições descritivas para as ferramentas. Os agentes usam essas descrições como contexto para decidir qual ferramenta usar. Uma linguagem clara ajuda o agente a determinar de forma autônoma quando uma ferramenta é adequada para uma tarefa.
Depurar métricas de tempo de execução específicas do aplicativo
Problemas como falhas silenciosas de cache ou chamadas de API redundantes geralmente são invisíveis para a inspeção padrão. Ao expor estatísticas internas, seu agente pode explicar por que um determinado comportamento ocorreu.
Suponha que você tenha uma função que exponha estatísticas internas. Primeiro, crie uma ferramenta como esta:
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();
}
}
]
});
});
Se a descrição da ferramenta for clara, o agente poderá usá-la de forma autônoma quando achar adequado. Você pode pedir ao agente para realizar uma tarefa usando a ferramenta como esta:
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.
Exemplo de execução do agente:o agente detecta a ferramenta getCacheStatistics
exposta pelo aplicativo. Ela invoca a ferramenta, analisa a proporção de acertos para erros retornada e identifica que o front-end está buscando novamente todo o pipeline sem necessidade, em vez de atualizar o cache local.
Como verificar flags de recurso
Defina pontos de dados personalizados para expor as variáveis de ambiente atuais ou as flags de recursos ativas para uma sessão de usuário específica. Isso ajuda a depurar por que determinados recursos estão ou não visíveis para usuários específicos. Se um usuário informar um bug, o agente poderá verificar se ele está em um grupo de experimento que pode estar causando o problema.
Por exemplo, crie uma ferramenta como esta para retornar o estado da flag de recurso interna:
// 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'
};
}
}
]
});
});
Se a descrição da ferramenta for clara, o agente poderá usá-la de forma autônoma quando achar adequado. Você pode pedir ao agente para realizar uma tarefa usando a ferramenta como esta:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
Exemplo de execução do agente: o agente invoca a ferramenta getFeatureFlags,
confirma que a flag new-ui-enabled está ativa e depura os
componentes associados à nova interface.
Inspecionar o estado global do aplicativo
Exponha a árvore de estado de tempo de execução do seu aplicativo para ajudar o agente a entender a lógica interna sem buscar todo o DOM.
Você pode criar uma ferramenta como esta para consultar caminhos específicos na sua árvore de estados, como:
// 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);
}
}
]
});
});
Se a descrição da ferramenta for clara, o agente poderá usá-la de forma autônoma quando achar adequado. Você pode pedir ao agente para realizar uma tarefa usando a ferramenta como esta:
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.
Exemplo de execução do agente: seu agente chama getGlobalState com o parâmetro path. Ele recupera a lista de itens do carrinho e identifica uma discrepância entre o estado interno e os itens renderizados na página.
Algumas observações importantes sobre este exemplo de ferramenta:
- Lógica dissociada: o agente de IA pede o "estado". Você, como desenvolvedor,
decide como mapear essa solicitação para sua estrutura de dados real na função
execute. - Depuração segmentada: ao incluir o parâmetro
path, o agente pode evitar extrair toda a árvore de estado (que pode ser enorme) e se concentrar apenas na parte relevante, economizando tokens e melhorando a performance. - Interface padronizada: mesmo que você mude as bibliotecas de gerenciamento de estado, contanto que atualize essa função
execute, o agente de depuração de IA não vai precisar de novas instruções ou ferramentas.
Inspecionar o conteúdo do banco de dados
Verifique se os dados de back-end correspondem ao estado da interface consultando os registros do banco de dados diretamente por um endpoint de depuração somente leitura.
Exponha um endpoint de depuração seguro e crie uma ferramenta como esta para verificar registros de back-end:
// 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}` };
}
}
}
]
});
});
Se a descrição da ferramenta for clara, o agente poderá usá-la de forma autônoma quando achar adequado. Você pode pedir ao agente para realizar uma tarefa usando a ferramenta como esta:
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.
Exemplo de execução do agente: seu agente chama queryDatabaseTable para a tabela de pedidos. Ele recupera o registro JSON, identifica um erro no cálculo de tributos do back-end e sugere uma correção para a lógica do servidor.
Algumas observações importantes sobre este exemplo de ferramenta:
- Segurança e autenticação: não é necessário transmitir credenciais de banco de dados
para o agente de IA. A chamada
fetchusa a sessão de login atual do navegador para autorizar a solicitação no seu back-end. - Depuração prática: se um agente de IA identificar um bug na interface, ele poderá
chamar imediatamente
queryDatabaseTablepara verificar se o erro existe nos dados de origem ou no cálculo do front-end. - Configuração mínima: basta expor um endpoint de depuração "seguro" (somente leitura) no servidor que aceite um nome de tabela e retorne JSON. Não importa qual framework você usa para criar esse endpoint.