As ferramentas de desenvolvedor de terceiros 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 o estado e os dados do aplicativo que, de outra forma, seriam inacessíveis.
Essas ferramentas são criadas em JavaScript e são descobertas automaticamente pelo Chrome DevTools para agentes quando a página é carregada.
Entender as ferramentas de desenvolvedor de terceiros
No contexto de agentes de programação, as ferramentas são funções prontas para que os agentes executem ações específicas. Para o DevTools para agentes especificamente, essas ferramentas podem expor o estado interno do ambiente de execução diretamente aos agentes de programação, preenchendo a lacuna entre a saída renderizada e a lógica interna.
Ao usar ferramentas de terceiros, tenha em mente o seguinte:
- Descoberta do ambiente de execução. As ferramentas são detectadas automaticamente quando o aplicativo responde ao evento
devtoolstooldiscoveryemitido pelo Chrome DevTools para agentes no objetowindowglobal. - Escopo de contexto. As ferramentas são executadas apenas no contexto da página que as define. Elas não persistem 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 de modelo simples para atender a um comando. Portanto, deixe os nomes e as descrições das ferramentas 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 mais recente.
- JavaScript ativado. O JavaScript precisa estar 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 aplicativo:
Defina o 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 precisar de uma lista atualizada de ferramentas disponíveis.Registre suas ferramentas. Chame o método
respondWith()do evento para fornecer o grupo de ferramentas ao agente.
Componentes essenciais para ferramentas individuais
Cada definição de ferramenta implementada precisa incluir estas três partes:
- Nome e descrição. Eles fornecem as instruções que o agente usa para decidir quando e como chamar a 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 desenvolvedor de terceiros
Instrua o agente a inspecionar a lógica do aplicativo em detalhes, em vez de apenas elementos da interface de nível superficial. Use essas ferramentas personalizadas para simplificar a depuração de aplicativos com estado ou com muitos frameworks.
Dicas para descoberta de ferramentas
Escreva nomes e descrições de ferramentas descritivos. 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 ambiente de execução específicas do aplicativo
Problemas como falhas de cache silenciosas ou chamadas de API redundantes geralmente são invisíveis para inspeção padrão. Ao expor estatísticas internas, o agente pode explicar por que um determinado comportamento ocorreu.
Suponha que você tenha uma função que exponha estatísticas internas. Primeiro, é necessário criar 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 solicitar que o agente execute 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. Ele invoca a ferramenta, analisa a taxa de acertos e erros retornada e identifica que o front-end está buscando novamente todo o pipeline desnecessariamente, em vez de atualizar o cache local.
Como verificar flags de recursos
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 experimentos 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 solicitar que o agente execute 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 prossegue para depurar os
componentes associados à nova interface.
Inspecionar o estado global do aplicativo
Exponha a árvore de estado do ambiente de execução do 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 árvore de estado, como esta:
// 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 solicitar que o agente execute 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: o agente chama getGlobalState com o path
parâmetro. 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 separada: o agente de IA pede "estado". Você, como desenvolvedor, decide como mapear essa solicitação para sua estrutura de dados real na função
execute. - Depuração direcionada: 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ê troque as bibliotecas de gerenciamento de estado,
contanto que atualize essa função
executeúnica, 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 os 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 solicitar que o agente execute 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: o agente chama queryDatabaseTable para a
tabela de pedidos. Ele recupera o registro JSON, identifica um erro no cálculo de impostos 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 back-end. - Depuração acionável: se um agente de IA identificar um bug na interface, ele poderá
chamar
queryDatabaseTableimediatamente para verificar se o erro existe nos dados de origem ou no cálculo do front-end. - Configuração mínima: você só precisa expor um endpoint de depuração "seguro" (somente leitura) no servidor que aceite um nome de tabela e retorne JSON. O framework usado para criar esse endpoint não importa.