Gli strumenti per sviluppatori di terze parti consentono agli agenti di codifica di vedere oltre il DOM, le richieste di rete e i log della console. Se esponi strumenti personalizzati direttamente dal tuo sito web o framework, consenti al tuo agente di interagire con dati e stati dell'applicazione altrimenti inaccessibili.
Questi strumenti vengono creati tramite JavaScript e vengono rilevati automaticamente da Chrome DevTools per agenti al caricamento della pagina.
Informazioni sugli strumenti per sviluppatori di terze parti
Nel contesto degli agenti di codifica, gli strumenti sono funzioni già pronte che consentono agli agenti di eseguire azioni specifiche. Per DevTools per gli agenti in particolare, questi strumenti possono esporre il suo stato di runtime interno direttamente agli agenti di codifica, colmando il divario tra l'output sottoposto a rendering e la logica interna.
Quando utilizzi strumenti di terze parti, tieni presente quanto segue:
- Rilevamento di runtime. Gli strumenti vengono rilevati automaticamente quando l'applicazione risponde all'evento
devtoolstooldiscoveryemesso da Chrome DevTools per gli agenti nell'oggetto globalewindow. - Ambito del contesto. Gli strumenti vengono eseguiti solo nel contesto della pagina che li definisce. Non vengono mantenuti tra origini e ricaricamenti di pagina.
- Specificità dello strumento. Gli strumenti sono solo un modo aggiuntivo per l'agente di eseguire un'attività. Potrebbe preferire strumenti integrati o funzionalità di base del modello per soddisfare un prompt. Pertanto, rendi i nomi e le descrizioni degli strumenti il più descrittivi possibile.
Prerequisiti
Prima di implementare strumenti di terze parti, assicurati di soddisfare i seguenti requisiti:
- Chrome DevTools per agenti. Utilizza la versione 0.25.0 o successive.
- JavaScript è attivato. JavaScript sia attivato e in esecuzione.
Implementare uno strumento
Per implementare uno strumento, ascolti un evento di rilevamento specifico e rispondi con le definizioni dello strumento. Il seguente codice rappresenta una risposta che include le definizioni degli strumenti:
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;
},
},
],
});
},
);
Per registrare gli strumenti nella tua applicazione:
Definisci il gruppo di strumenti. Crea un
ToolGroupche contenga un nome, una descrizione e un array di definizioni di singoli strumenti.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }Ascolta l'evento di rilevamento. Chrome DevTools per agenti invia un evento
devtoolstooldiscoverypersonalizzato sull'oggettowindowglobale dopo ogni navigazione e ogni volta che ha bisogno di un elenco aggiornato di strumenti disponibili.Registra i tuoi strumenti. Chiama il metodo
respondWith()dell'evento per fornire il tuo gruppo di strumenti all'agente.
Componenti essenziali per i singoli strumenti
Ogni definizione di strumento che implementi deve includere le seguenti tre parti:
- Nome e descrizione. Queste forniscono le istruzioni che l'agente utilizza per decidere quando e come chiamare il tuo strumento.
- Schema di input. Uno schema JSON che definisce la struttura e i tipi di argomenti previsti dallo strumento.
- Funzione di esecuzione. Il codice JavaScript effettivo eseguito sulla pagina quando l'agente richiama lo strumento.
L'esempio seguente mostra questi tre componenti in una singola definizione di strumento:
{
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;
},
}
Casi d'uso per gli strumenti per sviluppatori di terze parti
Chiedi all'agente di esaminare la logica dell'applicazione in modo approfondito anziché solo gli elementi UI a livello di superficie. Utilizza questi strumenti personalizzati per semplificare il debug di applicazioni stateful o basate su framework.
Suggerimenti per la scoperta degli strumenti
Scrivi nomi e descrizioni degli strumenti ricchi di dettagli. Gli agenti utilizzano queste descrizioni come contesto per decidere quale strumento utilizzare. Un linguaggio chiaro aiuta l'agente a determinare autonomamente quando uno strumento è appropriato per un'attività.
Esegui il debug delle metriche di runtime specifiche dell'applicazione
Problemi come errori di cache silenziosi o chiamate API ridondanti sono spesso invisibili all'ispezione standard. Mostrando le statistiche interne, l'agente può spiegare perché si è verificato un determinato comportamento.
Supponiamo di avere una funzione che espone statistiche interne; per prima cosa, devi creare uno strumento come questo:
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 la descrizione dello strumento è chiara, l'agente potrebbe utilizzarlo autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
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.
Esecuzione dell'agente di esempio:l'agente rileva lo strumento getCacheStatistics
esposto dalla tua applicazione. Invoca lo strumento, analizza il rapporto hit/mancata corrispondenza restituito e identifica che il frontend sta recuperando inutilmente l'intera pipeline anziché aggiornare la cache locale.
Controllo dei flag funzionalità
Definisci punti dati personalizzati per esporre le variabili di ambiente o i flag delle funzionalità attivi per una sessione utente specifica. In questo modo puoi eseguire il debug e capire perché determinate funzionalità sono o non sono visibili a utenti specifici. Se un utente segnala un bug, l'agente può verificare se fa parte di un gruppo sperimentale che potrebbe causare il problema.
Ad esempio, crea uno strumento come questo per restituire lo stato del flag di funzionalità interno:
// 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 la descrizione dello strumento è chiara, l'agente potrebbe utilizzarlo autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
Esecuzione dell'agente di esempio: l'agente richiama lo strumento getFeatureFlags,
conferma che il flag new-ui-enabled è attivo e procede al debug dei
componenti associati alla nuova interfaccia.
Ispeziona lo stato globale dell'applicazione
Esporre l'albero dello stato di runtime dell'applicazione per aiutare l'agente a comprendere la logica interna senza recuperare l'intero DOM.
Potresti creare uno strumento come questo per eseguire query su percorsi specifici nell'albero degli stati, ad esempio:
// 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 la descrizione dello strumento è chiara, l'agente potrebbe utilizzarlo autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
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.
Esecuzione dell'agente di esempio: l'agente chiama getGlobalState con il parametro path. Recupera l'elenco degli articoli dal carrello e identifica una
discrepanza tra lo stato interno e gli articoli visualizzati nella pagina.
Alcune note importanti relative a questo esempio di strumento:
- Logica disaccoppiata: l'agente AI chiede lo "stato". In qualità di sviluppatore,
decidi come mappare la richiesta alla struttura dei dati effettivi nella
funzione
execute. - Debug mirato: includendo il parametro
path, l'agente può evitare di estrarre l'intero albero degli stati (che potrebbe essere enorme) e concentrarsi solo sulla parte pertinente, risparmiando token e migliorando le prestazioni. - Interfaccia standardizzata: anche se cambi le librerie di gestione dello stato,
se aggiorni questa funzione
execute, l'agente di debug AI non avrà bisogno di nuove istruzioni o strumenti.
Ispezionare i contenuti del database
Verifica che i dati di backend corrispondano allo stato della UI eseguendo query sui record del database direttamente tramite un endpoint di debug di sola lettura.
Esporre un endpoint di debug sicuro e creare uno strumento come questo per verificare i record di backend:
// 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 la descrizione dello strumento è chiara, l'agente potrebbe utilizzarlo autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
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.
Esecuzione dell'agente di esempio: l'agente chiama queryDatabaseTable per la
tabella degli ordini. Recupera il record JSON, identifica un errore nel calcolo delle imposte del backend e suggerisce una correzione per la logica del server.
Alcune note importanti relative a questo esempio di strumento:
- Sicurezza e autenticazione: non devi trasmettere le credenziali del database
all'agente AI. La chiamata
fetchutilizza la sessione di accesso corrente del browser per autorizzare la richiesta sul backend. - Debug eseguibile: se un agente AI identifica un bug dell'interfaccia utente, può
chiamare immediatamente
queryDatabaseTableper verificare se l'errore esiste nei dati di origine o nel calcolo del frontend. - Configurazione minima: devi esporre un solo endpoint di debug "sicuro" (di sola lettura) sul server che accetta un nome di tabella e restituisce JSON. Il framework che utilizzi per creare l'endpoint non ha importanza.